Overview

Skill Level: Advanced

This recipe details the configuration steps required to configure client/server certificate authentication within a deployed ISD (Information Services Director) job/web service.

Ingredients

  • Information Server 11.5 Fix Pack 2 or later
  • WebSphere Application Server, Network Deployment
  • Information Services Director(ISD) Knowledge Center
  • SoapUI or some other client side tool to initiate/test the request to the ISD service.

Step-by-step

  1. WebSphere QoP settings

    First, we need to modify the Quality of protection (QoP) settings within WebSphere Application Server. 

    QoP

    • If None is selected, the server does not request that a client certificate be sent during the handshake.
    • If Supported is selected, the server requests that a client certificate be sent. If the client does not have a certificate, the handshake might still succeed.
    • If Required is selected, the server requests that a client certificate be sent. If the client does not have a certificate, the handshake fails.

     

    In order to permit ISD services to support client/server certificate authentication and still allow for the remaining components of Information Server to function, this setting must¬†be set to “Supported”

    Information Server DataStage clients¬†require Client authentication set to “None” or “Supported”. ¬†Setting Client authentication to “Required” will not permit the DataStage clients to authenticate against WebSphere Application Server.

  2. Setup Client Certificate mapping

    Client Certificate Authentication is only supported when Federated Repositories or Standalone LDAP is configured as the security registry within WebSphere Application Server.

    Client Certificate mapping provides WebSphere with instruction on how to map a client certificate to an existing user defined in your user registry.  Below are some references to documentation for each registry type:

    • Enabling client certificate login support for a file-based repository in federated repositories:

    For this repository type, Navigate to:

    Global security > Federated repositories > Manage repositories > InternalFileRepository
    Add Properties:
    certificateFilter=uid=’${SubjectCN}’
    certificateMapMode=filterDescriptorMode

    InternalFileRepository

    Consult the WebSphere Knowledge Center for additional information.

    • Enabling client certificate login support for LDAP repository in federated repositories

    Navigate to Global security > Federated repositories > <Repository Identifier>

    GlobalSecurity_Federated_LDAP

    Consult the WebSphere Knowledge Center for additional information.

    • Enabling client certificate login support for Standalone LDAP user registry

    Navigate to Global security > Standalone LDAP registry > Advanced Lightweight Directory Access Protocol (LDAP) user registry settings

    GlobalSecurity_Standalone_LDAP

    Consult the WebSphere Knowledge Center for additional information.

  3. Generate/Configure the Client certificate

    Generate the Client certificate that will be used. Note, it much match a user you plan to authenticate as:
    Ex:
    CN=isadmin

    The IBM JDK’s ikeyman is included with Information Server Client/Server installations and can be used to generate a Keystore and Truststore for the Client if one is not already created.

    For example on Windows:

    C:\IBM\InformationServer\jdk\jre\bin\ikeyman.exe

    CreateClientKeystore

    When prompted, enter a password to finish creating the keystore.

    Next, create a “New Self-Signed..” certificate, “Receive” a certificate from a CA (Certificate Authority), or “Import” a certificate from another keystore.

    This example shows creating a new self-signed certificate.  Note, that the CN (Common Name) matches a username that exists in the WebSphere Application Server security registry and represents the user that will be used to authenticate for the ISD service.

    CreateClientCert

  4. Import client certificate into the WAS

    WebSphere Application Server’s truststore must be configured to trust the new client certificate.

    One way to ensure the certificate is trusted is to use a certificate that is signed by a Signer Certificate that WebSphere trusts.

    Another way, is to import the certificate itself into WebSphere Application Server’s truststore.

    In either method, you will be importing the certificate into the NodeDefaultTrustStore so that the ISD Application that is deployed can trust the certificate.

    Within WebSphere navigate to:

    SSL certificate and key management > Key stores and certificates > NodeDefaultTrustStore > Signer certificates

    To add the appropriate certificate.

  5. Export WAS server certificate

    Create/Export the Server certificate from the WebSphere NodeDefaultKeyStore so that it can be imported into the Client’s truststore.¬† You can use an existing certificate in the keystore, or create a new one.

    Within WebSphere navigate to:

    SSL certificate and key management > Key stores and certificates > NodeDefaultKeyStore > Personal certificates

    Either create a new Personal certificate in this keystore, or use an existing certificate.¬† Once complete, export the certificate to a file so that you can import the certificate into the client’s Truststore.

  6. Default client certificate alias

    Set the “Default client certificate alias” within the WebSphere Application Server Administrative Console:

    Within WebSphere navigate to:

    SSL certificate and key management > SSL configurations > NodeDefaultSSLSettings

    DefaultClientCert

    The “Default client certificate alias” specifies the certificate alias to be used if this SSL configuration is to be used as a client.

    Select the alias to match the certificate created/exported in Step #5

  7. Import WAS certificate into client's truststore

    Import the WebSphere Server certificate created/exported from Step #6 into the Client’s Truststore

    If you do not have one, create a truststore by using ikeyman similar to the keystore creation steps described in Step #3.

    Select “Signer Certificates” and “Add” to import the certificate that was exported in Step #6

    Client_TrustStore

  8. Configure Client side tool

    Configure your Client Side tool that will interact with the ISD service (SOAP UI, etc) to use the Keystore (created or updated in Step #3) and Truststore (Created or updated in Step #7)

  9. Configure ISD Binding for Client Certificate Authentication

    On an Information Server client tier, open the IBM InfoSphere Information Server Console application:

    ISD_Icon

    Within the ISD Application, select the “Overview” tab to enable “Requires Authentication” and “Requires Confidentiality”

    ISD_Security

    Next, within the “Bindings” tab, select “WS-Security Username Token” as the “Authentication Support” option

    ISD_Security_Client_Cert

    Save and deploy the service. During the deployment ISD will produce the web service web.xml with the required section needed to enable 2-WAY SSL with this ISD Service, ie.:

    <login-config>
    <auth-method>CLIENT-CERT</auth-method>
    <realm-name>IBM Information Server</realm-name>
    </login-config>

  10. Debug Logging

    If needed, to debug the Client Certificate authentication within ISD, add the following string to:

    Within WebSphere, navigate to:

    Logging and tracing > server1 > Change log detail levels

    Choose the “Runtime” tab so that log level changes can be applied without needing to restart the WebSphere JVM.

    For log level details enter:

    *=info: com.ibm.iis.xmeta.*=warning: com.ibm.xmeta.*=warning: com.ibm.ws.security.*=all: com.ibm.websphere.security.*=all: com.ibm.ws.webservices.trace.MessageTrace=all: com.ibm.ws.webservices.trace.UserExceptionTrace=all

Join The Discussion