IBM Support

Configuring the Content Services GraphQL container to work with a traditional WebSphere Application Server hosted Content Platform Engine

How To


Summary

You can configure the Content Services GraphQL API container to work with a traditional WebSphere Application Server hosted Content Platform Engine. This configuration is useful if you need to use features or extensions that require the Content Services GraphQL API, but you are not ready to move your environment to containers.

Steps

These instructions assume that Content Services GraphQL is deployed manually using a container build and not through any Operator type of deployment.  

Important: This deployment pattern is intended for demonstration or proof-of-concept environments only, and is not supported for production use. For production environments, the Content Services GraphQL container must be deployed in a supported Kubernetes platform, using the operator to deploy. 

LTPA SSO

IBM WebSphere Lightweight Third Party Authentication (LTPA) is the officially supported mechanism for propagating a user's identity between the Content Services GraphQL container and Content Platform Engine, regardless of whether Content Platform Engine is running in a container on WebSphere Liberty or on-premises on traditional WebSphere Application Server.

Users can authenticate against Content Services GraphQL using Basic Authentication or through an Identity Provider (IdP) that supports OpenID Connect or OAuth 2.0 authentication. In either case, after the user has been authenticated in GraphQL, their identity is propagated to Content Platform Engine using LTPA SSO.

Configuring Content Platform Engine on WebSphere Application Server

Start by setting up the Content Platform Engine on WebSphere Application Server for LTPA SSO and exporting the LTPA key.

To enable Single Sign-On:

Make a note of the LDAP server configuration.

  1. In the WebSphere Application Server administration console, navigate to Security > Global security > Single sign-on, enter a Domain Name, and check the following settings:
    • Enabled
    • Requires SSL (with Domain name)
    • Web inbound security attribute propagation
    • Set security cookies HTTPOnly to help prevent cross-site scripting attacks
    image-20200529155540-1
  2. Export LTPA keys
    1. In the WebSphere Application Server administration console, navigate to Security > Global security > LTPA.
    2. Provide a password for the ltpa.keys file.
    3. Provide a path for the LTPA file, for example, /opt/IBM/WebSphere/AppServer/profiles/Appsrv01/ltpa.keys.
    4. Click Export
  3. Make note of the Realm value in the ltpa.keys file:

    The ltpa.keys file is a text file; open it and verify the value of the Realm property: com.ibm.websphere.ltpa.Realm=ldap_realm.

    This realm should match the Realm name under Security > Global security > Federated Repositories.

    This realm must match the realm in the LDAP configuration of your GraphQL Liberty server.

    image-20200529155540-2

  4. Configure the LDAP setup in your GraphQL WebSphere Liberty server with similar settings as the LDAP configuration in the WebSphere Application Server instance for Content Platform Engine.

Configuring Content Services GraphQL Liberty Container

You can use the instructions in the IBM FileNet Content Manager Download Document to download the container image from Passport Advantage:
IBM FileNet Content Services GraphQL API V5.5.5 Linux x86 Container Multilingual (CC6UAML )

The image file is called IBM_FILENET_CSG_API_V5.5.5.tgz.

You can use a command like the following example to load the container image into your Docker registry:

%  tar xzvf IBM_FILENET_CSG_API_V5.5.5.tgz 
% docker load -i images/graphql_ga-555-p8cgql.tar.gz

Get the repository identifier and tag of the GraphQL container using the following command and use them in your run script when starting the GraphQL container:

% docker images | grep graphql
graphql         ga-555-p8cgql        fca79e90f205        4 months ago        876MB 

Note that all configuration for Content Services GraphQL is performed by creating files in the configDropins/overrides directory that is mounted to a directory on the host machine.

Use a run script similar to the following to start the GraphQL container.  This sample script mounts the logs and configDropins/overrides directory to the Docker host.

    docker run -d -p 8182:9080 -p 8545:9443 \  -e LICENSE=accept -u 50001 --hostname cs-graphql \  --restart=always \   -v /root/docker_data/graphql/logs:/opt/ibm/wlp/usr/servers/defaultServer/logs \  -v /root/docker_data/graphql/configDropins/overrides:/opt/ibm/wlp/usr/servers/defaultServer/configDropins/overrides \  --name graphql \  graphql:ga-555-p8cgql    

jvm.options

Start the container using the run script from the previous section, and copy the jvm.options from inside the container to the overrides directory, for example:

    docker cp graphql:/opt/ibm/wlp/usr/servers/defaultServer/jvm.options /root/docker_data/graphql/configDropins/overrides/jvm.options    

Add this JVM option to ensure that LTPA is used between GraphQL and Content Platform Engine servers:

  -Dcom.filenet.authentication.wsi.AuthTokenOrder=ltpa,oauth,oidc    

Update the CPE URI JVM option to point to your on-prem Content Platform Engine server running on WebSphere Application Server:

  -Decm.content.remote.cpeuri=http://cpe-host:9080/wsi/FNCEWS40MTOM    

