Configuring users with an Identity Provider (IDP)

 For 20.0.1  Dynamic user provisioning requires you to configure at least two Identity Provider instances, one for the internal users and one or more for the external users. The Internal users are configured with an IDP that contains the same set of users as the LDAP server used by the Content Platform Engine in one of its directory configurations.

Before you begin

Note: This information applies if you want to use dynamic user provisioning in your External Share configuration. If you want to manage users with a second LDAP directory, this topic does not apply.

Set up the Managed User Directory configuration using the Administration Console for Content Platform Engine. Configure only one Managed User directory for the external users, even if more than one IDP is configured for the external users. The external users must be uniquely identified by the email address across all realms specified in the P8 domain, other than the Managed User Directory realm. To configure the Managed User Directory configuration see Configuring users with an identity provider.

All Identity Providers (IdPs) that support OAuth 2.0 or OpenID Connect authentication have a registration mechanism to identify the client application to the Identity Provider. At a minimum, a client ID, client secret, and redirect URLs to the client application are required by the OAuth 2.0 and OpenID Connect specifications.

For an example, you can review the Google Identity Platform documentation that describes how to obtain OAuth 2.0 credentials for applications: OpenID Connect.

When registering an application with an Identity Provider, you can use the same clientId registration for each of the IBM Content Navigator, External Share, and Content Platform Engine instances in your environment. You must provide a redirect URL for each of these instances using the following pattern:

https://<ingress_host>/oidcclient/redirect/<ExShareId>

Where:

<ingress_host> is the host name specified in the Ingress YAML file for configuring your IBM Content Navigator, External Share, and Content Platform Engine instance. For more information, see Configuring Ingress access for external share.

<ExShareId> is the ID that is used in the openIdConnectClient configuration for your IBM Content Navigator, External Share, and Content Platform Engine instance in the configuration file, for example, zoidc.xml. This ID is used in the redirection URI provided to the Identity Provider to configure the client ID redirection. For example, openidConnectClient id configured as ExShareGIDE for Content Platform Engine, ExShareGIDES for External Share, and ExShareGIDICN for IBM Content Navigator.

Each deployment requires a unique URI for redirection back from the Identity Provider to distinguish itself for the appropriate service. The URI are entered at the Identity providers registration page.

As an example, for Google Sign In Identity provider, the OAuth 2.0 client ID for ExShareGID would have three Authorized redirect URIs entered by the user, one for each deployment:

https://hostname.ingress.ibm.com/oidcclient/redirect/ExShareGIDE

https://hostname.ingress.ibm.com/oidcclient/redirect/ExShareGIDES

https://hostname.ingress.ibm.com/oidcclient/redirect/ExShareGIDICN

About this task

To prepare for managing users with an external and internal identity provider, you must configure your environment to communicate securely with the identity providers. Note that most configuration steps are repeated for each component container, IBM Content Navigator, External Share, and Content Platform Engine.

For an example, the following steps assume that you are using UMS for the internal identity provider, and Google Sign In for your external user identity provider.

Note: For V5.5.4 and later, name any files in the overrides directory with a z prefix. This ensures a file order that means that your version of the file, for example, zoidc.xml will override any other version.

Procedure

To configure user management with an Identity Provider (IDP):

  1. Import the Identity Provider SSL certificate into the application's (for example, IBM Content Navigator's) trust store:
    1. Obtain the identity provider's SSL certificate.
      The following example shows a command that you might use with a UMS or other WebSphere® Liberty based identity provider:
      keytool -exportcert -keystore key.p12 -storetype pkcs12 -alias default -rfc -file umscert.pem

      Google uses GlobalSign as the certificate authority for Google Sign In. You can obtain the certificate from your browser at https://accounts.google.com or download it from a site such as https://www.tbs-certificates.co.uk/FAQ/en/GlobalSign_Root_CA_R2_root.html

    2. Import this certificate in the IBM Content Navigator's trust store, giving it a unique alias name.

      Use the trust store that you created when you configured Ingress, for example, that you defined in zibm_custom-ssl.xml.

      The following examples show commands for importing your identity provider certificates into your custom trust store.

      For UMS:
      keytool -importcert -trustcacerts -keystore new_custom_tls.p12 -storetype pkcs12 -storepass PASSWORD -alias ums -file umscert.pem
      For Google:
      keytool -import -noprompt -keystore new_custom_tls.p12 -file globalsignrootca.crt -storepass changeit -v -alias gmailglobalsignrootca -storetype pkcs12
    3. Repeat these steps for the External Share and Content Platform Engine configurations.
  2. Configure JVM options for the IBM Content Navigator.
    1. Create the file ${server.config.dir}/configDropins/overrides/jvm.options with the following content: 
      -Dcom.filenet.authentication.providers=ExShareUmsInternal,ExShareGID
