IBM Support

Configuring federated single sign-on for IBM Content Navigator on docker container by using SAML 2.0.

Product Documentation


Abstract

This document contains instructions for configuring federated single sign-on (SSO) for IBM Content Navigator on docker container with a FileNet P8 repository by using SAML 2.0.

IBM Content Navigator (ICN) configured with SAML SSO can work on environments for container deployments and IBM Private Cloud (ICP) deployments.

Note:
The steps described in this document should be considered as guidance only. The steps might be different in your environment and and might require further modification depending on your requirements. Consult the site administrator for environmental modifications.

Important:
ECM Clients such as Edit Services, Sync and Sync Client, IBM Navigator for Microsoft Office are not supported in SAML SSO container environment. Support will be added in future releases.

Content

Before you begin

    • Identity Provider (IP) should be installed and configured with SAML SSO according to documentation.
       NOTE: In our sample deployment we used IBM Tivoli Federated Identity Manager as our Identity Provider.  But any Identity Provider that support SAML 2.0 standards can be used.     
    Refer to your Identity Provider documentation on how security federation and SAML is configured.

    Below is the link to TFIM Identity Provider
    https://www.ibm.com/support/knowledgecenter/SSZSXU_6.2.2.7/com.ibm.tivoli.fim.doc_6227/config/config.html

    • Prepare your environment for deploying FileNet Content Manager and Content Navigator on docker container environment or ICP environment by following steps in the Knowledge Center.     
    • Deploy and configure Content Platform Engine container according to instructions in the Knowledge Center. Refer to this link.
    https://www.ibm.com/support/knowledgecenter/en/SSNW2F_5.5.0/com.ibm.p8.containers.doc/containers_deploy.htm

   

  

Deploy and configure Content Navigator with SAML SSO

1. Before deploying IBM Content Navigator container you need to enable samlWeb-2.0 feature in Liberty server.
  
    1.1    Create xml file with SAML feature enabled. Call it e.g. SAMLDefaultSP.xml
        <server description="new server">    
        <!-- Configuration for default SAMLSP -->
        <featureManager>
          <feature>samlWeb-2.0</feature>
        </featureManager>
        </server>
  
    1.2    Copy this file to IBM Content Navigator Liberty configuration persistent volume.
            Refer to the following link for details on Creating persistent volumes and persistent volume claims for the IBM Content Navigator container deployment:
        https://www.ibm.com/support/knowledgecenter/en/SSNW2F_5.5.0/com.ibm.p8.containers.doc/containers_volumeicpprepare.htm
        For example,
        /icncfgstore/icn/configDropins/overrides folder
        Make sure you set the ownership on this file to 50001:50000

2. Create your own SSL certificates for navigator.
    Below is the example on how to create and configure key stores:
    Note: Run the keytool command with IBM Java V1.8 or above.
  
    2.1    Generate a key pair and create server certificate key store for navigator container.
        Refer to Oracle Java 1.8 documentation for further details on keytool command syntax.
        https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html
        For example,
        keytool -genkeypair -v -keyalg RSA -sigalg SHA256withRSA  -alias icp-icn -keypass changeit -keystore mykey.jks  -storepass changeit -validity 3650 -dname "CN=ICN , OU=ECM, O=IBM, L=Unknown, ST=Unknown, C=Unknown"
        Make sure the certification key algorithm is RSAs and signature algorithm is SHA256withRSA.
  
    2.2    Export certificate from the key store created in step 2.1:
        For example,
        keytool -exportcert -alias icp-icn  -keystore mykey.jks -file mykey.cer -storepass changeit
  
    2.3    Create trust key store for navigator container server and import the certificate from step 2.2
        For example,
        keytool -importcert -keystore mytruststore.jks -alias  icp-icn -file mykey.cer -storepass changeit
  
    2.4    Overwrite the default SSL settings for navigator container with the pair of key stores created earlier by creating xml file.
        For example,
        <server description="new server" >
        <sslDefault sslRef="icnSSLSettings" />
        <ssl id="icnSSLSettings"   
            keyStoreRef="icnKeyStore"
            trustStoreRef="icnTrustStore"  
            clientAuthenticationSupported="false"
             />
        <keyStore id="icnKeyStore"
            location="/opt/ibm/wlp/usr/servers/defaultServer/configDropins/overrides/mykey.jks"
            type="JKS" password="changeit"
        />
        <keyStore id="icnTrustStore"
            location="/opt/ibm/wlp/usr/servers/defaultServer/configDropins/overrides/mytruststore.jks"
            type="JKS" password="changeit"
        />
        </server>
  
    2.5    Name this file e.g.  SSL_ICN_Overrite.xml.
  
    2.6    Copy the key store pair together with SSL_ICN_Overrite.xml file to IBM Content Navigator Liberty configuration persistent volume.
        For example,
        /icncfgstore/icn/configDropins/overrides folder
        Make sure you set the ownership on this file to 50001:50000
  
