(V5.5.5 and later) Configuring an identity provider connection

You can use an identity provider to manage user authentication for your container environment. You can use this approach to manage and automatically register both internal users and users that you designate for external sharing of items.

Before you begin

Check the IBM® Software Product Compatibility Report for the appropriate versions of supporting software.

About this task

In your container environment, you can use an external OIDC/OAuth identity provider to manage authentication in the following two scenarios:

Internal users of your content repository: For internal users, you configure a managed user realm and set identity rules that govern which sets of users have access to your domain, based on email suffix or address. This configuration can apply both with and without an external share configuration. This configuration also requires a basic LDAP service for default config and admin user access to the domain.
External users with whom you want to share limited access to items in your content repository: For external users, you similarly configure an authentication realm for managing the external users. You can combine external share OIDC/OAuth user authentication with traditional LDAP user management for internal users, or use an identity provider for both internal and external users. If you want to user LDAP authentication for both internal and external users, skip this procedure and set up your LDAP directory servers instead. For details, see Configuring the external user LDAP realm.

Important: With an identity provider, user registration is by the email address of the user, and the email address must be unique not only across all managed users, but also must not collide with the short name of any LDAP user or group. Configuration settings called identity rules can restrict which email addresses can be registered as managed users and control which users can register themselves.

To prepare this connection for your container environment, you set up your identity provider, register your clients with the identity provider, and create secrets with your connection credentials. To register your clients- at a minimum, Content Platform Engine and Navigator- you must provide a redirect URI for each component in the following format:https://ingress-cpe:<hostname>.

When you prepare your environment, record the settings so that these values are available to enter into the custom resource YAML file for deployment and configuration. For lists of the parameters that you need to collect, see Identity provider configuration parameters.

After you configure your identity provider connection and provide the relevant details in your custom resource YAML file, the operator creates the identity provider configuration for your container environment.

Procedure

To configure the identity provider connection:

Prepare a draft redirect URL value to use when you register your components as clients of the identity provider.
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.es-<ingress_host>/oidcclient/redirect/<Provider ID for each instance>
```
You confirm the values for these redirect URLs after your container deployment completes. At that time you determine the final URL and reset the URL values with the identity provider.
Create your identity provider application.

Remember: Check the Software Product Compatibility Report for details on what identity providers are supported.
Register your components as clients of the identity provider that you configured.

On your cluster, create an identity prover secret with the client ID and client secret from the identity provider:

For Open Shift Cloud Platform:

oc create -f <IdP secret YAML file> -n <namespace>

For generic Kubernetes:

kubectl create -f <IdP secret YAML file> -n <namespace>

Note: Use base64 encoding to encrypt the secret.

The IdP secret YAML file looks something like the following example:

apiVersion: v1
data:
  client_id: <client ID from your IdP with base64 encryption>
  client_secret: <client secret from your IdP with base64 encryption> 
kind: Secret
metadata:
  creationTimestamp: null
  labels:
    app: sample-oidc-google-secret
    app.kubernetes.io/instance: <namespace>
    app.kubernetes.io/managed-by: <namespace>
    app.kubernetes.io/name: <namespace>
    release: 20.0.2
  name: sample-oidc-google-secret
type: Opaque

Create additional secrets with the certificates from the identity provider.
1. Contact the identity provider administrator to get the certificate or instructions to download the certificate.
2. Save the certificate file to a location in your container environment.
3. From the directory where the downloaded certificate file is located, run the following command:
```
kubectl create secret generic <secret name> --from-file=tls.crt=<CERT FILE_NAME> -n <namespace>
```
  Note: The tls.crt component is part of the command and must not be changed.
  For example, for Google:
```
oc create secret generic gmail-tls --from-file=tls.crt=gmail_tls2.cert -n <namespace>
```
  When you add your values to the custom resource YAML file, add the secret name as the value for trusted_certificate_list, and include the square brackets around the secret name.
```
shared_configuration:
  …
    tls:
      trusted_certificate_list: [adw-tls-secret, baw-tls-secret, aca-tls-secret]
```

Compile the values to add to the custom resource YAML file that you will use for deployment:

For example:

shared_configuration:
    open_id_connect_providers:
    - provider_name: "ExShareGID"
      display_name: "Google"
      client_oidc_secret:
         es: "sample-oidc-google-secret" # Points to a secret with client_id and client_secret in that format.
         nav: "sample-oidc-google-secret" # Points to a secret with client_id and client_secret in that format.
         cpe: "sample-oidc-google-secret" # Points to a secret with client_id and client_secret in that format.
         graphql: "sample-oidc-google-secret" # Points to a secret with client_id and client_secret in that format.
      issuer_identifier: "https://accounts.google.com"
      # REQUIRED PROPERTIES AND VALUES which are common
      # If not set will be set to the defaults.
      response_type: "id_token token"
      scope: "openid email profile"
      map_identity_to_registry_user: "false"
      authn_session_disabled: "false"
      inbound_propagation: "supported"
      https_required: "true"
      validation_method: "introspect"
      disable_ltpa_cookie: "true"
      signature_algorithm: "RS256"
      user_identifier: "email" # sub for ums and ibm id, email for google
      unique_user_identifier: "email" # sub for ums and ibm id, email for google
      user_identity_to_create_subject: "email" # sub for ums and ibm id, email for google
      # Uncomment out discovery_endpoint_url for Google or UMS IdP.
      discovery_endpoint_url: "https://accounts.google.com/.well-known/openid-configuration" 
      # authorization_endpoint_url: ""
      # token_endpoint_url: ""
      # validation_endpoint_url: ""
      # trust_alias_name: "secrent name you created"
      # disables_iss_checking: "true"
      # jwk_client_oidc_secret:
      #   es: "" # Points to a secret with client_id and client_secret in that format.
      #   nav: "" # Points to a secret with client_id and client_secret in that format.
      #   cpe: "" # Points to a secret with client_id and client_secret in that format.
      #  graphql: "" 
      # token_reuse: "true"
#       oidc_ud_param:
#       - 'DELIM=;KEY1;value1'
#       - "key2:value2"

The sample is specifically for Google ID. The sample provides the common shared parameters required for most IdPs, but each IdP may need different parameters added or removed. You can refer to your specific IdP documentation for the exact parameters and uncomment or add in parameters accordingly in the CR file.

If you have more than one identity provider, you add a stanza and record values for each provider. For more information on the parameters and values, see Identity provider configuration parameters.

If any required parameters are not provided in the sample, you can add them as a list of strings such as 'key:value' in the oidc_ud_param:

oidc_ud_param:
       - 'DELIM=;KEY1;value1'
       - "key2:value2"

The operator splits the string by the default delimiter, a colon (:). If the value of a required parameter contains a colon (:), such as in a URL, you can specify 'DELIM=<delim>KEY<delim>VALUE' instead, for example:

 'DELIM=;myURLKey;https://myurl.com'

In this case, the operator would output the parameter pair as follows:

myURLKey="https://myurl.com"

Note: If you plan to use a realm as part of an integration with an application that is hosted on a traditional WebSphere Application Server instance, you must provide a value for the provider_name parameter that matches the realm name for the application in that WebSphere Application Server instance.

To determine the realm name for your existing application, in the WebSphere Application Server admin console, go to Security > Global Security, and under User account repository, check the value for Realm name.

What to do next

To protect FileNet Content Manager configuration data, see topic Creating secrets to protect sensitive configuration data.