Setting up SSO authentication

To configure LTPA token authentication:

1. Copy the ltpa.keys file from the Content Platform Engine server to the ${server.config.dir}/resources/security/ltpa.keys directory on the Content Platform Engine client's WebSphere Liberty server.
2. From the Content Platform Engine Liberty server's configuration, copy the same LTPA configuration into the server.xml file of the client, for example:

    <ltpa keysFileName="${server.config.dir}/resources/security/ltpa.keys" keysPassword="{xor}Lz4sLChvLTs=" expiration="120" />

3. Remove legacy JVM options on the Content Platform Engine client.
   Examples of clients include IBM Content Navigator, External Share, and Content Services GraphQL. Remove the following arguments:

   -DFileNet.WSI.AutoDetectLTPAToken=true
   -Dcom.filenet.authentication.token.userid=sso:ltpa 

   Note: For V5.5.4, keep the -Dcom.filenet.authentication.token.userid=sso:ltpa argument. Remove it for V5.5.5.
4. Add the following JVM option on the Content Platform Engine client:

   -Dcom.filenet.authentication.wsi.AutoDetectAuthToken=true

5. Remove the following legacy JVM options on the Content Platform Engine server:

   -DFileNet.WSI.AutoDetectLTPAToken=true

To configure OAuth or OpenID token authentication:

1. Register Content Platform Engine and the Content Platform Engine clients with the identity provider.

   All identity providers (IdP) supporting OAuth 2.0 and OpenID Connect authentication have registration mechanisms to identify the client application to the IdP. At a minimum a client id, client secret, and redirect URL or URLs to the client application are required by the OAuth 2.0 and OpenID Connect specifications.

   The same client registration can be used by multiple related applications. You can register a clientId once and use that same clientId for Content Platform Engine and its client applications like IBM Content Navigator, External Share, and Content Services GraphQL.

   The following example shows the JSON posted to a UMS registration endpoint to register Content Platform Engine and its client applications. A description of each of these parameters can be found in https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/twlp_client_registration.html

   POST https://my-ums-host:9443/oidc/endpoint/ums/registration
   {
       "token_endpoint_auth_method": "client_secret_basic",
       "scope": "openid profile email",
       "grant_types": [
           "authorization_code",
           "client_credentials",
           "implicit",
           "refresh_token",
           "urn:ietf:params:oauth:grant-type:jwt-bearer"
       ],
       "response_types": [
           "code",
           "token",
           "id_token token"
       ],
       "application_type": "web",
       "subject_type": "public",
       "post_logout_redirect_uris": [],
       "preauthorized_scope": "openid profile email",
       "introspect_tokens": true,
       "trusted_uri_prefixes": [
           "https://my-cpe-server/",
    "https://my-cpe-client/",
       ],
       "resource_ids": [],
       "functional_user_groupIds": [],
       "client_id": "filenetP8Ums",
       "client_secret": "XXXX",
       "client_name": "FileNet P8 UMS",
       "redirect_uris": [
          "https://my-cpe-server:9443/oidcclient/redirect/FileneP8Ums",
   "https://my-app:9443/oidcclient/redirect/FileneP8Ums",
   "regexp:https://my-cpe-client:!d*/oidcclient/redirect/FileneP8Ums",
   "regexp:https://my-cpe-client:!d*/ibm/api/social-login/redirect/FileneP8Ums"
       ],
       "allow_regexp_redirects": true
   }

   Note the following information for this sample:

   • Multiple redirect_uris can be specified if there are multiple applications or multiple instances of the same application that will use this client_id.
   • If allow_regexp_redirects is true, then you can use regular expressions in the redirect_uris. Prefix the URI with "regexp:" if specifying a regular expression, as shown in the examples above.
   • The middle part of the redirect_uri depends on which OIDC client configuration you are using for your application.
     • If you are using openidConnectClient, then use /oidcclient/redirect/
     • If you are using oidcLogin (from the social-login feature), then use /ibm/api/social-login/redirect
   • The last part of the redirect_uri, for example, FilenetP8Ums, corresponds to the id of the openidConnectClient or oidcLogin stanza that is used in your application configuration.
   • The trusted_uri_prefixes should correspond to those specified in the redirect_uris.
   • If you need to retrieve the current registration for your application, use a GET request with your client_id at the end of the URL, for example:

     GET https://my-ums-host:9443/oidc/endpoint/ums/registration/filenetP8Ums

   • If you need to update the current registration for your application, use a PUT request with your client_id at the end of the URL with body contents similar to your original POST request, for example:

     PUT https://my-ums-host:9443/oidc/endpoint/ums/registration/filenetP8Ums