-Dcom.filenet.authentication.ExShareUmsInternal.displayname=Employee Login
-Dcom.filenet.authentication.ExShareGID.displayname=Google Sign-In
-Dcom.filenet.authentication.ExShareGID.AuthTokenOrder=oidc,oauth,ltpa
      Notes®:

      • com.filenet.authentication.providers

        This is a comma separated list of identity provider identifiers. There should be at least 2 identity providers: one for internal users (e.g. your employees) and one for external users.

      • com.filenet.authentication.<providerid>.displayname

        Using the <providerid> listed under com.filenet.authentication.providers, specify the text of the login button associated with that identity provider.

      • com.filenet.authentication.<providerid>.AuthTokenOrder=oidc,oauth,ltpa

        This option allows a different order to be applied for a specific identity provider when determining the authentication token type to be propagated to the Content Platform Engine server. For example, Google authentication requires that the OpenID Connect id_token is propagated to the Content Platform Engine server for SSO. Hence the oidc option is listed first, followed by oauth, then ltpa in the example above. These are the 3 authentication token types supported by the Content Platform Engine server.

  3. Configure Open Id Connect on the IBM Content Navigator:
    1. Create a file, for example zoidc.xml, in the configDropins/overrides directory that you created for the IBM Content Navigator deployment.
      You can start with the sample zoidc.xml file that is provided on the GitHub location. Your file must include the OpenID Client Connect information for both the internal and external identity providers, including the feature for Open Id Client Connect 1.0, an authFilter parameter for each identity provider, and the Open ID Client Connect values for each identity provider:
      <?xml version='1.0' encoding='UTF-8'?>
<server>
    <featureManager>
        <feature>openidConnectClient-1.0</feature>
    </featureManager>

    <webAppSecurity ssoCookieName="FileNetLtpaToken" overrideHttpAuthMethod="CLIENT_CERT" 
allowAuthenticationFailOverToAuthMethod="FORM" loginFormURL="/navigator/idplogin.jsp" 
loginErrorURL="/navigator/loginError.jsp" />

    <logging traceSpecification="com.ibm.ws.webcontainer.*=all:com.ibm.webcontainer.security.*=all:com.ibm.ws.security.*=all:com.ibm.websphere.security.*=all"
        consoleLogLevel="INFO"
        traceFileName="trace.log"
        maxFileSize="200"
        maxFiles="10"
        traceFormat="BASIC"/>

    <authFilter id="ExShareUmsInternalFilter">
        <cookie id="ExShareUmsInternalCookie" name="ExShareUmsInternal" matchType="contains"/>
        <cookie id="ltpatokencookie" name="FileNetLtpaToken" matchType="notContain"/>
    </authFilter>

    <openidConnectClient id="navigator"
        authFilterRef="ExShareUmsInternalFilter"
        clientId="navigator"
        clientSecret="xxxxxxxx"
        audiences="e,navigator,extshare"
        realmName="ExShareUmsInternal"
        userIdentifier="sub"
        uniqueUserIdentifier="uniqueSecurityName"
        userIdentityToCreateSubject="uniqueSecurityName"
        discoveryEndpointUrl="https://server_name:port/oidc/endpoint/ums/.well-known/openid-configuration"
        mapIdentityToRegistryUser="false"
        scope="openid email profile"
        responseType="id_token token"
        httpsRequired="true"
        tokenReuse="true"
	inboundPropagation="supported"
	signatureAlgorithm="RS256"
        authnSessionDisabled="false"
        disableLtpaCookie="false"
        validationMethod="introspect">
    </openidConnectClient>

    <authFilter id="ExShareGIDFilter">
        <cookie id="ExShareGIDCookie" name="ExShareGID" matchType="contains"/>
        <cookie id="ltpatokencookie" name="FileNetLtpaToken" matchType="notContain"/>
    </authFilter>

    <openidConnectClient id="ExShareGIDICN"
        authFilterRef="ExShareGIDFilter"
        clientId="xxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com"
        clientSecret="xxxxxxxxxxxxxxxxxxxx"
        audiences="xxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com"
        realmName="ExShareGIDICN"
        userIdentifier="email"
        uniqueUserIdentifier="email"
        userIdentityToCreateSubject="email"
        tokenReuse="true"
        discoveryEndpointUrl="https://accounts.google.com/.well-known/openid-configuration"
        mapIdentityToRegistryUser="false"
        scope="openid email profile"
        responseType="code"
        inboundPropagation="supported"
        signatureAlgorithm="RS256"
        authnSessionDisabled="false"
        disableLtpaCookie="true"
        validationMethod="introspect"
        issuerIdentifier="https://accounts.google.com"
        jwkClientId="xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com"
        jwkClientSecret="xxxxxxxxxxxxxx"
        jwkEndpointUrl="https://www.googleapis.com/oauth2/v3/certs"
        discoveryEndpointUrl=https://accounts.google.com/.well-known/openid-configuration
        userIdentifier="email"
        uniqueUserIdentifier="email"
        userIdentityToCreateSubject="email”>
    </openidConnectClient>

