4.1.7 Mutual SSL (X.509) Authentication

In mutual authentication, a trusted source issues an X.509 certificate and the certificate is 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.

Configuring X.509 Authentication

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

  1. Log in to Administration Console.

  2. Import the trusted root certificate or certificate chain of the certificate authority (CA) into Identity Server trusted root store.

    For more information, see Importing Public Key Certificates (Trusted Roots).

    Identity Server must trust the CA that created the user certificates.

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

  4. Specify a display name, then select X509Class from the list.

  5. Click Next.

  6. Configure the following validation options:

    Option

    Description

    Validations

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

    Access Manager caches CRLs. The 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, select OCSP-CRL or CRL-OCSP validation for highest security. 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 on 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

    Select to disable checking if a certificate authority has been revoked. This option checks 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 do not select this option, checks performed by Identity Server depends on 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, 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 Identity Server.

  7. Under Trusted Roots for Validation, click New and add the trusted roots that you want to use in the authentication. Access Manager uses these trusted roots to validate the user’s identity.

    If you do not specify any trusted root, Access Manager validates the user’s certificate against the default Access Manager trusted root. For more information, see Restricting the X.509 Authentication to a Specific Certificate Authority.

  8. Select Read certificate from http header and specify the header name. This configuration is required when Identity Server is configured as a public resource behind a reverse proxy other than an Access Manager Access Gateway reverse proxy. If the proxy is configured to send the user certificate to Identity Server as part of HTTP header in the PEM encoded data, Identity Server can read this header value and completes X.509 authentication.

    For example, if Identity Server is behind Apache, add the following advanced Apache configuration with the rewrite module to send the user certificate to Identity Server through a custom header called SSL-Client-Cert.

    • SSLVerifyClient optional_no_ca

    • SSLVerifyDepth 10

    • RequestHeader set SSL-Client-Cert "%{SSL_CLIENT_CERT}s“

  9. Click Next.

  10. Continue with Configuring Attribute Mappings.

Configuring Attribute Mappings

  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.

    Option

    Description

    Show certificate errors

    Select to displays an error page when a certificate error occurs. This option is not selected by default.

    Auto Provision X509

    Select to enables automatic provisioning of users for X.509 authentication.

    This option enhances the security of X.509 authentication when using a less secure way of authentication, such as username/password. Additional security measures include manual intervention to activate X.509 authentication by adding an additional attribute that is checked during authentication. For example, when a user authenticates with an X.509 certificate, Access Manager looks up for a matching SASallowableSubjectNames with the name of the user certificate. If no match is found and Auto Provision X509 is enabled, an error page is displayed that prompts the user to specify additional credentials such as a username/password or to start an optional Identity Manager workflow. If the authentication is successful, the user’s SASallowableSubjectNames attribute is filled with the 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, ensure that the LDAP attribute that is used can store string values 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 than 64 characters. The authentication works if a valid name and password is given, but provisioning fails.

    Attributes

    Select attributes from Available attributes used for matching. If multiple attributes are specified, the evaluation of these attributes must resolve to only one user in the user store.

    Access Manager 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 list of available X.509 attributes. To use an attribute, select it and move it to Attributes.

    • 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 must 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 on the same list. The issuer name needs to be the first item on the list, with the serial number being the second and last item on 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.)

    Attribute Mappings

    This option allows you to specify how Identity Server maps the certificate to a user in the user store. Subject name is the default map.

    When an attribute is moved to Attributes, you can modify the mapping name here. The mapped name must match an attribute in your LDAP user store.

    You can also configure regular expression for attributes to use a partial value of the X.509 certificate attribute for searching users. See Regular Expression for Extracting the Partial String from DN.

  3. Click Finish.

  4. Create a method for this class.

    During step-up authentication with X509 method as primary method, if a user specifies a different username while authentication for secondary method, an error is displayed. While configuring a method, configure the following property to enable customizing this error message.

    Property: PRINCIPAL_MISMATCH_ERR

    Value: provide string to display on user principal mismatch

    If this property is not configured, the default intruder detection error is displayed to users.

    For instructions, see Section 4.1.3, Configuring Authentication Methods.

  5. Create a contract for the method:

    For instructions, see Section 4.1.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. See Password Retrieval.

  6. Update Identity Server.