2. Import the identity provider SSL certificate into the application trust store.

   When an OIDC RP, for example, the Content Platform Engine or the Content Platform Engine client, receives a request with a Bearer token in the Authorization header, it must validate the token with the Identity Provider that created it to confirm that it is still valid. This confirmation requires that the Liberty server contact the Identity Provider at a validation endpoint URI. To verify that this validation endpoint URI is trusted, the SSL certificate that is associated to that URI must be imported into the OIDC RP (the Content Platform Engine or the Content Platform Engine client) trust store.

   For a UMS server, use a command similar to the following to export the default SSL certificate into a file that will be imported in to the Content Services trust store:

   keytool -exportcert -keystore key.jks -alias default -rfc -file umscert.pem

   Then on your application's Liberty server, import this certificate into the trust store, giving the certificate a unique alias name. The command to import this certificate depends on the type of trust store that is being used by the Liberty server. Below are example commands for some of the more common trust store types. Also note that a key store and a trust store are often the same file, as shown in the examples below.

   JKS trust store:

   keytool -importcert -noprompt -keystore key.jks -file umscert.pem -storepass PASSWORD -v -alias ums

   JCEKS trust store:

   keytool -importcert -keystore keys.jceks -storepass PASSWORD -file umscert.pem -v -alias ums -storetype JCEKS

   PKCS12 trust store

   keytool -importcert -trustcacerts -keystore key.p12 -storetype pkcs12 -storepass PASSWORD -alias ums -file umscert.pem

   Your application's Liberty configuration likely has an entry like the following identifying the keystore being used. If there is no separate defaultTrustStore defined, then the defaultKeyStore is used as the trust store.

   <keyStore id="defaultKeyStore" location="${server.config.dir}/resources/security/key.p12" password="PASSWORD"/>

