Configuring certificate authentication in Jazz Authorization Server

Jazz Authorization Server serves as an OpenID Connect provider (OIDC) for single sign-on (SSO) for Engineering Lifecycle Management applications. You can configure the Jazz Authorization Server running on IBM® WebSphere® Liberty to log in using a User Certificate (.p12) file or a smart card, which are more secure than logging in with a user name and password. Although a certificate file and a smart card are different, they are both certificates that are used for authentication. Certificate authentication uses HTTP over SSL and authentication occurs by using a public key certificate that is issued by a trusted organization, which is known as a certificate authority.

Before you begin

Before you can configure certificate authentication, you must complete the following tasks:
  • Configure Jazz Authorization Server to use LDAP user registry
  • Ensure that a certificate authority and user certificates already exist and that the certificate authority's public certificate is available to the administrator. For information about how to create SSL certificates, see SSL Certificates HOWTO.
  • Copy the root certificate authority's public certificate to the computer that hosts Jazz Authorization Server.
  • Smart card authentication is available for Windows operating systems only.
Limitation: Configuring certification authentication with Jazz Authorization Server is not supported for the deployments with reverse proxy such as IBM HTTP Server.

There are three components involved in this configuration:

  1. WebSphere Liberty server Profile hosting Jazz Authorization Server.
  2. OpenID Connect provider (OIDC)
  3. Clients

Configure WebSphere Liberty server to accept certificates

About this task

Configure IBM WebSphere Liberty to support or require client certification authentication at the transport layer.

Procedure

  1. Edit the appConfig.xml file that is located at JazzAuthServer_install_dir/wlp/usr/servers/jazzop.
  2. Add the clientAuthenticationSupported=”true” parameter within the SSL configuration as follows:
    <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" 
    sslProtocol="TLSv1.2" 
    trustStoreRef="defaultTrustStore" 
    clientAuthenticationSupported="true" 
    serverKeyAlias="<Server_CA_Cert>" /> 

    The default value provided for <Server_CA_Cert> is sslkey

    If you specify the clientAuthentication="true" parameter, the server requests a certificate from the client. However, if the client does not have a certificate, or the certificate is not trusted by the server, the handshake does not succeed.

    If you specify the clientAuthenticationSupported="true" parameter, the server requests a certificate from the client. However, if the client does not have a certificate, or the certificate is not trusted by the server, the handshake might still succeed.

    If you do not specify either clientAuthentication or clientAuthenticationSupported parameter, or you specify clientAuthentication=”false” or clientAuthenticationSupported=”false”, the server does not request a certificate from the client during the handshake.

Configure the default KeyStore

About this task

Configure the default Keystore with a server certificate from the certificate authority where the common name in the certificate matches the FQDN that is used in your Jazz Authorization Server public URI.

Procedure

  1. Use ikeyman or keytool to import the CA certificate to the default keyStore that is located at JazzAuthServer_install_dir/wlp/usr/servers/jazzop/resources/security.
    The default keyStore file used in Liberty is ibm-team.keystore and password is ibm-team.
  2. Copy the KeyAlias/Label of the imported certificates and include it in the <ssl> configuration serverKeyAlias.
  3. Edit the appConfig.xml file located at JazzAuthServer_install_dir/wlp/usr/servers/jazzop/.
    <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" 
    sslProtocol="SSL" 
    trustStoreRef="defaultTrustStore" 
    clientAuthenticationSupported="true" 
    serverKeyAlias="<Server_CA_Cert>" />
  4. Edit the defaultKeyStore element if there are changes to your keystore location/password.
    <keyStore
    id="defaultKeyStore"
    location="ibm-team.keystore"
    type="JCEKS"
    password="{xor}Nj0ycis6Pjl="/>

Configure the default TrustStore

About this task

Configure the default TrustStore with the certificate authority’s root certificate, so that the server trusts the client certificates.

Procedure

  1. Create a New TrustStore using ikeyman or keytool (IBM JRE) and import the root/public certificate from the CA authority.
  2. Include the new TrustStore name under <ssl> configuration in the appConfig.xml file that is located at JazzAuthServer_install_dir/wlp/usr/servers/jazzop/.
    <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" 
    sslProtocol="SSL" 
    trustStoreRef="defaultTrustStore" 
    clientAuthenticationSupported="true" 
    serverKeyAlias="<Server_CA_Cert>"/>
  3. Add the new TrustStore details below the default KeyStore configuration.
    <keyStore 
    id="defaultTrustStore"
    location="trust.p12"
    type="JKS"
    password="<TrustStore_Password>" />
    Alternatively, you can import the root/public certificate from the CA authority into your defaultKeyStore and use it as your trust store trustStoreRef. Below the default KeyStore is used for the default TrustStore.
    <ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" 
    sslProtocol="SSL" 
    trustStoreRef="defaultKeyStore" 
    clientAuthenticationSupported="true" 
    serverKeyAlias="<Server_CA_Cert>"/>

    For more information, see Configuring your web application and server for client certificate authentication.