Restricting the X.509 Authentication to a Specific Certificate Authority

In an ideal mutual authentication scenario, a user gets an X.509 certificate from a trusted CA. The CA is imported to the Access Manager trust store and Access Manager uses the same CA for authenticating this user.

Access Manager trust store contains many other trusted certificate authorities. If the user submits a certificate issued by a different CA that is trusted by Access Manager, the authentication succeeds. In some scenarios, this behavior is not suitable, such as when smart cards and X.509 authentications are used in an enterprise. You can restrict this behavior and configure to allow the X.509 authentication only for configured CA. After enabling the restriction, the mutual authentication succeeds only when a user submits an X.509 user certificate issued by the specified CA. This restriction does not restrict the certificates available on the client side. This restriction is only applicable during processing or validating the certificates.

For example, an organization has two departments: HR and Finance. Each department issues smart cards to its respective employees. In Access Manager, contracts are configured for both departments as follows:

Department

Contract

CA

HR

X509_HR

CA_HR

Finance

X509_Finance

CA_ Finance

Employees of the HR department use the certificate signed by CA_ HR and employees of the Finance department use the certificate signed by CA_ Finance. Both certificates are imported into the trust store.

If not specified, Access Manager does not validate certificates with any specific CA. In this case, employees can authenticate with any certificate that is imported to the trust store irrespective of the contracts they use. As a result, employees of the HR department can use the certificate signed by CA_ Finance and employees of the Finance department can use the certificate signed by CA_ HR for authentication.

When you specify the CA, Access Manager validates the certificates with the configured CA. Therefore, you can restrict employees of the HR department to use the X509_ HR contract and employees of the Finance department to use the X509_ Finance contract. Access Manager validates the certificate with the CA configured in the Access Manager authentication method property.

For information about configuring X.509 authentication, see Configuring X.509 Authentication.

Regular Expression for Extracting the Partial String from DN

By default, Access Manager uses the complete string of the X.509 certificate attribute to identify a user in the userstore. When the X.509 subject name contains a long DN or string, you can configure regular expression (regex) to extract the partial value. You can configure regex for the following attributes of the certificate:

  • Subject name
  • Directory name
  • Email
  • Serial number and issuer name

If the subject of the certificate is fully qualified DN, Access Manager can use the CN value or ignore it while searching for a user. You can also configure regex for each attribute that is available with the X.509 certificate configuration.

You can configure regex while creating an X.509 class. See Attribute Mappings.

For example, the X.509 subject is EMAILADDRESS=martial@novell.com, CN=martial, OU=NTS, O=MF, L=Malahide, ST=Dublin

To retrieve the martial CN value, you can use regex (?<=CN=)([^,]+).

The expression CN=(.*?) matches the common name field. So, if the subject name in the certificate is "CN=martial, OU=...", this will give a username “martial". The matches are case-sensitive.

"EMAILADDRESS =(.*?)," will match "EMAILADDRESS=martial@novell.com,CN=... “ and will give username “martial@novell.com”.

OU=(.*?)(?:,|$) will match “EMAILADRESS=martial@novell.com,CN=..,OU=NTS...” and match value to “NTS”.

For more information about regex, see Regular Expression.info and for editing and testing a regex, you can try Online Regex Tester or Regexr.

Setting Up Mutual SSL Authentication

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

  • Authentication and non-repudiation 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 non-repudiation of the client, using digital signatures.

  1. Set up Access Manager certificates for security, and import them into the Access Manager system. (See Section 15.0, Creating Certificates.)

  2. Create an X.509 authentication class. (See Mutual SSL (X.509) Authentication.)

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

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

  5. Update Identity Server cluster configuration. (See Updating Identity Server Configuration.)

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

  7. Assign the contract to protect resources.

    See Section 2.6.5, Configuring Protected Resources.

  8. Update Access Gateway.