</server>
    2. Confirm or set your values for the internal and external authFilter parameters.

      The authFilter for IBM Content Navigator uses a cookie. This cookie value is set when the user clicks the button on the login dialog that corresponds to identity provider. In the ExShareUmsInternalFilter authFilter, the name given for cookie ExShareUmsInternalCookie must match the corresponding providerid specified in the jvm.options (i.e. ExShareUmsInternal).

      Likewise, for the ExShareGIDFilter authFilter, the name given for cookie ExShareGIDCookie must match the corresponding providerid specified in the jvm.options (i.e. ExShareGID).

    3. Confirm or set your values for the openidConnectClient parameters.

      The value for id, for example, "navigator", must match the target of a redirect_uri in the registration with the identity provider. For example,

      https://icn-host:9443/oidcclient/redirect/ExShareUms

      The value for realmName must match the corresponding providerid specified in jvm.options. For example in the navigator configuration, the realmName property is set to ExShareUmsInternal.

      The value for audiences must include your clientId plus the clientId of other applications that you interact with. For example in the navigator configuration, the audiences property is set to e,navigator,extshare. Depending on your identity provider, additional configuration might be required to support this scenario. For more details, refer to Configuring an OpenID Connect Client to use the RSA-SHA256 algorithm for signing ID tokens.

    4. Update the values for the clientId and clientSecret for the external Identity Provider.
      The following example shows a sample format for values for a Google ID configuration:
      clientId="xxxxxxxxxxxxxxxx.apps.googleusercontent.com"
clientSecret="xxxxxxxxxxxxxxxxxxxxxx"
audiences="xxxxxxxxx-xxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com”
    5. Update other values that are specific to your external Identity Provider.
    6. Add values to override the web.xml: 
      
    <webAppSecurity ssoCookieName="FileNetLtpaToken" overrideHttpAuthMethod="CLIENT_CERT" 
allowAuthenticationFailOverToAuthMethod="FORM" loginFormURL="/navigator/idplogin.jsp" 
loginErrorURL="/navigator/loginError.jsp" />
    7. Save all changes to the zoidc.xml file.
  4. Configure JVM options for External Share:
    1. Create the file ${server.config.dir}/configDropins/overrides/jvm.options with the following content: 
      
-Dcom.filenet.authentication.ExShareGID.AuthTokenOrder=oidc,oauth,ltpa

      Notes:

      com.filenet.authentication.<providerid>.AuthTokenOrder=oidc,oauth,ltpa

      This option allows a different order to be applied for a specific identity provider when determining the authentication token type to be propagated to the Content Platform Engine server. For example, Google authentication requires that the OpenID Connect id_token is propagated to the Content Platform Engine server for SSO. Hence the oidc option is listed first, followed by oauth, then ltpa in the example above. These are the 3 authentication token types supported by the Content Platform Engine server. The <providerid> comes from the realm associated to the inbound SSO token. This realm is set by the sender of the SSO token, for example, IBM Content Navigator, via the realmName attribute of the sender's openidConnectClient configuration.

  5. Configure Open Id Connect for External Share:
    1. Create a file called zoidc.xml in the configDropins/overrides directory that you created for the External Share deployment.
      You can start with the sample zoidc.xml file that is provided on the git hub location:
      <?xml version='1.0' encoding='UTF-8'?>
