Configure Client Certificate or Smart Card Authentication

Smart cards are physical devices used to identify users in secure systems. These cards can be used to store certificates both verifying the user's identity and allowing access to secure environments.

OMi can be configured to use these certificates in place of the standard model of each user manually entering a user name and password. You define a method of extracting the user name from the certificate stored on each card.

When using smart cards with OMi, users can only log in using the smart card. The option of logging in by manually typing in your log-in user name and password is locked for all users unless smart card configuration is disabled.

1. Make sure OMi is already configured and running.

2. Create an OMi super-admin user and optionally other OMi users:

   1. Log into OMi and navigate to user management:

      Administration > Users > Users, Groups, and Roles

      Alternatively, click Users, Groups, and Roles.

   2. Create a new user and click Super-Admin to assign all permissions to the user.

      Create additional users as required.

   3. Take note of each user's log-in name (case sensitive). The user log-in value must be embedded in an attribute in the client certificate. When you run the configuration wizard you choose the attribute.

3. Obtain certificates from your Certificate Authority (CA):

   1. Obtain the root CA certificate and any intermediate CA certificates of the CA.

   2. Obtain client authentication certificates from your CA for each OMi user. Make sure the certificates include the user's log-in credentials in one of the certificate attributes. When you run the configuration wizard you choose the attribute that contains the log-in credentials.

      Note We recommend using the strongest currently available cryptographic algorithms when obtaining client certificates, as well as the largest key size (not less than 2048-bit RSA keys). To see the latest NIST approved cryptographic algorithms and key lengths, go to http://csrc.nist.gov/publications/PubsFIPS.html.

   3. Verify that the client authentication certificate is correct.

      1. Double-click the client authentication certificate that is installed on your machine. The Certificate dialog box opens.

      2. Click the Details tab.

      3. Click Enhanced Key Usage.

      4. Verify that the Client Authentication object identifier (OID) is 1.3.6.1.5.5.7.3.2.

         

4. If your OMi front-end server is a load balancer or reverse proxy, perform the following steps:

   1. Follow the standard procedures for requiring a client authentication certificate specified on your reverse proxy. For details, see the third party documentation of your reverse proxy.

   2. Pass the client authentication certificate details in a header to the OMi gateway server.

      This procedure describes the general settings that are required, but you may need to see the web server documentation for the details. For details, see How to manually configure reverse proxy for smart cards.

5. Stop OMi.

6. Start the OMi configuration wizard:

   <OMi_HOME>/bin/config-server-wizard.[bat|sh]

