Secure Sockets Layer client certificate authentication

Client software that wants to establish a secure connect to a server by using Secure Socket Layer (SSL) protocol initiates by leveraging SSL protocol or the enhanced protocol called Transport Layer Security (TLS) to perform a 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 that is 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:
  • The server side must determine if client authentication is going to take place. The client authentication must be enabled in the SSL configuration of the server and the Common Secure Interoperability version 2 (CSIv2) configuration if Inter-ORB Protocol (IIOP) is used.
  • The CSIv2 configuration must take place in global security, not in a security domain.
  • The signer certificate of the client must be extracted from the key store of the client and added to the trust store of the server.
  • The signer certificate of the server must to be extracted from the key store of the server and added to the trust store of the client.

Configuring 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. This configuration affects WebSphere when it is acting only as a server, not when it is acting as a client.

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.

You can also use the modifySSLConfig command with the -clientAuthentication flag set to true to enable client authentication. See SSLConfigCommands command group for the AdminTask object 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

You can also use the configureCSIInbound command with the -clientCertAuth flag set to Required to enable client authentication on CSIv2. Read SecurityConfigurationCommands command group for the AdminTask object 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 you 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 that is 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

You can also use the addSignerCertificate command to add a signer to the trust store of the server. Read SignerCertificateCommands command group for the AdminTask object for more information about this command.

If you 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.

Setting 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 that is created when WebSphere Application Server 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 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. You 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.
Important: A best practice is to manage server keystores and client keystores separately. However, if you do wish to manage client keystores in adminconsole with server keystores, you can create a keystore configuration to point to the local client keystore. Be aware that the certificate expiration monitor does not monitor client keystores.

The file that contains 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.
  • Enable SSL:
    	com.ibm.CSI.performTransportAssocSSLTLSSupported=true
	com.ibm.CSI.performTransportAssocSSLTLSRequired=false
  • Disable client authentication at the message layer:
    	com.ibm.CSI.performClientAuthenticationRequired=false
	com.ibm.CSI.performClientAuthenticationSupported=false
  • Enable client authentication at the transport layer (this is supported, but not required):
     com.ibm.CSI.performTLClientAuthenticationRequired=false
	com.ibm.CSI.performTLClientAuthenticationSupported=true

Thin clients and pure clients might not use the WebSphere Application Server 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. It is recommended 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.

You can also use the extractCertificate command to extract the root certificate. Read PersonalCertificateCommands command group for the AdminTask object for more information about this command.

The certificate file that is 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.

You can also use the retrieveSignerFromPort command to retrieve the signer from the port. Read SignerCertificateCommands command group for the AdminTask object for more information about this command.

Setting 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 administrative console.

You can create a certificate for the browser by using the administrative console. You must first create a key store and then create a chained certificate. After the certificate is created, use the instructions for your 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 you 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. You can enter information in any of the remaining fields to build the subject DN of the chained certificate.
  8. Click OK to save.

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

You 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 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 Lightweight Directory Access Protocol (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.