3. Deploy and configure IBM Content Navigator container according to instructions in the Knowledge Center. Refer to this link.
https://www.ibm.com/support/knowledgecenter/en/SSNW2F_5.5.0/com.ibm.p8.containers.doc/containers_privateclouddeploy.htm
Important: Make sure to deploy IBM Content Navigator SSO container image.
    For example,
    When using Configuration tool the image name is:
     mycluster.icp:8500/default/navigator-sso:3.0.5
    mycluster.icp:8500/default/navigator-sso: <image_tag>
    Specify navigator SSO image:
    - image: mycluster.icp:8500/default/navigator-sso:3.0.5

 

Post-deployment configurations

Post-deployment configurations
1. Refer to Identity Provider documentation on how to export Identity Provider metadata. The name of the file has to be idpMetadata.xml. Copy this file to IBM Content Navigator overrides folder.
    For example:
    /icncfgstore/icn/configDropins/overrides folder
    Make sure you set the ownership on this file to 50001:50000
        
2. Export Service Provider metadata as follows:
    - Use a browser to download the metadata for this service provider (SP) by using this URL, and provide the URL to the SAML identity provider to establish federation between this SP and Identity Provider (IP).
             - On a standalone docker container environment the URL is:
             https://containerhostname:sslport/ibm/saml20/defaultSP/samlmetadata
            - On an IBM Cloud Private deployed environment the URL is:
           https://proxyserverIPaddress:navigatorsslport/ibm/saml20/defaultSP/samlmetadata
    - Save Service Provider metadata xml file.
  
3. Follow your Identity Provider documentation how to add Partner to Federation.
        E.g. when using TFIM IP follow instructions but with the following difference:
        • Use Assertion Consumer Service URL to your ICN docker container.
               -  On a standalone docker container environment the URL is:
                https://containerhostname:sslport/ibm/saml20/defaultSP/acs
               - On an IBM Cloud Private deployed environment the URL is:
               https://proxyserverIPaddress:navigatorsslport /ibm/saml20/defaultSP/acs
       • For Signature Algorithm select RSA-SHA256 (to match up the algorithm on the ICN container)
       • When import service provider metadata select docker container Service Provider metadata file saved in step 3 above.
  
4. Modify SAMLDefaultSP.xml file and add the following configuration parameters.
        Below is the example of xml file that is using TFIM Identity Provider. Customer will have their own parameters that would be applicable to  their environment.
         <server description="new server">    
            <!-- Configuration for default SAMLSP -->
           <featureManager>
                 <feature>samlWeb-2.0</feature>
           </featureManager>
          <samlWebSso20 id="defaultSP"
           errorPageURL="https://idphostname:sslport/sps/federationname/saml20/logininitial?          NameIdFormat=Email;   PartnerId=https://containerhost:sslport/ibm/saml20/defaultSP/acs;Target=https://containerhost:sslport/navigator"
         mapToUserRegistry="User"
         disableLtpaCookie="false"
         allowCustomCacheKey="false"
         authFilterRef="myAuthFilter"
         idpMetadata="/opt/ibm/wlp/usr/servers/defaultServer/configDropins/overrides/idpMetadata.xml">
         </samlWebSso20>
         <authFilter id="myAuthFilter">
         <requestUrl id="ICNRequestUrl" urlPattern="/navigator" matchType="contains"/>
       </authFilter>
    </server>
    Parameters given above is the minimum required configurations for Content Navigator with SAML SSO. There is a number of optional parameters that can be used depending on your requirements that might be applicable to your environment.
    Refer to the WebSphere Liberty documentation in following link for the description of all available parameters:
    https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.liberty.autogen.base.doc/ae/rwlp_config_samlWebSso20.html
    Configure Liberty with Service Provider for SAML SSO. Below steps are just a guideline with minimum configurations in order to get Content Navigator configured with SAML SSO working.
  
5. Start Content Navigator container. Connect to navigator using HTTPS URL with SSL port.
       - On a standalone docker container environment the URL is:
       https://containerhostname:sslport/navigator
       - On an IBM Cloud Private deployed environment the URL is:
        https://proxyserverIPaddress:navigatorsslport/navigator
    Note: If using TFIM IP you should be redirected to IP login form. Login to a form as an existing LDAP user.
    Important: Before connecting to navigator make sure clocks are in syncronized between the host that is running containers and Identity Provider server.


Troubleshooting

For Troubleshooting SAML SSO on Liberty docker container add the following logging into the server.xml file by creating an xml file and coping it to the Overrides folder.
    <server>
      <!-- WAS tracing  -->
       <logging traceSpecification=" com.ibm.ws.security.*=all:com.ibm.websphere.security.*=all:com.ibm.ws.security.web.saml.*=all"/>
    </server>

Document Location

Worldwide

[{"Business Unit":{"code":"BU002","label":"Business Analytics"},"Product":{"code":"SSEUEX","label":"Content Navigator"},"Component":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"All Versions","Edition":""}]

Product Alias/Synonym

Content Navigator

Document Information

Modified date:
03 September 2019

UID

ibm10878128