4.2 Configuring Mutual SSL (X.509) Authentication

Mutual authentication is used when a user is issued an X.509 certificate from a trusted source, and the certificate is then used to identify the user. To ensure the validity of the certificates, Access Manager supports both Certificate Revocation Lists (CRLs) and Online Certificate Status Protocol (OCSP) methods of verification.

To configure X.509 authentication, you need to create an authentication class, then configure the validation and attribute mapping options.

  1. Log in to the Administration Console.

  2. Import the trusted root certificate or certificate chain of the Certificate authority into the Identity Server trusted root store.

    For information on how to import trusted roots, see Importing Public Key Certificates (Trusted Roots) in the NetIQ Access Manager 3.1 SP5 Administration Console Guide.

    The Identity Server must trust the Certificate authority that created the user certificates.

  3. To create the X.509 authentication class, click Devices > Identity Servers > Edit > Local > Classes.

  4. Click New.

  5. Specify a display name, then select X509Class from the drop-down menu.

  6. Click Next.

    Specifying X.509 validations
  7. Configure the validation options:

    Validations: The validation type. Trust validation occurs if the certificate chain is verified in the NIDP Trust Store. In addition to usual certificate validations, the Identity Server supports CRL (certificate revocation list) and OCSP (Online Certificate Status Protocol) validations for each authentication request.

    Access Manager caches CRLs, so the revoked status of a newly revoked certificate is not picked up until the next cache refresh. For higher security requirements, use OCSP validation with CRL validation. You can select None, CRL, OCSP, OCSP-CRL, or CRL-OCSP validation. In a production environment, for highest security, select either OCSP-CRL or CRL-OCSP validation. The default setting is to check OCSP first, then CRL.

    CRL Validation: Checks the CRL. If you enable CRL validations, the CRL distribution point extension is read out of the user’s X.509 certificate. The CRL distribution point contains the URL where the complete CRL can be found, as published by the certificate authority. The system checks the CRL itself and then checks to see if the user certificate is in the revoked list. The system can get the CRL over HTTP and LDAP. If you are not expecting the distribution point in user certificates, you can specify a value in the LDAP URL option to get the CRL.

    Access Manager supports two schemes for a URL: http:// and ldap://.

    OCSP Validation: If OCSP validation is enabled, the Authority Info Access point (AIA) is read out of the user certificate, which contains the URL for the OCSP responder. A signed OCSP request for the user certificate is sent to OCSP responder. A signed OCSP response is received from the responder that has the revoked status for the user certificate. Alternately, if you are not expecting an AIA in a user certificate, you can specify a value in the OCSP responder URL field. The value you enter here overrides any OCSP responder URLs in a certificate.

    Access Manager supports two schemes for a URL: http:// and ldap://.

    Disable Root CA Revocation Check: Disables whether to check if a certificate authority has been revoked. This option checks the CRL and OCSP for the trusted root certificate in the chain. You can enable or disable this option for X.509 user authentication performance.

    If you enable the root CA revocation check, what the Identity Server checks depends upon the certificates that have been added to the Identity Server trust store. If the root certificate and the intermediate certificates in the chain are in the trust store, the Identity Server only validates the client (leaf) certificate. If the trust store only contains the root certificate, the browser sends the intermediate and leaf certificates, which are then validated by the Identity Server.

  8. Configure the trust stores:

    NIDP Trust Store: This trust store must contain the trusted root certificate of the certificate authorities that signed your user certificates. Click this link to add certificates to the trust store.

    OCSP Trust Store: This trust store must contain the signing certificate of the OCSP servers you want to trust. Click this link to add certificates to the trust store. You must add the signing certificate, not the trusted root certificate, for this feature to work.

  9. Configure the browser restart option.

    Some browsers, such as Internet Explorer, keep the SSL session active until the user closes the browser. When the user logs in with the certificate on a smart card, then removes the card and logs out but does not close the browser, the SSL session is still active. If another user has access to the machine, that user can use the existing session.

    To prevent this from happening, enable the Force browser restart on logout option.

  10. Click Next.

  11. Continue with Section 4.2.1, Configuring Attribute Mappings.

4.2.1 Configuring Attribute Mappings