3. Set up the Content Platform Engine client.
   When you configure OAuth/OIDC for the Content Platform Engine, you have two choices:

   openidConnectClient feature

   Use this feature if your Content Platform Engine client does not (normally) have a web browser interface. This feature has a richer set of configurable options for better interoperability with various identity providers. Its options are also more similar to that found in WebSphere traditional application server.

   Use this feature for the following applications:

   • IBM Content Navigator
   • Content Services GraphQL API
   • External Share
   • Content Platform Engine test clients

   social-login feature

   Use this feature if your Content Platform Engine client application uses a web browser interface that requires a login dialog to select among different identity providers or local authentication with an internal LDAP provider. Note that this login dialog works only on Liberty and is not available on WebSphere Application Server traditional.

   This feature also has some pre-built configuration for some popular social media identity providers such as Google and FaceBook that might make integrating with these providers simpler.

   • Configure openidConnectClient-1.0
     Use the following configuration file, for example, oidc.xml, to configure OAuth or OIDC for your application when using the openidConnectClient feature. This file can be placed in the configDropins/overrides directory of your Liberty server.

     <?xml version='1.0' encoding='UTF-8'?>
     <server>
         <featureManager>
             <feature>openidConnectClient-1.0</feature>
         </featureManager>
     
         <openidConnectClient id="FilenetP8Ums"
             scope="openid profile email"
             responseType="id_token token"
             clientId="filenetP8Ums"
             clientSecret="XXXX"
             issuerIdentifier="https://my-ums-host:9443/oidc/endpoint/ums"
             audiences="filenetP8Ums,anotherClientUms"
             validationMethod="introspect"
             inboundPropagation="supported"
             signatureAlgorithm="RS256"      
             jwkEndpointUrl="https://my-ums-host:9443/oidc/endpoint/ums/jwk"
             validationEndpointUrl="https://my-ums-host:9443/oidc/endpoint/ums/introspect"
             authorizationEndpointUrl="https://my-ums-host:9443/oidc/endpoint/ums/authorize"
             tokenEndpointUrl="https://my-ums-host:9443/oidc/endpoint/ums/token">
         </openidConnectClient>
     </server>

     Additional documentation on these configuration settings can be found in the following topic: https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.liberty.autogen.nd.doc/ae/rwlp_config_openidConnectClient.html

     See the following important notes about this configuration:

     • The clientId and clientSecret must match the the client_id and client_secret values you used when you registered with the identity provider.
     • The application with this configuration must run on a host matching one of the redirect_uris in the registration with the identity provider.
     • The openidConnectClient id, for example FilenetP8Ums, must match the target of a redirect_uri in the registration with the identity provider, for example: https://my-app:9443/oidcclient/redirect/FileneP8Ums
     • The value for issuerIdentifier must match how the identity provider, such as UMS, sees its URI. For example, if UMS is running in a Docker container under port 9443, but due to port mapping the UMS server is actually accessed externally via a different port number, the issuerIdentifier port must be 9443 because that is how the Liberty server inside the docker container sees its URI.
     • The value for audiences should contain your clientId as well as the clientIds of other applications, for example anotherClientUms, that will communicate with your application using OAuth or OIDC.
     • The clientId is how the identity provider verifies the request is coming from a valid location. The audiences is how the Liberty server hosting your application verifies the received authentication token was meant for it and not some other application.
     • Not all identity providers support the JWK endpoint to validate the OIDC token. The alternative is to import the idP's public key into your Liberty servers keystore as described in https://www.ibm.com/support/knowledgecenter/SSD28V_liberty/com.ibm.websphere.wlp.core.doc/ae/twlp_oidc_rsa_sha.html
   • Configure socialLogin-1.0.
     Use the following configuration file, for example oidc.XML, to configure OAuth/OIDC for your application when using the social-login feature. This file can be placed in the configDropins/overrides directory of your Liberty server.

     <?xml version='1.0' encoding='UTF-8'?>
     <server>
       <featureManager>
         <feature>socialLogin-1.0</feature>
       </featureManager>
     
       <oidcLogin id="FilenetP8Ums"
         clientId="filenetP8Ums"
         clientSecret="XXXX"
         displayName="Authenticate with UMS"
         scope="openid profile email"
         responseType="code"
         hostNameVerificationEnabled="false"
         userNameAttribute="sub"
         userUniqueIdAttribute="uniqueSecurityName"
         redirectToRPHostAndPort="https://my-app:9443"
         signatureAlgorithm="RS256"
         issuer="https://my-ums-host:9443/oidc/endpoint/ums"
         jwkClientId="filenetP8Ums"
         jwkClientSecret="XXXX"
         jwksUri="https://my-ums-host:9443/oidc/endpoint/ums/jwk"
         authorizationEndpoint="https://my-ums-host:9443/oidc/endpoint/ums/authorize"
         tokenEndpoint="https://my-ums-host:9443/oidc/endpoint/ums/token"
         userInfoEndpointEnabled="true"
         userInfoEndpoint="https://my-ums-host:9443/oidc/endpoint/ums/userinfo"
         isClientSideRedirectSupported="true">
       </oidcLogin>
     
       <socialLoginWebapp enableLocalAuthentication="true" />
     
     </server>

     This configuration uses the generic OIDC capabilities of the social-login feature. Additional documentation on these configuration settings can be found in https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.liberty.autogen.nd.doc/ae/rwlp_config_oidcLogin.htmlOther social media identity providers, for example Google, Facebook, GitHub, and so on, can be configured using the settings described in https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/twlp_sec_sociallogin.html

     See the following important notes about this configuration:

     • The clientId and clientSecret must match the the client_id and client_secret values you used when you registered with the identity provider.
     • The application with this configuration must run on a host matching one of the redirect_uris you used when you registered with the identity provider.
     • The oidcLogin id, for example FilenetP8Ums, must match the target of a redirect_uri you used when you registered with the identity provider, for example, https://my-app:9443/oidcclient/redirect/FileneP8Ums
     • The value for issuer must match how the identity provider such as UMS sees its URI. For example if UMS is running in a Docker container under port 9443, but due to port mapping the UMS server is actually accessed externally via a different port number, the issuerIdentifier port must be 9443, because that is how the Liberty server inside the Docker container sees its URI.
     • The redirectToRPHostAndPort (such as https://my-app:9443) must match the host and port of your application
     • The jwkClientId and jwkClientSecret should be the same values as your clientId and clientSecret, respectively.
   1. Remove all additional legacy JVM arguments.
      If the following legacy JVM arguments are specified in the jvm.options file for your application, remove them:

      -DFileNet.WSI.AutoDetectLTPAToken=true
      -Dcom.filenet.authentication.token.userid=sso:ltpa 

   2. Add the following JVM argument:

      -Dcom.filenet.authentication.wsi.AutoDetectAuthToken=true

   3. Determine which authentication token to send on CEWS request.

      If multiple authentication token types are found by the CE API, for example, Jace.jar, then the default priority order for using a particular token type is: OAuth, OIDC, and LTPA. Hence, if all three token types are found by the CE API, then the OAuth token will be the one sent on the CEWS request. If only an LTPA token is found on the JAAS subject, the LTPA token will be sent on the CEWS request.

      This order can be changed using the following JVM argument, where a comma separated list of the different authentication token types can be specified in the desired order:

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

4. Set up the Content Platform Engine server:
   1. Configure openidConnectClient-1.0
      Use the following configuration file, for example, oidc.xml, to configure OAuth or OIDC for your application when using the openidConnectClient feature. This file can be placed in the configDropins/overrides directory of your Liberty server.

      <?xml version='1.0' encoding='UTF-8'?>
      <server>
          <featureManager>
              <feature>openidConnectClient-1.0</feature>
          </featureManager>
      
          <openidConnectClient id="FilenetP8Ums"
              scope="openid profile email"
              responseType="id_token token"
              clientId="filenetP8Ums"
              clientSecret="XXXX"
              issuerIdentifier="https://my-ums-host:9443/oidc/endpoint/ums"
              audiences="filenetP8Ums,anotherClientUms"
              validationMethod="introspect"
              inboundPropagation="supported"
              signatureAlgorithm="RS256"      
              jwkEndpointUrl="https://my-ums-host:9443/oidc/endpoint/ums/jwk"
              validationEndpointUrl="https://my-ums-host:9443/oidc/endpoint/ums/introspect"
              authorizationEndpointUrl="https://my-ums-host:9443/oidc/endpoint/ums/authorize"
              tokenEndpointUrl="https://my-ums-host:9443/oidc/endpoint/ums/token">
          </openidConnectClient>
      </server>

      Additional documentation on these configuration settings can be found in the following topic: https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.liberty.autogen.nd.doc/ae/rwlp_config_openidConnectClient.html

      See the following important notes about this configuration:

      • The clientId and clientSecret must match the the client_id and client_secret values you used when you registered with the identity provider.
      • The application with this configuration must run on a host matching one of the redirect_uris in the registration with the identity provider.
      • The openidConnectClient id, for example FilenetP8Ums, must match the target of a redirect_uri in the registration with the identity provider, for example: https://my-app:9443/oidcclient/redirect/FileneP8Ums
      • The value for issuerIdentifier must match how the identity provider, such as UMS, sees its URI. For example, if UMS is running in a Docker container under port 9443, but due to port mapping the UMS server is actually accessed externally via a different port number, the issuerIdentifier port must be 9443 because that is how the Liberty server inside the docker container sees its URI.
      • The value for audiences should contain your clientId as well as the clientIds of other applications, for example anotherClientUms, that will communicate with your application using OAuth or OIDC.
      • The clientId is how the identity provider verifies the request is coming from a valid location. The audiences is how the Liberty server hosting your application verifies the received authentication token was meant for it and not some other application.
      • Not all identity providers support the JWK endpoint to validate the OIDC token. The alternative is to import the idP's public key into your Liberty servers keystore as described in https://www.ibm.com/support/knowledgecenter/SSD28V_liberty/com.ibm.websphere.wlp.core.doc/ae/twlp_oidc_rsa_sha.html
   2. Remove legacy JVM arguments.
      If the following legacy JVM argument is specified in the jvm.options file for your application, remove it:

      -DFileNet.WSI.AutoDetectLTPAToken=true
      -Dcom.filenet.authentication.token.userid=sso:ltpa

      Note: Keep -Dcom.filenet.authentication.token.userid=sso:ltpa if you are on V5.5.4. Remove it if you are on V5.5.5 or later.

      The following JVM argument is still required if you are using LTPA:

      
      -Dcom.filenet.authentication.token.userid=sso:ltpa 

   3. Add or confirm the following JVM argument:

      -Dcom.filenet.authentication.wsi.AutoDetectAuthToken=true

      Note: This argument is set by default in V5.5.4 and later.