7. Proceed through the wizard. In the Client Certificate Authentication page, select the authentication option:

   • Authentication on OMi web server.

     1. Select the certificate of the CA that issued the client certificate. The certificate file must be PEM-encoded.

        If you have more than one CA certificate issuer for the client authentication certificates (for example, there is an intermediate CA) follow the instructions below:

        • Apache. Create a chain certificate of the certificates in .PEM format.

     2. Choose how OMi checks whether the client certificate has been revoked:

        None. OMi does not check the revocation status.

        OCSP URL from certificate. OMi sends an OCSP request to the URL provided in the client certificate and evaluates the OCSP response to determine the revocation status of the certificate.

        Local CRL file (PEM-encoded). OMi checks the revocation status in a CRL file local to the gateway server. Make sure the CRL file on the gateway server is the latest one available from your CA.

        Tip The following example converts a revocation list from CRL to PEM format:

        <OMi_HOME>/WebServer/bin>openssl crl -inform DER -outform PEM -in <path to .crl> -out <path to .pem to be created>

     3. Specify the certificate data that is used for authentication:

        Attribute used to identify users. If Subject has an attribute called E, Email, emailaddress, email address, e-mail address, e-mailaddress, rfc822 name, or rfc822name, select SubjectDN in the Attribute used to identify users field, and enter the value of the attribute in the Relevant part of the attribute field.

        Relevant element of attribute field (for example, CN). If the Subject does not contain one of the attributes listed above, select Subject Alternative Name in the Attribute used to identify users field, and enter the attribute name (not its value) in the Relevant part of the attribute field. The attribute name may be one of the following: Principal Name, Principalname, other name, principalname, principal name, or Microsoft principal name.

        Tip When defining the Relevant part of the attribute field, the attribute must be the user's unique identifier. You can find the certificate attributes in the certificate details. In Internet Explorer, these can be viewed from Tools > Internet Options > Content > Certificates > Personal > Details > Subject or Subject Alternative Name.

     4. Optional. Click Enforce use of smart card certificates to configure OMi to always require a smart card when a user logs on.

     5. Click Next to continue.

   • Authentication on load balancer.

     1. Specify the certificate data that is used for authentication:

        Attribute used to identify users. If Subject has an attribute called E, Email, emailaddress, email address, e-mail address, e-mailaddress, rfc822 name, or rfc822name, select SubjectDN in the Attribute used to identify users field, and enter the value of the attribute in the Relevant part of the attribute field.

        Relevant element of attribute field (for example, CN). If the Subject does not contain one of the attributes listed above, select Subject Alternative Name in the Attribute used to identify users field, and enter the attribute name (not its value) in the Relevant part of the attribute field. The attribute name may be one of the following: Principal Name, Principalname, other name, principalname, principal name, or Microsoft principal name.

        Tip When defining the Relevant part of the attribute field, the attribute must be the user's unique identifier. You can find the certificate attributes in the certificate details. In Internet Explorer, these can be viewed from Tools > Internet Options > Content > Certificates > Personal > Details > Subject or Subject Alternative Name.

     2. Optional. Click Enforce use of smart card certificates to configure OMi to always require a smart card when a user logs on.

     3. Click Next to continue.

8. Complete the remaining wizard pages and enable OMi again.

9. Enable smart card authentication on the data collector or component servers. For details, see the following help centers:

   • OpsCx. See the OpsCx Help.

   • SiteScope. See the SiteScope Help.

10. Distribute the client certificates to the OMi users and data collectors.

This procedure describes the general settings that are required, but you may need to refer to the web server documentation for the details. It must be performed before you restart your OMi gateway servers to enable smart card authentication.

For the Apache web server:

1. Prerequisite. Apache is already configured to require a client certificate.

2. In httpd.conf, enable the mod_headers.so

3. In httpd-ssl.conf, add the following line before </VirtualHost>:

   requestHeader set CLIENT_CERT_HEADER "%{SSL_CLIENT_CERT}s"

In some cases, the OMi server itself acts as a client with respect to other servers and must provide a client authentication certificate. If this is the case, it must be performed only once.

For example, this is required when a data collector such as SiteScope requires a client authentication certificate (for example, when smart cards authentication is required by the data collector).

1. Obtain software client authentication certificate from your CA issued to a user with appropriate permissions for this integration. You can use one of the certificates you obtained in the beginning of the How to configure client certificate or smart card authentication.

2. If the certificate is not already in Java keystore (JKS) format, convert it to JKS.

   For example, if your certificate is in PFX format, you can convert it to JKS format as seen in the following example: 

   keytool.exe -importkeystore -srckeystore c:\certificate.pfx -destkeystore c:\certificate.jks -srcstoretype PKCS12

3. Open <OMi_HOME>/application-server/bin/standalone.conf[.bat|.sh] on all OMi gateway and data processing servers and make the following changes on each server:

   1. Locate the following line in the file:

      set "JAVA_OPTS=%JAVA_OPTS% ‑Dtopaz.home=%PRODUCT_HOME_PATH%"

   2. Insert the following lines right after the line:

      set SECURITY_OPTS=‑Djavax.net.ssl.keyStore=<path to certificate.jks> ‑Djavax.net.ssl.keyStorePassword=<keystore password> ‑Djavax.net.ssl.keyStoreType=JKS

      set JAVA_OPTS=%JAVA_OPTS% %SECURITY_OPTS%