Generic OIDC provider type

If your OIDC identity provider type is not listed or you want more configuration flexibility, set the type to Generic when you configure your OpenID Connect namespace as your authentication provider. Additional information about the namespace is required.

You must perform two tasks:

Finding out information about the OIDC namespace

Before you configure Cognos Configuration, gather information from your identity provider (IDP) administrator. For interactive user authentication, Cognos Analytics supports the authorization code flow, as defined in OpenID Connect Core 1.0 specification (https://openid.net/specs/openid-connect-core-1_0.html).

To obtain the necessary information, ask your IDP administrator these questions:

Does the IDP support OpenID Connect Discovery?
For more information, see https://openid.net/specs/openid-connect-discovery-1_0.html
If the answer is yes, obtain the discovery URL.
If the answer is no, obtain values for these settings:
  • Issuer
  • Token Endpoint
  • Authorization Endpoint
  • JWKS Endpoint (optional)
Does the IDP support JSON Web Key Sets (JWKS)?

The URL may be returned in the Discovery document. If it is not returned or your IDP does not support discovery, then ask your administrator to provide the JWKS URL.

If JWKS is not supported, ask your administrator to provide the public key used to sign the id_token. The key must be provided in the form of a file that contains a single PEM-encoded X509 certificate.

How will the Cognos Analytics application authenticate to the IDP?
The options are to use a client secret or a JWT signed with a private key. If you are using a private key, it must be provided as encrypted PKCS#8 in a PEM format.

In both cases, obtain the Client ID.

Which user property claims can be mapped to Cognos Analytics?
Cognos Analytics maps user properties to claims in the OIDC id_token and optionally also the user_info endpoint. Your administrator can help determine which claims are available and if extra scope values are required for the required claims.
For more information, see Table 1: Mapping of OIDC claim names to Cognos Configuration properties.

In addition, you can configure custom properties. If a property is not mapped to a claim or if the claim is sometimes empty the value is displayed as empty.

First, identify which claim uniquely identifies a user. Next, map this claim to one of the user properties or a custom property. The value of this property must never change and must be unique across all users in the namespace.

The sub claim is convenient, and guaranteed unique by the OIDC specification. However, it may make it more difficult to pre-register users in Cognos Analytics before they logon. It may also make migration to a different IDP more complicated if the value is proprietary. The preferred_username attribute usually works well if supported by the IDP and does not change over time.

The rest of the user properties are optional. However, configuring at least the username is recommended so that it can be displayed in the audit logs.

Does the IDP support password grant/ROPC (Resource Owner Password Credentials)?
If the answer is yes, are any additional URL parameters required?
What offline authentication methods are supported by the IDP?
Cognos Analytics supports password grant, refresh_token, and a proprietary fallback of "id token". Some IDPs require additional scope values for refresh tokens.
What is the Return URL?

For security reasons, the OIDC protocol requires the application to pre-register its own URL with the IDP. The specification also requires that https protocol be used. At this time the URL must contain a port, and is usually 443 for https.

You must give your administrator the exact URL with the port.

Configuring OIDC values in Cognos Configuration

  1. Open IBM® Cognos® Configuration on your Content Manager computer.
  2. Under Security > Authentication, right-click and select New resource > Namespace.
  3. For Type (Group), select OpenID connect.
  4. For Type, select Generic.
  5. Type the namespace name in the Name field, and then click OK.

    The new namespace is added in the Explorer pane under Security > Authentication, and its properties are displayed in the properties pane.

  6. Specify values for the namespace properties.
    • The Namespace ID is used in the CAMID.
    If you are using a discovery URL:
    • Keep Use Discovery endpoint? set to True and configure Discovery Endpoint.
    • Keep the following Non-discovery endpoint configuration properties empty:
      • Issuer
      • Token Endpoint
      • Authorization Endpoint
    If you are not using a discovery URL:
    • Change the Use discovery endpoint? value to False.
    • Leave Discovery Endpoint empty.
    • Configure the Non-discovery endpoint configuration properties Issuer, Token endpoint, and Authorization Endpoint properties with the values that you obtained from the OIDC administrator.
    • In the Application configuration section, specify values for Client Identifier, and Return URL, as suggested by your OIDC administrator.
    • In the Identity provider authentication section:
      • For the Scope for authorize endpoint property, keep the value openid. Add any required additional scopes. Values are separated by spaces.
      • For the Account claims property, the default value is ID token.
        Tip: Some IDPs require an extra call to the Userinfo endpoint property to resolve all needed claims. This causes an extra HTTP GET request to be sent to the IDP logon time. If your IDP requires this, you can change this setting.
    • In the Token endpoint authentication section:
      • If you are using a client secret, enter its value. For the Strategy property, select Client secret post or Client secret basic, depending on what your IDP requires. Leave the private key parameters empty.
      • If you are using Private Key JWT authentication, select Private key JWT for the Strategy property and leave Client secret empty. Configure the path to the private key file and password. The file must contain a single, encrypted PKCS#8 key in a PEM format. If your IDP requires a kid parameter in the JWT header, enter it as the Private key identifier, otherwise leave it blank.
    • For the Token signature verification section:

      Usually, the JWKS URL is taken from the Discovery endpoint document and these sections defaults are appropriate.

      However, you can manually configure the URL or certificate file, if needed. The Location drop down allows you to select which one to use. If you are using a file, it must contain a single PEM encoded X509 certificate.

    • For the Password grant section:
      • If you are using password grant for offline authentication, the strategy lets you configure where the claims are gathered from.
      • ID Token: Only the ID token is considered.
      • ID Token and User info endpoint: both the ID token and the user info endpoint are used.
      • User info endpoint. For security reasons, the setting is now identical to ID Token and User info endpoint and is included for backward compatibility with previous versions.
      • Unsupported - Select this value if your IDP does not support password grant or if you do not wish Cognos Analytics to use it.
      • If your IDP requires that the scope not be sent, then you can configure this here. Same with additional URL parameters that may be required. Note that the parameters must start with & and the rest be URL-encoded. For example: '&resource=https%3A%2F%2Fca.ibm.com'.
    • For the Scheduling credentials section:

      This section is used to configure offline authentication or when interactive authentication is not possible. An example is a schedule that runs a report.

      For offline authentication to be possible, an encrypted blob is stored in Content Manager while the user is logged on interactively, for example, when the schedule is created. Then later a trusted service can use this blob to create a session to perform work on behalf of a user.

      The configured strategy controls what this encrypted blob contains:

      • ID Token: store only the id_token. Later the idtoken is used directly to establish the users identity. This is the most compatible setting but it prevents certain forms of Data Source authentication. Also the IDP is not contacted so the credentials will be valid until the user is disabled in Cognos Analytics.
      • Credentials: Cognos Analytics will prompt for a username and password. When needed, they are directly used to authenticate the user with the IDP using ROPC/password grant.
      • Credentials and ID Token: A combination of both. Password grant is used, and claims can come from either the old or new token. Use this if your IDP returns limited claims when using password grant.
      • Refresh token: The most secure setting. It is the default recommended setting if it is supported by your IDP. This setting usually requires the offline_access scope, but check with your administrator to see if additional scopes are required.
    • For the Account mappings (Advanced) section:

      For historical reasons, the Unique Identifier must be the internal name that corresponds to the property name in Cognos Configuration. For more information, see Table 1: Mapping of Cognos Configuration properties to internal names.

      The rest of the properties must be OIDC claims. If the configured unique identifier is not configured correctly, the following error message appears when you log on:

      Cannot create Account object. CAMID property value is null

      If none of the Cognos user properties are appropriate for use as the unique identifier, a custom property can be configured to map to any claim.

      Both the Cognos Analytics property names and the OIDC claim names are case-sensitive.

      The following table lists the property names displayed in Cognos Configuration and the corresponding internal names to use for the unique identifier.

      Table 1. Mapping of Cognos Configuration properties to internal names
      Property name in Cognos Configuration Internal name to use for the unique identifier
      Business phone businessPhone
      Content locale contentLocale
      Description description
      Email email
      Fax/Phone faxPhone
      Given name givenName
      Home phone homePhone
      Mobile phone mobilePhone
      Name name
      Pager phone pagerPhone
      Postal address postalAddress
      Product locale productLocale
      Surname surname
      User name username

      Member Of is used for simple group configuration. The comma -separated list of claims is looked up in the user claims individually. The resulting array of strings is used to create groups.

      Custom properties can be added. For example, use "subjectId: sub" to use the sub claim value as the value of the subjectId custom property. Custom properties are exposed in certain parts of the product and they can also be used for a user's Unique Identifier as mentioned above.

  7. If your IDP is not using a well known certificate, you must import the root certificate authority certificate into the Cognos Analytics keystore using the Third-Party Certificate Tool. Proceed as follows:

    • On UNIX or Linux® operating systems, type ThirdPartyCertificateTool.sh -i -T -r cert.cer -p NoPassWordSet
    • On Windows operating systems, type ThirdPartyCertificateTool.bat -i -T -r cert.cer -p NoPassWordSet
    Tip: Replace the cert variable with the name of the certificate file that is used by your OpenID Connect identity provider.

    The command imports the contents into the CAMKeystore file in the certs directory by using the specified password.

  8. Perform the same configuration steps on your backup Content Manager computer.
  9. Restart the IBM Cognos service on the Content Manager and the backup Content Manager computers.