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.
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.
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.
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.
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.
com.ibm.CSI.performTransportAssocSSLTLSSupported=true com.ibm.CSI.performTransportAssocSSLTLSRequired=false
com.ibm.CSI.performClientAuthenticationRequired=false com.ibm.CSI.performClientAuthenticationSupported=false
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.
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.
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.
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.
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.
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, install WebSphere Application Server fixpack version 8.0.0.4 or higher, and 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.