Configuring single sign-on in the OpenID Connect provider

Use OpenID Connect for single sign-on to allow applications to verify the identity of its users based on the authentication that is performed by Verify. Users do not need to sign up for an account with the application. The users are redirected to Verify for login. Verify verifies the users' identities, sends the information through an ID token, and confirms with the relying party that the users are authorized to access and use the resource.

Before you begin

Note: An alternative to this task is available at OpenID Connect Dynamic Client Registration.
  • You must have administrative permission to complete this task.
  • Open at least two browser windows to complete the setup. One for the Verify administration console and the other for the administration console of the target application.
    • Log in to the IBM® Security Verify administration console.
    • Log in to the target application administration console with your Administrator account.
  • You must set up the basic information for the application instance in the General tab. See Setting the basic application details.

About this task

Verify predefined application templates do not have the OpenID Connect sign-on option. Use the Custom Application template to configure an application to act as an OpenID Connect relying party or client application that delegates users authentication to Verify.

Configure Verify and the relying party to talk to each other. To enable OpenID Connect single sign-on, you must provide:
  • Verify with certain data from the relying party.
  • The relying party with certain data from Verify.

You can configure IBM Security Verify Access and mobile applications as OpenID Connect relying parties.

Procedure

  1. Navigate to the Sign-on tab.
  2. In the Sign-on Method, select OpenID Connect 1.0.
  3. Provide Verify with basic information about the relying party.
    Field Description
    Application URL

    It is the single sign-on initialization URL that is used to log in to the OpenID Connect relying party.

    The application uses this URL to request Verify for the ID token that contains the user details.

    When users access the application through this URL, they are redirected to Verify for authentication.

    You can get this information from the relying party when you configure an authorization provider or OpenID Connect provider at its site.

    Grant Types

    It indicates the mechanism that the relying party can use to retrieve the ID token from Verify.

    Verify supports the following grant types:
    • Authorization Code
      Note: Authorization code is preselected as the default grant type with PKCE also selected by default.
    • Implicit
    • Device Flow
      Note: If you select Device Flow, you can also generate a QR code.
    • Policy driven authentication policyauth
    • JWT bearer
      Note: If you select JWT bearer, you have option to configure JWKS URI, JWT bearer user identification and JWT bearer default identity source. For more information about how to use the JWT bearer grant type, see Grant types.
    • Any combination of authorization code, implicit, device flow and ROPC.

    You must select at least one grant type. If ROPC is the only grant type that is selected, the Access Policies section is not displayed. See Grant types for a quick comparison of the supported grant types and to determine which grant type to set for the application.

    Client ID

    It is the unique public identifier that is assigned to the client application, which is the OpenID Connect relying party. The authorization server uses this information to identify the relying party and the authorization request.

    This information is automatically generated after you save the custom OpenID Connect application. You must provide this information to the relying party when you configure Verify as an OpenID Connect provider in the administration console of the application.

    The relying party uses the client ID every time it requests for an access token.

    Public client (no client secret)

    Indicates that the client has no secret that needs to be provided by the application.

    Note: When selected, the Client Secret field is hidden and the following algorithms are removed from the Signature Algorithm options:
    • HS256
    • HS384
    • HS512

    Generate a client secret only if the client type is confidential. Confidential clients can keep the client ID and secret in a secure way and does not show these credentials to unauthorized parties.

    A client secret must be known only to the client application and to the authorization server.

    Client Secret

    This data is used together with the client ID to authenticate the relying party and to exchange an authorization code for an ID token.

    This information is automatically generated after you save the custom OpenID Connect application. You must provide this information to the relying party when you configure Verify as an OpenID Connect provider in the administration console of the application.

    Client authentication method

    Indicates the authentication method for endpoints such as the token endpoint that require client authentication.

    Verify supports the following client authentication methods:
    • Default
    • Client secret basic
    • Client secret POST
    • Client secret JWT
    • Private key JWT

    If left as default, both client secret basic and POST are allowed. If the relying party supports it, use private key JWT as the configuration.

    Validate client assertion JTI

    Indicates whether the JTI in the client assertion JWT is validated for single-use. This option is displayed only when the client secret JWT or the private key JWT client authentication method is selected.

    Allowed signature verification keys

    The signature verification key IDs that can be used to verify the client assertion JWT. This option is displayed only when the private key JWT client authentication method is selected.

    Require proof key for code exchange (PKCE) verification PKCE is used to mitigate authorization code interception attacks. It requires a code challenge before the authorization code flow can proceed. This option is displayed only when the authorization code grant flow is selected.
    Redirect URIs

    It is the callback URL; the address where Verify sends its authentication response to the relying party.

    Users are redirected to this URL after they are authenticated and authorized by Verify.

    You must specify at least one URI. If the callback URI is the application's domain, it can be the domain of the tenant.
    Note: The domain can have a wildcard value.

    You can add a maximum of 10 URIs.

    You can get this information from the relying party when you configure an authorization provider or OpenID Connect provider at its site.
    JWKS URI The URI where the relying party publishes its public keys in JSON Web Keys (JWKs) format. This URI is used for JWT signature verification. The system can reject an unreachable or unresponsive JWKS URI. The system can also reject the JWKS URL if the JWKS size is too large. If the relying party does not publish a JWKS URI, a public key can be added, in the form of a X509 certificate, into the system. See Managing certificates. The `Friendly Name` that is associated with the public certificate is the value of the key ID (kid) header of JWT.
    JWT bearer user identification

    Available for JWT bearer grant type only.

    This configuration tells the system how the JWT bearer subject (sub) is interpreted to identify the User that is associated with this JWT bearer token. The sub can be the User ID, the Username, or the External ID.
    JWT bearer default identity source

    Available for JWT bearer grant type only.

    If the JWT does not specify the realm, it is the default identity source realm that the user that is identified by the sub belongs to. When the JWT bearer user identification option is set to User ID, this setting is not applicable.
    If you are editing an existing application, you can use the following client secret options:
    • Select Copy to clipboard to copy the client ID or secret to the clipboard.
    • Select Show to view the client secret.
    • Select Hide to hide the client secret.
    • Select Revert to generate a new client secret. Use this option if you think that the client secret is compromised. If you do regenerate the client secret, you must update the client secret in all the OAuth clients for the application.
  4. Configure the access token and refresh token expiry to limit the time of unauthorized access when these tokens are stolen.

    Access token is used to authorize access to the protected resource. After the access token expires, the authorization is revoked.

    Table 1. Token settings
    Field Description
    Access Token Expiry (secs)

    It sets the length of time in seconds after which, the access token is expired.

    Set an access token expiry to limit the time that an attacker can access the resource with the stolen token when the client application is compromised.

    Only positive integers are allowed.

    The default value is 7200 seconds. The minimum allowed value is 1 and the maximum is 2147483647 seconds.

    Access Token Format Indicates whether the access token is produced as an opaque string, which is the Default setting, or in JWT format.
    Audiences Specifies the targets that are the recipients of the token. These values are listed in the aud claim for JWT-formatted tokens and in the introspection payload as either a single string or an array of strings.
    Introspection attribute mapping This attribute-mapping list is used to include claims in the introspection payload and the JWT-format access token.
    Attribute Name Name of the attribute that the relying party uses and requires from Verify.
    Attributes

    Lists all of the attribute sources that you defined for each type in Directory > Attributes.

    The value of your selected attribute source is assigned as the attribute value for the defined relying party attribute name in the ID token.

    Generate refresh token

    Indicates whether the client application can request and use a refresh token to obtain a new access token from the authorization server of the OpenID Connect identity provider.

    Use this option only if the application intends to use the access token to perform operations by using Verify APIs.

    It is only necessary to obtain a new access token if the previous one expired.

    This option is not relevant if you selected "Implicit" as the Grant Type.

    Refresh Token Expiry (secs)

    It sets the length of time in seconds after which, the refresh token is expired. This setting determines how often the user can reauthenticate.

    Set the refresh token expiry to ensure that the user reattempts the full single sign-on operation against Verify after some time elapsed.

    This option is displayed only if you enabled Generate Refresh Token.

    A refresh token is used to get a new access token to continue access to the protected resource.

    Only positive integers are allowed.

    The default value is 604800 seconds. The minimum allowed value is 1 and the maximum is 2147483647 seconds.

    Renew refresh token lifetime This option indicates whether the refresh token lifetime is renewed when a refresh token is used to get a new set of tokens. When this checkbox is selected, the lifetime set by Refresh Token Expiry is renewed every time that the refresh tokens are refreshed. If it is not selected, the renewed refresh token expires when the original Refresh Token Expiry is reached.
  5. Specify the ID token signature attributes. The relying party uses the signature to verify the integrity and authenticity of the user claims that are contained in the token and the OpenID Connect identity provider that signed the token.
    Table 2. Signature options
    Field Description
    Signature Algorithm

    The algorithm that Verify uses to sign the ID token. The algorithm must match the one that the relying party registered with Verify.

    Choose from the following hashing algorithms to verify the signature:
    • HS256
    • HS384
    • HS512
    • PS256
    • PS384
    • PS512
    • RS256 (default value)
    • RS384
    • RS512
    Note: The HS algorithms are not displayed when you chose not to generate a client secret.
    Signing Certificate

    This option is displayed only if you selected any of the RS signature algorithms.

    Use this certificate to sign the ID token during single sign-on.

    The default selection refers to the default personal certificate that you configured in Security > Certificates > Personal Certificates.

  6. Map the user attributes that Verify supports and provides to the relying party through the ID token.
    Verify might extend the standard JSON claims schema to include additional attributes such as employee role, manager, and department.
    Note: The following attributes are already added to the ID token by default: userType, uniqueSecurityName, displayName, realmName, name, preferred_username, jti, at_hash, ext. Some of these attributes can be removed from the ID token by mapping them to an attribute source that is configured to return no value.
    The Attribute Mappings section consists of the following elements, which are described in Table 3.
    • A checkbox option to send all known user attributes.
    • Option to add attribute names, and their corresponding attribute source in Verify.
    Table 3. Attribute mappings
    Information Descriptions
    Send all known user attributes in the ID token

    When selected, all known user credential attributes that are available from the OpenID Connect provider identity source are automatically included in the ID token.

    Known user credential attributes consists of:
    Standard attributes
    These attributes are from the Verify Cloud Directory, which includes the built-in attributes that are displayed in Directory > Attributes.
    Extended attributes
    These attributes are from the SAML Enterprise identity provider that you configured in Authentication > Identity providers.
    Custom attributes
    These attributes are the attributes that you manually defined in Directory > Attributes, Add Attribute Source dialog.

    Otherwise, define only the specific attributes that the relying party requires in the ID token. Specify the attribute name and attribute source.

    Attribute Name Name of the attribute that the relying party uses and requires from Verify.
    Attributes

    Lists all of the attribute sources that you defined for each type in Directory > Attributes.

    The value of your selected attribute source is assigned as the attribute value for the defined relying party attribute name in the ID token.

    Note: If Untagged attribute is shown for the attribute source value, it is because the purpose of the attribute was changed. Existing applications that consume the attribute can continue to use the application until you remap the application to use a different attribute for that purpose. For example, if the Single sign-on (SSO) checkbox is cleared on an existing attribute, applications that already consume that attribute for SSO can continue to use it for SSO. The same behavior applies to the provisioning attribute mappings when the Provisioning purpose is removed.
  7. Select the identity sources and the policy that determine how users can access the application.
    1. Select the identity sources that can be used to sign in to this application.
      The default setting is to allow access from all the identity sources that are configured for the tenant. To limit the identity sources that can be used to sign in to the application, select Select specific supported identity sources. Select the checkboxes for the identity sources from which you want to allow sign-in.
    2. Select the policy that determines how users can access the application.
      You can continue to use the default access policy that is assigned, which is Allow access from all devices. Alternatively, you can clear the checkbox, and select the Edit to select from the list of predefined access policies. If multiple grant types, including ROPC, are selected, the policy applies to all the grant types except ROPC. Access policy is not enforced for ROPC flows. If ROPC is the only grant type that is selected, the Access Policies section is not displayed. For more information, see Access policies.
  8. Select whether to ask for user consent.
    The request for user consent can be added to Open ID Connect applications. It is available for all grant types except for Resource Owner Password Credentials (ROPC). If ROPC is the only grant type that is selected for the application, the User Consent option is hidden. If the default, Ask for consent, remains selected, the user is prompted to explicitly consent to scopes and API access entitlements. The user can grant or deny permission for API access. Existing Open ID Connect applications do not request consent. You must edit those applications if you want to ask for user consent. See Managing application consents.

    After the application is created, the field Consent type with the value of Advanced is displayed under Ask for consent. The Advanced value indicates that the user consents are stored in DPCM. Older OIDC custom applications display this field after migrating their consents to DPCM. See Migrating user consents.

  9. Optional: Restrict custom scopes.
    Custom scopes can be requested by an OIDC/OAuth client in the supported OIDC/OAuth grant flows. If Restrict Custom Scopes is enabled, which is the default setting, the scopes that are granted to the client at the end of the flow are restricted to those scopes that are specified in this section. If Restrict Custom Scopes is disabled, any custom scopes requested are granted when the flow completes.
    Note: The standard scopes openid, profile, email, phone, and address can't be restricted.
    1. Ensure that the Restrict Custom Scopes checkbox is selected.
    2. Type the name of the custom scope that you want to grant and a description.
      The scope name refers to the OAuth2/OIDC scope that is requested by a relying party/client. The description is a friendly explanation for the scope.
      Another set of scope fields is displayed.
    3. Repeat the previous step for each custom scope that you want to grant.
  10. Optional: Grant API entitlements to the sign-on token.
    Restrict API access is the default setting for new applications. The application has no sign-on token entitlements. To grant entitlements for API access perform the following steps.
    1. Select the edit icon.
      The Edit API client wizard starts.
    2. Select the user and non-user permissions that you want to grant to the sign-on token.
      If you clear the Restrict API access checkbox, a set of default entitlements is granted to the token. See Default API client sign-on token entitlements.
    3. Select Save.
  11. Select Save.

What to do next

  • Provide the relying party with information about Verify that is necessary to complete the OpenID Connect sign-on configuration between Verify and the relying party. See the instructions that are provided in the user interface.
  • Add user or group entitlements to permit access to the configured applications. See Managing application entitlements (by administrator or application owner).
  • Enforce two-factor authentication for added security control on users when they sign on to the configured applications. See Configuring authentication factors.