The attribute mapping options allow you to specify how the Identity Server maps the certificate to a user in the user store. Subject name is the default map.

  1. Step 3 of the wizard or click Devices > Identity Servers > Edit > Local > Classes > [Name of X.509 class] > Properties > Attributes.

  2. Configure attribute mappings.

    Specifying attribute mappings for X.509

    Show certificate errors: Displays an error page when a certificate error occurs. This option is disabled by default.

    Auto Provision X509: Enables using X.509 authentication for automatic provisioning of users. This option allows you to activate X.509 for increased security, while using a less secure way of authentication, such as username/password. Extra security measures can even include manual intervention to activate X.509 authentication by adding an extra attribute that is checked during authentication.

    An example of using this option is when a user authenticates with an X.509 certificate, a lookup is performed for a matching SASallowableSubjectNames with the name of the user certificate. When no match is found, and Auto Provision X509 is enabled, the user is presented with a custom error page specifying to click a button to provide additional credentials, such as a username and password, or to start an optional Identity Manager workflow. If the authentication is successful, then the user’s SASallowableSubjectNames attribute is filled in with the certificate name of the user certificate.

    When Auto Provision X509 is enabled, and the attribute that is used for subject name mapping is changed from the default sasAllowableSubjectNames, you need to ensure that the LDAP attribute that is used can store string values with a length as long as the longest client certificate subject name. For example, if you use the LDAP attribute title (which has an upper bound of 64 characters) the Auto Provision X509 fails the provisioning part of the authentication if the client certificate subject name is longer 64 characters. The authentication works if a valid name and password is given. However, provisioning fails.

    Attributes: The list of attributes currently used for matching. If multiple attributes are specified, the evaluation of these attributes should resolve to only one user in the user store.

    The evaluation first does a DN lookup for subject name or directory name mapping. If this fails, the rest of the mappings are looked up in a single LDAP query.

    Available attributes: The available X.509 attributes. To use an attribute, select it and move it to the Attributes list. When the attribute is moved to the Attributes list, you can modify the mapping name in the Attribute Mappings section. The mapped name must match an attribute in your LDAP user store.

    Directory name: Searches for the directory address in the client certificate and tries to match it to the DN of a user in the user store. If that fails, it searches the sasAllowableSubjectNames attribute of all users for a value that matches. The sasAllowableSubjectNames attribute must contain values that are comma-delimited, with a space after the comma. (For example, O=CURLY, OU=Organization CA or OU=Organization CA, O=CURLY.)

    Email: Searches for the email attribute in the client certificate and tries to match it with a value in the LDAP mail attribute.

    Serial number and issuer name: Lets you match a user’s certificate by using the serial number and issuer name. The issuer name and the serial number must be put into the same LDAP attribute of the user, and the name of this attribute must be listed in the Attribute Mappings section.

    When using a Case Ignore String attribute, both the issuer name and the serial number must be in the same attribute separated by a dollar sign ($) character. The issuer name must precede the $ character, with the serial number following the $ character. Do not use any spaces preceding or following the $ character. For example: O=CURLY, OU=Organization CA$21C0562C5C4

    The issuer name can be from root to leaf or from leaf to root. The issuer name must be comma-delimited with a space after the comma. (For example, O=CURLY, OU=Organization CA or OU=Organization CA, O=CURLY.)

    The serial number cannot begin with a zero (0) or with a hexadecimal notation (0x). If the serial number is 0x0BAC05, the value of the serial number in the attribute must be BAC05. The certificate number is displayed in Internet Explorer with a space after every fourth digit. However, you should enter the certificate number without using spaces.

    The LDAP attribute can be any Case Ignore List or Case Ignore String attribute of the user. If you are configuring your own attribute, ensure that the attribute is added to the Person class. When using a Case Ignore List attribute, both the issuer name and the serial number must be in the same list. The issuer name needs to be the first item in the list, with the serial number being the second and last item in the list.

    Subject name: Searches for the Subject name of the client certificate and tries to match it to the DN of a user in the user store. If that fails, it searches the sasAllowableSubjectNames attribute of all users for a value that matches the Subject name of the client certificate. The sasAllowableSubjectNames attribute must contain values that are comma-delimited, with a space after the comma. (For example, O=CURLY, OU=Organization CA or OU=Organization CA, O=CURLY.)

  3. Click Finish.

  4. Create a method for this class.

    For instructions, see Section 3.3, Configuring Authentication Methods.

  5. Create a contract for the method:

    For instructions, see Section 3.4, Configuring Authentication Contracts.

    If you want the user’s credentials available for Identity Injection policies, add the password fetch method as a second method to the contract. For more information about this class and method, see Section 4.5, Configuring Password Retrieval.

  6. Update the Identity Server.

4.2.2 Setting Up Mutual SSL Authentication

SSL provides the following security services from the client to the server:

  • Authentication and nonrepudiation of the server, using digital signatures

  • Data confidentiality through the use of encryption

  • Data integrity through the use of authentication codes

Mutual SSL provides the same things from the server to the client as SSL. It provides authentication and nonrepudiation of the client, using digital signatures.

  1. Set up Access Manager certificates for security, and import them into the Access Manager system. (See Creating Certificates in the NetIQ Access Manager 3.1 SP5 Administration Console Guide.)

  2. Create an X.509 authentication class. (See Section 4.2, Configuring Mutual SSL (X.509) Authentication.)

  3. Create an authentication method using this class. (See Section 3.3, Configuring Authentication Methods.)

  4. Create an authentication contract using the X.509 method. (See Section 3.4, Configuring Authentication Contracts.)

  5. Update the Identity Server cluster configuration. (See Section 15.1.1, Updating an Identity Server Configuration.)

  6. Update any associated Access Gateways to read the new authentication contract.

  7. Assign the contract to protect resources.

    See Configuring Protected Resources in the NetIQ Access Manager 3.1 SP5 Access Gateway Guide.

  8. Update the Access Gateway.