Web Services Security Guides › CA SiteMinder WSS Policy Configuration Guide › Configure Authentication Schemes to Verify User Identities Obtained from Web Service Requests › How to Configure XML DSIG Authentication to Verify User Identities Associated with X.509 Certificates

How to Configure XML DSIG Authentication to Verify User Identities Associated with X.509 Certificates

Configure an XML Digital Signature (XML DSIG) authentication scheme to verify user identities that are associated with the X.509 certificates used to sign XML request messages.

To use an X.509 certificate to identify a user, the XML DSIG authentication scheme uses a certificate mapping to compare a certificate with a user in a user directory. A certificate mapping defines how data in the certificate is mapped to form a user Distinguished Name (DN), which the Policy Server uses to authenticate the client.

To configure CA SiteMinder WSS to validate user identities using XML DSIG authentication, complete the following process:

1. Verify required XML document elements for XML-DSIG authentication
2. Configure the XML DSIG authentication scheme
3. Configure a certificate mapping

Verify Required XML Document Elements for XML-DSIG Authentication

For the XML-DSIG authentication scheme to work, the XML document sent by the web service consumer must contain the following elements:

<Signature>

As the parent element for the XML signature, it specifies all information relevant to the digital signature.

To verify the signature, CA SiteMinder WSS requires that an X.509 certificate be part of the <Signature> element in the XML document.

Because the Policy Server does not interact with a Certificate Authority for this scheme, you must configure a certificate mapping that maps the Issuer DN in the certificate to a corresponding entry in the referenced user store. For LDAP user directories only, you can configure the certificate mapping to require that a copy of the certificate is in the user store to be compared against the certificate in the document.

<KeyInfo>

This element specifies the key needed to validate the signature. This information may include keys, names, and certificates for the sender.

For the Policy Server to authenticate a client, this element must have enough information to determine the public key that created the signature.

<KeyName>

This is a child element of <KeyInfo>; it contains a string value that identifies the key to the recipient of the XML document. This string could be a key index, a distinguished name (DN), or an email address, for example.

The Policy Server maps the value of this element to an entry in the user store.

More information:

Certificate Mapping for X.509 Client Certificate Authentication Schemes

Configure the XML DSIG Authentication Scheme

To obtain authentication information from digital signatures associated with incoming XML documents, you configure the XML DSIG authentication scheme.

Follow these steps:

1. Click Infrastructure, Authentication.
2. Click Web Services Authentication Schemes, Create Authentication Scheme.

   The Create Authentication Scheme pane opens.

   Authentication scheme settings open.

3. Enter a name and a description for the scheme in the General group box.
4. Select XML Digital Signature from the Authentication Scheme list.
5. Specify a protection level.
6. In the Scheme Setup group box, select how much of the XML document content is signed. A digital signature can apply only to one portion of an XML document. The choices are as follows:
   • Must cover the entire document
   • Must cover the body of the message
   • Only needs to apply to headers

   Note: If the XML document uses raw XML, select the Must cover entire document option, because the entire document is the payload. With raw XML, no envelope headers or body tags exist to distinguish the payload from other content.

7. To perform authentication over an SSL connection, select the Require Secure Transport Layer check box.
8. Click Submit.

   The authentication scheme is saved. You can now assign it in application object components or realms.

9. Configure certificate mapping for the XML-DSIG scheme.

   A certificate mapping defines how data in the certificate is mapped to form a user Distinguished Name (DN), which the Policy Server uses to authenticate the client.

Configure a Certificate Mapping

To determine how to compare user certificate information with the information stored in the user directory, configure a certificate mapping.

Follow these steps:

1. Click Infrastructure, Directory.
2. Click Certificate Mappings.
3. Click Create Certificate Mapping.
4. Type the Issuer DN exactly as it appears in the certificate. Do not add any additional spaces or characters.

   When entering the DN, escape reserved special characters with a backslash (\). Special characters include:

   • semicolons (;)
   • quotes (")
   • backslashes (\)
   • plus character (+)
   • greater than character (>)
   • less than character (<)

   More information about reserved special characters for DNs exists at http://www.faqs.org/rfcs/rfc2253.html.

   Note: If you use a relational database as a policy store, Issuer DNs cannot exceed 255 characters. If you use an LDAP directory as a policy store, verify the character limit for your specific directory.

5. Select the directory type against which the certificate is mapped.

   For LDAP directories only, you can configure the Policy Server to verify that the certificate the user presents matches the certificate that is stored in the user record in the user directory. The Certificate Required in Directory option lets you require this verification.

   Note: The attribute in the user record where the certificate is stored is named usercertificate.

6. Specify how to map X.509 user certificate information to a user entry in the user directory. The Policy Server can apply a mapping using one of the following properties to locate the correct user entry:
   • A single attribute
   • A custom mapping expression
   • The entire Subject Name from the user certificate
7. Select an attribute name from the list.
8. Click Test to test the certificate mapping.
9. (Optional) Select Perform CRL Checks and specify the CRL settings.

   If you do not select CRLs, you can use OCSP.

10. Click Submit.

    The certificate is mapped with the selected user directory.

More information:

Certificate Validity Checking for X.509 Client Certificate Authentication

Note: For more information about certificate mapping, including how to test a mapping and configure custom mapping expressions, see Certificate Mapping for X.509 Client Authentication Schemes in the Policy Server Configuration Guide.