Note: If you use an https URL to the Content Platform Engine server, make sure you import the Content Platform Engine server's SSL certificate into the Liberty truststore.

When done, your jvm.options should look similar to the following example:

    -Dcom.filenet.gcd.LicenseModel=FNCM.CU  -Dcom.filenet.AppServerType=liberty  -Dcom.filenet.authentication.wsi.AutoDetectAuthToken=true  -Dcom.filenet.authentication.wsi.AuthTokenOrder=ltpa,oauth,oidc  -Dhttps.protocols=TLSv1.2  -Decm.content.remote.cpeuri=http://cpe-host:9080/wsi/FNCEWS40MTOM  #-DtestUsername=admin  #-DtestPassword=password  -Dcom.ibm.ws.http.options.readTimeout=180  -Dcom.ibm.ws.http.options.writeTimeout=180  -XshowSettings:vm  -XX:InitialRAMPercentage=40  -XX:MaxRAMPercentage=66  -Dcom.ibm.ecm.content.graphql.enable.graphiql=FALSE  -DContainerType=1  -Dcom.ibm.jsse2.usefipsprovider=true  -Dcom.ibm.jsse2.sp800-131=transition  # other containers will add entries on the next line    

ltpa.keys

Copy the ltpa.keys files that you exported from the WebSphere Application Server instance for Content Platform Engine to the configDropins/overrides directory of your GraphQL server.

Create a ltpa.xml file that points to this ltpa.keys file and set the password to match the password used when you exported this file from the WebSphere Application Server instance for Content Platform Engine.

The following is a sample ltpa.xml file:

<server>

   <ltpa keysFileName="/opt/ibm/wlp/usr/servers/defaultServer/configDropins/overrides/ltpa.keys" keysPassword="XXXX"expiration="120" />

</server>

ldap.xml

Create an ldap.xml file in the configDropins/overrides directory to connect to the same LDAP server used by the WebSphere Application Server instance for Content Platform Engine.

Make sure you set the realm attribute of the ldap configuration to match the realm in the ltpa.keys file.  

The following is a sample ldap.xml that matches the configuration of the WebSphere Application Server instance for Content Platform Engine LDAP server.

<server>
        <ldapRegistry id="9.30.100.216" realm="ldap_realm"
                host="9.30.100.216"
                baseDN="OU=Engineering,OU=FileNet,DC=adam2016,DC=com" port="389"
                ldapType="Microsoft Active Directory"
                bindDN="CN=CEAdmin,OU=Shared,OU=Engineering,OU=FileNet,DC=adam2016,DC=com"
                sslEnabled="false" bindPassword="XXXX">
                <activedFilters
                        userFilter="(&amp;(objectClass=person)(cn=%v))"
                        groupFilter="(&amp;(objectClass=group)(cn=%v))" userIdMap="person:cn"
                        groupIdMap="*:cn">
                </activedFilters>
        </ldapRegistry>
</server>

Configuring GraphQL OAuth 2.0/OpenID Connect Authentication with LTPA SSO to Content Platform Engine

If Content Services GraphQL is authenticating using an OAuth 2.0 or OpenID Connect Identity Provider, then in the openidConnectClient configuration for GraphQL, make sure the realmName attribute is set to the same realm name in the ldap.xm and ltpa.keys file. This setting allows users of GraphQL to authenticate using OAuth/OIDC but use LTPA SSO to communicate with the Content Platform Engine server.

The following sample shows an oidc.xml configuration file that can be put in the GraphQL configDropins/overrides directory to authenticate with a UMS server:
<?xml version='1.0' encoding='UTF-8'?>
<server>
    <featureManager>
        <feature>openidConnectClient-1.0</feature>
    </featureManager>
    <openidConnectClient id="MyUms"
        clientId="myUms"
        clientSecret="XXXX"
        audiences="myUms"
        realmName="ldap_realm"
        userIdentifier="sub"
        uniqueUserIdentifier="uniqueSecurityName"
        userIdentityToCreateSubject="uniqueSecurityName"
        discoveryEndpointUrl="https://ums-host:port/oidc/endpoint/ums/.well-known/openid-configuration"
        mapIdentityToRegistryUser="false"
        scope="openid email profile"
        responseType="code"
        inboundPropagation="supported"
        signatureAlgorithm="RS256"
        authnSessionDisabled="false"
        validationMethod="introspect">
    </openidConnectClient>
</server>

When this openidConnectClient feature is used to authenticate users to GraphQL with the mapIdentityToRegistryUser="false" property set, the LDAP configuration in ldap.xml is no longer necessary and can be removed (if present) from the GraphQL configDropins/overrides directory.

Users authenticating using an OAuth 2.0 / OpenID Connect identity provider must also exist in the LDAP server used by Content Platform Engine under the same principal name.

Document Location

Worldwide

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSNVNV","label":"FileNet Content Manager"},"ARM Category":[{"code":"a8m0z000000cwLDAAY","label":"Container"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"5.5.4;and future releases","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
12 November 2020

UID

ibm16210693