<server>
    <featureManager>
        <feature>openidConnectClient-1.0</feature>
    </featureManager>

    <webAppSecurity ssoCookieName="FileNetLtpaToken" overrideHttpAuthMethod="CLIENT_CERT" allowAuthenticationFailOverToAuthMethod="BASIC"/>

    <authFilter id="ExShareUmsInternalFilter">
        <requestHeader id="ExShareUmsInternalHeader" name="auth-token-realm" value="ExShareUmsInternal" matchType="contains"/>
        <cookie id="ltpatokencookie" name="FileNetLtpaToken" matchType="notContain"/>
    </authFilter>

    <openidConnectClient id="extshare"
        authFilterRef="ExShareUmsInternalFilter"
        clientId="extshare"
        clientSecret="xxxxxxxxx"
        audiences="e,navigator,extshare"
        realmName="ExShareUmsInternal"
        userIdentifier="sub"
        uniqueUserIdentifier="uniqueSecurityName"
        userIdentityToCreateSubject="uniqueSecurityName"
        discoveryEndpointUrl="https://e-ums1.fyre.ibm.com:9443/oidc/endpoint/ums/.well-known/openid-configuration"
        mapIdentityToRegistryUser="false"
        scope="openid email profile"
        responseType="code"
        inboundPropagation="supported"
        signatureAlgorithm="RS256"
        authnSessionDisabled="false"
        disableLtpaCookie="true"
        validationMethod="introspect">
    </openidConnectClient>

    <authFilter id="ExShareGIDFilter">
        <requestHeader id="ExShareGIDHeader" name="auth-token-realm" value="ExShareGID" matchType="contains"/>
        <cookie id="ltpatokencookie" name="FileNetLtpaToken" matchType="notContain"/>
    </authFilter>

    <openidConnectClient id="ExShareGIDES"
        authFilterRef="ExShareGIDFilter"
        clientId="xxxx.apps.googleusercontent.com"
        clientSecret="xxxxxx"
        audiences="xxxx.apps.googleusercontent.com"
        realmName="ExShareGID"
        userIdentifier="email"
        uniqueUserIdentifier="email"
        userIdentityToCreateSubject="email"
        tokenReuse="true"
        discoveryEndpointUrl="https://accounts.google.com/.well-known/openid-configuration"
        mapIdentityToRegistryUser="false"
        scope="openid email profile"
        responseType="code"
        inboundPropagation="supported"
        signatureAlgorithm="RS256"
        authnSessionDisabled="false"
        disableLtpaCookie="true"
        validationMethod="introspect"
        issuerIdentifier="https://accounts.google.com"
        jwkClientId="xxxxxxxxxx-xxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com"
        jwkClientSecret="xxxxxxxxxxxxxxxxxxx"
        jwkEndpointUrl="https://www.googleapis.com/oauth2/v3/certs"
        discoveryEndpointUrl=https://accounts.google.com/.well-known/openid-configuration
        userIdentifier="email"
        uniqueUserIdentifier="email"
        userIdentityToCreateSubject="email”>
    </openidConnectClient>

</server>
    2. Confirm or set your values for the internal and external authFilter parameters.
      The authFilter for External Share uses a HTTP request header with name of "auth-token-realm" and value corresponding to the identity provider. In the example, the value is ExShareUmsInternal for the identity provider used for internal users and is ExShareGID for the Google Sign In identity provider used for external users.
    3. Confirm or set your values for the openidConnectClient parameters.
      • The value for id, for example, "extshare", must match the target of a redirect_uri in the registration with the identity provider. For example,

        https://es-host:9443/oidcclient/redirect/ExShareUms

      • The value for realmName must match the corresponding providerid specified in jvm.options. For example in the ExShareUms configuration, the realmName property is set to ExShareUmsInternal.
      • The value for audiences must include your clientId plus the clientId of other applications that might invoke this application with an OpenID Connect token. For example in the extshare configuration, the audiences property is set to e,navigator,extshare. Depending on your identity provider, additional configuration might be required to support this scenario. For more details, refer to Configuring an OpenID Connect Client to use the RSA-SHA256 algorithm for signing ID tokens.
    4. Update the values for the clientId and clientSecret for the external Identity Provider.
      The following example shows a sample format for values for a Google ID configuration:
      clientId="xxxxxxxxxxxxxxxx.apps.googleusercontent.com"
clientSecret="xxxxxxxxxxxxxxxxxxxxxx"
audiences="xxxxxxxxx-xxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com”
    5. Update other values that are specific to your external Identity Provider.
    6. Add values to override the web.xml: 
       <webAppSecurity ssoCookieName="FileNetLtpaToken" overrideHttpAuthMethod="CLIENT_CERT" allowAuthenticationFailOverToAuthMethod="BASIC"/>
    7. Save all changes to the zoidc.xml file.
  6. Configure Open Id Connect on the Content Platform Engine:
    1. Create a file called zoidc.xml in the overrides directory that you created for the Content Platform Engine deployment.
      You can start with the sample zoidc.xml file that is provided on the git hub location:
      <?xml version='1.0' encoding='UTF-8'?>