Configure Liberty Profile to map incoming certificates to users in the registry

About this task

WebSphere Liberty server accepts incoming certificates as an authentication mechanism, but the server is not configured to map the incoming certificates to users. Provide a mapping strategy between certificates and users in the registry. The mapping is described through two settings: CertificateMapMode and CertificateFilter. Regardless of the user registry that you use, you must know the values for those two settings.

Certificate filter

Specifies the filter certificate mapping property for the LDAP filter. The filter is used to map attributes in the client certificate to entries in the LDAP registry. If more than one LDAP entry matches the filter specification at run time, authentication fails because the result is an ambiguous match. The syntax for this filter is: LDAP attribute=${Client certificate attribute}.

An example of a simple certificate filter is: uid=${SubjectCN}. For more information see the related Liberty Documentation.

Here is an example of an LDAP configuration with certificate filter mode enabled:

<ldapRegistry id="LDAP" realm="SampleLdapIDSRealm" 
host="myldap.ibm.com" port="389" ignoreCase="true" 
baseDN="o=ibm,c=us" 
certificateMapMode="CERTIFICATE_FILTER" 
certificateFilter="uid=${SubjectCN}" 
userFilter="(&(uid=%v)(objectclass=ePerson))" 
groupFilter="(&(cn=%v)(|(objectclass=groupOfNames)
(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))" 
userIdMap="*:uid" 
groupIdMap="*:cn" 
groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember;
groupOfNames:member;groupOfUniqueNames:uniqueMember" 
ldapType="IBM Tivoli Directory Server" searchTimeout="8m" />

Configure OpenID connect provider configuration to require certificate-based authentication

About this task

WebSphere Liberty server is now configured to allow certificate authentication and map incoming certificates to known users, but you must also configure the OpenID connect configuration of Jazz Authorization Server to accept certificate-based authentication.
Note: The Engineering Lifecycle Management Applications and the Liberty servers that host the Engineering Lifecycle Management applications do not need to be configured for certification authentication because the authentication is redirected to Jazz Authorization Server.

Procedure

  1. Edit the appConfig.xml file located at JazzAuthServer_install_dir/wlp/usr/servers/jazzop/.
  2. Add on of the following lines below the autoAuthorize= parameter in the <oauthProvider> section:
    • If you want to make certificate mandatory and fail the authentication if no certificate is available, add certAuthentication=true.
    • If you do not want to make certificate mandatory and the authentication must use user's credentials if the certificate is not available, add allowCertAuthentication=true
    For example,
    <oauthProvider id="JazzOP"
        httpsRequired="true"
        autoAuthorize="true"
        allowCertAuthentication="true"
        customLoginURL="/jazzop/form/login"
        accessTokenLifetime="7201"
        authorizationGrantLifetime="604801">
        <autoAuthorizeClient>client01</autoAuthorizeClient>
        <databaseStore dataSourceRef="OAuthFvtDataSource" />
    

Configure web browsers to authenticate applications via user certificates

Procedure

  1. Import the user certificate into the browser as personal certificates.
  2. On Microsoft Windows, double-click on the user certificate and follow the steps in the wizard to import the certificate to your web browser.
    After the import completes, on accessing any of the Engineering Lifecycle Management applications, the imported certificates are listed.
  3. Select the appropriate user certificate to log in to Engineering Lifecycle Management.
  4. check the user name that is displayed at the top-right corner and confirm the certificate if it matches your user ID.
    Windows security dialog box to confirm the certificate

Configure Eclipse and Visual Studio clients to authenticate applications via user certificates

Procedure

  1. Create a new repository connection and configure it to use the certificate authentication.
  2. Change authentication type to SSL certificate.
  3. Browse the user certificate you want to use and enter the password.
    Configure certificate for jazz repository connection
  4. Click Finish to log in.

Repotools Utility

Repotools supports the use of certificate authentication using the certificateFile parameter. The adminPassword parameter is the password for the certificate provided. Below is an example of using a User Certificate and password to execute repotools commands

Example

Following is an example of using a User Certificate and password to execute repotools commands:
> repotools-ccm.bat -backupJFSIndexes repositoryURL=https://ibmclm.vapp.com:9443/ccm 
certificateFile="C:\Certs\MyCert.p12" adminPassword="MyPassword" toFile=C:\Test\CCMIndexBackup.zip