Customizing Certificate Errors

When certificate validation fails, the browser displays a standard Page expired error. If you want Identity Server to display an Access Manager error instead of the usual error messages provided by the browser, edit the /opt/novell/nam/idp/conf/server.xml by using the following steps:

  1. Search for the clientAuth attribute in the server.xml file.

  2. Modify the value of the clientAuth attribute from the default value of false to want.

    NOTE:If you use clientAuth=want in a connector, ensure that the connector contains protocol="org.apache.coyote.http11.Http11Protocol".

  3. Save the file and restart Identity Server by using the rcnovell-idp restart command.

    This setting ensures that the certificate is exchanged between the client and the server.

  4. Export the certificate of the user and the server from Administration Console by using the Security > Certificates option.

    To avoid the untrusted certificate messages in browsers, import the trusted root certificate of the CA into your browsers. See Resolving Certificate Import Issues.

Configuring X.509 Authentication to Display the Access Manager Error Message

You can configure the X.509 authentication class to avoid the browser provided message and display the Access Manager error message. This error message is displayed when the SSL mutual handshake fails because of non-availability of the client certificate. To display the Access Manager specific error message during X.509 authentication, you must configure a dual connector setup in Identity Server.

Configuring a Dual Connector Setup in a Single-Node Identity Server Environment

IMPORTANT:Add the DNS name of the second connector in the browser exception list or proxy settings.

You can specify the port and URL name as per your environment. The URL name and port number specified in the following procedure is an example.

Prerequisite:You must have a parent domain and a sub-domain.

For example, you must have the following domains:

Parent Domain: https://240onbox.nam.example.com:8443/nidp/

Sub-Domain: https://onbox.nam.example.com:8443/

To create a sub-domain, create a secondary Ethernet in Identity Server with the IP address that you want to create the sub-domain.

Perform the following steps to configure a dual connector setup:

  1. In Identity Server, navigate to the /opt/novell/nam/idp/conf directory.

    1. Open the server.xml file.

    2. Search the <Connector NIDP_Name="connector" string and create a copy of the existing connector in the same file.

    3. In the new connector, change the port number to 8448.

    4. Change the clientAuth="false" string to clientAuth="want".

    5. Add protocol="org.apache.coyote.http11.Http11Protocol".

    6. Save the server.xml file.

  2. Navigate to the /opt/novell/nids/lib/webapp/META-INF/ directory and open the context.xml file.

  3. Change Tomcat context.xml to set a same cookie for sub-domains. Ensure that the path is set to "/" as follows:

    <?xml version="1.0" encoding="UTF-8"?> <Context sessionCookiePath="/" sessionCookieDomain=".nam.example.com"> <!-- Disable session persistence across Tomcat restarts --> <Manager pathname="" saveOnRestart="false"/> </Context>

  4. Uncomment the following string in the context.xml file:

    <CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor" />

  5. Change session proxying for setting this cookie.

    1. Navigate to Devices > Identity Servers > Edit > Options.

    2. Click New and specify the following details:

      Property Name: CLUSTER COOKIE DOMAIN

      Property Value: nam.example.com

      Property Name: CLUSTER COOKIE PATH

      Property Value: /nidp

      NOTE:Before you proceed to the next step, ensure that you have configured the X.509 class, method, and contract. For information, see Mutual SSL (X.509) Authentication.

  6. Navigate to Devices > Identity Servers > Edit > Options.

  7. Select the X.509 authentication method and click New under Properties.

    Specify the following details:

    Property Name: CONNECTOR_HOST

    Property Value: https://onbox.nam.example.com:8448

    NOTE:Do not add a / after the port number.

    For X.509Class-based redirection, this property will redirect X.509 to the new connector. The DNS named onbox is a sub-domain as indicated in the prerequisite.

    Use a wildcard name for the identity server certificate. For example, *.nam.example.com.

  8. Restart Tomcat by using the following commands:

    • Linux: /etc/init.d/novell-idp restart

    • Windows:

      • net stop Tomcat8

      • net start Tomcat8