<server>
    <featureManager>
        <feature>openidConnectClient-1.0</feature>
    </featureManager>

    <authFilter id="ExShareUmsInternalFilter">
        <requestHeader id="ExShareUmsInternalHeader" name="auth-token-realm" value="ExShareUmsInternal" matchType="contains"/>
    </authFilter>

    <openidConnectClient id="e"
        authFilterRef="ExShareUmsInternalFilter"
        clientId="e"
        clientSecret="xxxxxxx"
        audiences="e,navigator,extshare"
        realmName="ExShareUmsInternal"
        userIdentifier="sub"
        uniqueUserIdentifier="uniqueSecurityName"
        userIdentityToCreateSubject="uniqueSecurityName"
        discoveryEndpointUrl="https://e-ums1.fyre.ibm.com:9443/oidc/endpoint/ums/.well-known/openid-configuration"
        mapIdentityToRegistryUser="false"
        scope="openid email profile"
        responseType="code"
        inboundPropagation="supported"
        signatureAlgorithm="RS256"
        authnSessionDisabled="false"
        validationMethod="introspect">
    </openidConnectClient>

    <authFilter id="ExShareGIDFilter">
        <requestHeader id="ExShareGIDHeader" name="auth-token-realm" value="ExShareGID" matchType="contains"/>
    </authFilter>

    <openidConnectClient id="ExShareGIDE"
        authFilterRef="ExShareGIDFilter"
        clientId="530122881973-fuotgltih4t5e3335im9aeca2uql7q52.apps.googleusercontent.com"
        clientSecret="YPcdr1FifclLuF2Dyu164WWD"
        audiences="530122881973-fuotgltih4t5e3335im9aeca2uql7q52.apps.googleusercontent.com"
        realmName="ExShareGID"
        userIdentifier="email"
        uniqueUserIdentifier="email"
        userIdentityToCreateSubject="email"
        tokenReuse="true"
        discoveryEndpointUrl="https://accounts.google.com/.well-known/openid-configuration"
        mapIdentityToRegistryUser="false"
        scope="openid email profile"
        responseType="code"
        inboundPropagation="supported"
        signatureAlgorithm="RS256"
        authnSessionDisabled="false"
        validationMethod="introspect"
        issuerIdentifier="https://accounts.google.com"
        jwkClientId="530122881973-fuotgltih4t5e3335im9aeca2uql7q52.apps.googleusercontent.com"
        jwkClientSecret="YPcdr1FifclLuF2Dyu164WWD"
        jwkEndpointUrl="https://www.googleapis.com/oauth2/v3/certs"
        discoveryEndpointUrl=https://accounts.google.com/.well-known/openid-configuration
        userIdentifier="email"
        uniqueUserIdentifier="email"
        userIdentityToCreateSubject="email”>
    </openidConnectClient>

</server>
    2. Confirm or set your values for the internal and external authFilter parameters.
      The authFilter for Content Platform Engine uses an HTTP request header with name of "auth-token-realm" and value corresponding to the identity provider. In the example, the value is ExShareUmsInternalfor the identity provider used for internal users and is ExShareGID for the Google Sign In identity provider used for external users.
    3. Confirm or set your values for the openidConnectClient parameters.
      • The value for id, for example, "e", must match the target of a redirect_uri in the registration with the identity provider. For example,

        https://e-host:9443/oidcclient/redirect/e

      • The value for realmName must match the corresponding providerid associated with the inbound SSO token. For example in the e configuration, the realmName property is set to ExShareUmsInternal.
      • The value for audiences must include your clientId plus the clientId of other applications that you interact with. For example in the e configuration, the audiences property is set to e,navigator,extshare. Depending on your identity provider, additional configuration might be required to support this scenario. For more details, refer to Configuring an OpenID Connect Client to use the RSA-SHA256 algorithm for signing ID tokens
    4. Update the values for the clientId and clientSecret for the external Identity Provider.
      The following example shows a sample format for values for a Google ID configuration:
      clientId="xxxxxxxxxxxxxxxx.apps.googleusercontent.com"
clientSecret="xxxxxxxxxxxxxxxxxxxxxx"
audiences="xxxxxxxxx-xxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com”
    5. Update other values that are specific to your external Identity Provider.
    6. Save all changes to the zoidc.xml file.