+

Search Tips   |   Advanced Search

Secure Sockets Layer client certificate authentication

Client software that wants to establish a secure connect to a server by using SSL protocol initiates by leveraging SSL protocol or the enhanced protocol called Transport Layer Security (TLS) to perform an SSL handshake with SSL certificates. A personal certificate can represent the server or it can represent a particular client, and is signed by a Certificate Authority (CA) to ensure that the personal certificate is correctly identified.

SSL ensures that the administrator has the CA signer certificate available used to sign the personal certificate, and that it is stored in both the client and or the server trusted store. SSL client certificate authentication takes place during the connection handshake by using SSL certificates.

The following events must occur during this process:


Configure a WebSphere server for client authentication

Client certificate authentication occurs if the server side requests that the client side send a certificate. A Websphere server can be configured for client certificate authentication on the SSL configuration. However, if client authentication is needed for IIOP then it must be configured on the CSIv2 configuration.

To configure client certificate authentication on the SSL configuration using the console:

We can also use the addSignerCertificate command to add a signer to the trust store of the server. Read SignerCertificateCommands (AdminTask) for more information about this command.

If we are using client authentication in a cluster environment, client authentication must be configured for each node that the servers in the cluster are located in.


Set up the client side for client authentication

Clients:

Administrative clients, thin clients or pure clients must have a personal certificate in their key stores. The WebSphere client default key store created when WebSphere Application Server is installed already has a personal certificate in it. This key store can be found in ssl.client.props in the com.ibm.ssl.keyStore property. The client key stores are not managed by WebSphere Application Server, so the Key Management utility (iKeyman) or Java keytool utility can be used to extract the certificate to a certificate file.

To extract a certificate using iKeyman:

  1. Start iKeyman.

  2. Select Key Database File > open.

  3. Enter the path to the keystore file. We can obtain this from ssl.client.props.

  4. Click OK.

  5. Enter the password to the key store and click OK

  6. Under Personal Certificates, select the client default certificate.

  7. Enter a path and file name for the certificate file and click OK.

The file containing the extracted certificate can be used to add the signer to the trust store of the server. Follow the steps in the "Configuring a WebSphere server for client authentication" section to add that signer to the server trust store.

If the communication is over IIOP, the following properties must be set in the sas.client.props file.

Thin clients and pure clients might not use the WAS SSL properties file, ssl.client.props. They most likely use the Java system properties to set the client key store and trust store. The signer certificate of the server must be added to the trust store specified with the java.net.ssl.trustStore system property. Keytool or iKeyman can be used to add the signer certificate. The signer must be extracted from the personal certificate in the key store specified by the javax.net.ssl.keyStore system property, and added to the trust store of the server.

For example:

Server acting as a client:

The client can be a WebSphere server acting as a client. If so, determine which SSL configuration is being used as the client side of the communication, extract it's certificate's signer and add it to the server side trust store. IBM recommends that the root certificate signer be used.

To extract the root certificate using the console:

  1. Click...

  2. Select either DmgrDefaultRootStore (for a network deployment server) or NodeDefaultRootStore (for an application server).

  3. Under Additional Properties, select Personal certificates.

  4. Select the default root certificate (usually called root), and then click Extract.

  5. In the Certificate file name box, type a full path to the file in which to hold the certificate.

  6. Click OK to save.

We can also use the extractCertificate command to extract the root certificate. Read PersonalCertificateCommands (AdminTask) for more information about this command.

The certificate file created can be carried to the server side and added to the trust store of the server.

When a server acts as a client, the client side server requires the signer from the destination server. The signer can be retrieved using the signer certificate Retrieve from port option.

To retrieve the signer from the port using the console:

  1. Click...

  2. Enter a destination host name and a destination port name. Enter an alias name for the certificate.

  3. Click Retrieve signer information.

  4. Click OK to save.

We can also use the retrieveSignerFromPort command to retrieve the signer from the port. Read SignerCertificateCommands (AdminTask) for more information about this command.

Set up a browser for client authentication:

When WebSphere Application Server is configured for client certificate authentication, and an attempt is made to access the server from a browser, the browser must have a certificate for the client certificate authentication. If the default SSL configuration of the server was modified to enable client certificate authentication you are unable to login to the console.

We can create a certificate for the browser using the console. We must first create a key store and then create a chained certificate. After the certificate is created, use the instructions for the browser to import a certificate. Browsers require that each part of the chain be added to verify the certificate, so the root certificate must be extracted and added to the browser. Follow the instructions in the "Setting up the client side for client authentication" section for information about extracting the root certificate.

To create a key store using the console:

  • Enter a name for the key store. Enter the full path to the key store file. Enter a password for the key store and then confirm. Click OK to save.

    To create a chained certificate using the console:

    1. Click...

        Security | SSL certificate and key management | Key stores and certificates | key store created previously | Additional Properties | Personal certificates | pull-down list under the Create button | Chained Certificate

    2. Enter an alias name for the certificate.

    3. Provide a common name for the certificate. The name is the "CN=" part of the subject DN.

    4. We can enter information in any of the remaining fields to build the subject DN of the chained certificate.

    5. Click OK to save.

    We can also use the createKeyStore command to create a key store. Read KeyStoreCommands command group (AdminTask) for more information about this command.

    We can also use the createChainedCertificate command to create a chained certificate. Read PersonalCertificateCommands (AdminTask) for more information about this command.

    When client certificate authentication is enabled, web certificate authentication can then be performed as discussed in the next section.


    Web certificate authentication

    Certificate base authentication can be performed on Java 2 Platform, Enterprise Edition (J2EE) web modules when the module is configured for client certificate authentication. This enables a user to login to a web module using a certificate to authenticate, and to map that certificate to a user from the registry.

    Enabling web certificate authentication requires that the SSL configuration of the server be configured for client certificate authentication on the server where the module is installed.

    The server side determines that client authentication is to take place. See the "Configuring a WebSphere server for client authentication" section for information about how to configure client authentication. The client side must have the signer from the server to add to the client truststore. See the "Setting up the client side for client authentication" section for more information.

    The web.xml file of the web module must have the authentication method set to CLIENT-AUTH in the login-config section of the web.xml file:

    <login-config>
    <auth-method>CLIENT-CERT</auth-method>
    </login-config>

    The certificate must map to a user in the registry or you are unable to login to that web module.

    For localOS user registries, the CN value of the certificate subject DN must map to a user in the local OS user registry. For example, if the certificate subject DN is CN=tester,o=ibm,c=us, then tester is the user searched for in the local user registry. If that user does not exist in the local registry then the authentication fails.

    The LDAP user registry provides more options for mapping a certificate to a user identity. The default certificate mapping mode in LDAP is used for an exact DN match between the entry in the LDAP registry and the subject DN in the certificate. For example, if the certificate DN is CN=user1,o=ibm,c=us, then there must be an entry in the LDAP registry with that exact value. The LDAP user registry also has a certificate filter option that can provide a match to a particular part of the certificate subject DN against entries in the LDAP repository. For more detail on LDAP certificate mapping, read "Lightweight Directory Access Protocol repository configuration settings".

    In a federated repositories configuration, by default, client certificate login is not supported for the file-based repository. To enable support for certificate mapping in the file-based repository follow the procedure in the topic, Enable client certificate login support in a federated repositories file-based repository.

    The federated repository LDAP registry supports certificate mapping. It uses the same mapping rules and properties that the LDAP user registry uses.

    Custom user registry can map certificates to a user if the custom registry implemented the mapCertificate() method.


    Related

    Certificate management using iKeyman prior to SSL
  • Enable client certificate login support for a file-based repository in federated repositories
  • SSLConfigCommands (AdminTask)
  • SecurityConfigurationCommands (AdminTask)
  • SignerCertificateCommands (AdminTask)
  • PersonalCertificateCommands (AdminTask)
  • Personal certificates collection
  • KeyStoreCommands (AdminTask)
  • Lightweight Directory Access Protocol repository configuration settings