Verify the configuration as follows:

Access the Identity Server URL in a browser that does not have the client certificate. Access the X.509 authentication card and verify the behavior. It must redirect to the connector page and redirect to the original page with an Access Manager error message or error code.

Configuring a Dual Connector Setup in a Multi-Node Identity Server Environment

Let us consider that your setup details are as follows:

  • Base URL of the Identity Server cluster: https://abc.idp.com:8443/nidp

  • Value of the common name of the Certificate, cn=*.idp.com

  • Details of the Identity Server nodes:

    Identity Server

    IP Address

    Host

    Node 1

    1.1.1.10

    abc

    Node 2

    1.1.1.11

    auth

Perform the following steps to configure a dual connector setup:

NOTE:The second Identity Sever node acts as a connector host.

  1. Create an X.509 authentication class and method. See Configuring X.509 Authentication and Configuring Attribute Mappings.

  2. Navigate to Devices > Identity Servers > Edit > Local > Methods.

  3. Select the X.509 authentication method and click New under Properties.

    Specify the following details:

    Property Name: CONNECTOR_HOST

    Property Value: https://auth.idp.com:8448

    NOTE:Do not add a / after the port number.

  4. Navigate to Devices > Identity Servers > Edit > Options.

  5. Click New and specify the following details:

    Property Name: CLUSTER COOKIE DOMAIN

    Property Value: .idp.com

    Property Name: CLUSTER COOKIE PATH

    Property Value: /nidp

  6. (Identity Server Node 1 and Node 2) Back up server.xml and context.xml files located at the following paths:

    server.xml: /opt/novell/nam/idp/conf

    context.xml: /opt/novell/nids/lib/webapp/META-INF

  7. In the Identity Server Node 1, navigate to the /opt/novell/nam/idp/conf directory.

    1. Open the server.xml file.

    2. Search the <Connector NIDP_Name="connector" string and create a copy of the existing connector in the same file.

    3. In the new connector, change the port number to 8448.

      NOTE:Ensure that clientAuth="false".

    4. Save the server.xml file.

  8. In the Identity Server Node 2, navigate to the /opt/novell/nam/idp/conf directory.

    1. Open the server.xml file.

    2. Search the <Connector NIDP_Name="connector" string and create a copy of the existing connector in the same file.

    3. In the new connector, change the port number to 8448.

    4. Change the clientAuth="false" string to clientAuth="want".

    5. Add protocol="org.apache.coyote.http11.Http11Protocol".

    6. Save the server.xml file.

  9. (Identity Server Node 1 and Node 2) Navigate to the /opt/novell/nids/lib/webapp/META-INF directory and open the context.xml file.

  10. Ensure that the following strings are available:

    <Context sessionCookiePath="/" sessionCookieDomain=".idp.com"> 
    <Manager pathname="" saveOnRestart="false"/> 
    <CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor" />
</Context>

  11. Save the files and restart both the Identity Server nodes.

    NOTE:Check the log files and ensure that there are no errors.

  12. Create a user certificate. See Section 15.0, Creating Certificates.

  13. Import the certificate to the browser.

  14. Create a contract for the method. See Configuring Authentication Contracts.

Verifying the Dual Connector Setup

To verify that the dual connector setup configuration is successful, execute the X.509 dual connector contract as an end user and ensure that the CONNECTOR_HOST URL is visible in the browser URL and in the Identity Server logs.

  1. At the User Portal, select the X.509 dual connector contract.

  2. Select the user certificate when prompted.

A successful login to the User Portal verifies that the dual connector setup configuration is complete.