+

Search Tips   |   Advanced Search

Secure Sockets Layer client certificate authentication

Client software that wants to establish a secure connect to a server using Secure Socket Layer (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 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 administrative console:

  1. Click Security > SSL certificate and key management > SSL configurations.

  2. Select a SSL configuration.

  3. Under Additional Properties, select Quality of protection (QoP) settings.

  4. Under Client authentication, select Required.

  5. Click OK to save the changes.

We can also use the modifySSLConfig command with the -clientAuthentication flag set to true to enable client authentication. See SSLConfigCommands .for more information about this command. .

To configure client certificate authentication on a CSIv2 inbound connection using the administrative console:

  1. ClickSecurity > Global Security.

  2. Under RMI/IIOP security, select CSIv2 inbound communications.

  3. In the CSIv2 Transport Layer section, and under Client certificate authentication, select Required.

  4. Click OK to save the changes

We can also use the configureCSIInbound command with the -clientCertAuth flag set to Required to enable client authentication on CSIv2. Read SecurityConfigurationCommands .for more information about this command.

If the client side is set up for client authentication, the signer certificate of the client must be added to the trust store of the server. When we have a certificate from the client in a certificate file it can be added to the trust store of the server.

To add a signer to the trust store of the server using the administrative console:

  1. Click Security > SSL certificate and key management > Key stores and certificates.

  2. Select the trust store configured for client authentication.

  3. Under Additional Properties, select Signer Certificates.

  4. Click Add.

  5. In the Alias field, type an alias name under which to store the certificate.

  6. In the File name box, type the full path to the certificate file.

  7. Click OK to save the changes

We can also use the addSignerCertificate command to add a signer to the trust store of the server. Read SignerCertificateCommands .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 WAS is installed already has a personal certificate in it. This key store can be found in the ssl.client.props file in the com.ibm.ssl.keyStore property. The client key stores are not managed by WAS, 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 the ssl.client.props file.

  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 that is 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: 

javax.net.ssl.keyStore
javax.net.ssl.keyStorePassword
javax.net.ssl.keyStoreType
javax.net.ssl.trustStore
javax.net.ssl.trustStorePassword
javax.net.ssl.trustStoreType

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 administrative console:

  1. Click Security > SSL certificate and key management > Key stores and certificates.

  2. Under the Keystore usages pull-down, select Root certificate keystore.

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

  4. Under Additional Properties, select Personal certificates.

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

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

  7. Click OK to save.

We can also use the extractCertificate command to extract the root certificate. Read PersonalCertificateCommands .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 administrative console:

  1. Click Security > SSL certificate and key management > Key stores and certificates.

  2. Select the trust store of the server from the collection.

  3. Under Additional Properties, select Signer certificates.

  4. Click Retrieve from port.

  5. Enter a destination host name and a destination port name.

  6. Enter an alias name for the certificate.

  7. Click Retrieve signer information.

  8. Click OK to save.

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

Set up a browser for client authentication:

When WAS 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 we are unable to login to the administrative console.

Create a certificate for the browser using the administrative console. We must first create a key store and then create a chained certificate. After the certificate is created, use the instructions for our 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 administrative console:

  1. Click Security > SSL certificate and key management > Key stores and certificates.

  2. Click New.

  3. Enter a name for the key store.

  4. Enter the full path to the key store file.

  5. Enter a password for the key store and then confirm.

  6. Click OK to save.

To create a chained certificate using the administrative console:

  1. Click Security > SSL certificate and key management > Key stores and certificates.

  2. Select the key store we created previously.

  3. Under Additional Properties, click Personal certificates.

  4. In the pull-down list under the Create button, select Chained Certificate.

  5. Enter an alias name for the certificate.

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

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

  8. Click OK to save.

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

We can also use the createChainedCertificate command to create a chained certificate. Read PersonalCertificateCommands command group for the AdminTask object 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 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.

Enable 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 we 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, Enabling 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
  • SecurityConfigurationCommands
  • SignerCertificateCommands
  • PersonalCertificateCommands
  • Personal certificates collection
  • KeyStoreCommands
  • LDAP repository configuration settings