Configuring single sign-on in the OpenID Connect for Open Banking applications

Use OpenID Connect for Open Banking to allow applications to verify the identity of its users based on the authentication that is performed by IBM® Security 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. This application uses the new OpenID Connect provider with the discovery endpoint https://<tenant-host>/oauth2/.well-known/openid-configuration.

Before you begin

  • 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 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

When adding an application, select the OpenID Connect for Open Banking application template to configure an application to act as an OpenID Connect relying party or as a 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. Provide Verify with basic information about the relying party.
    Table 1. Relying party information
    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.

    OpenID Connect for Open Banking supports the following grant types:
    • Authorization code
    • Implicit
    • Client credentials
    • Authorization code and implicit (hybrid flow)
    • Token exchange
    • JWT bearer
    • Device flow
    • Context-based authorization

    You must select at least one grant type. See Grant types for a quick comparison of the supported grant types and to determine which grant type to set for the application.

    Response types Response types inform the Authorization Server of the wanted authorization processing flow.
    Note: When you are editing an existing application that does not have response types that are configured, it defaults to all applicable response types for the grant types that were enabled.
    OpenID Connect supports the following response types:
    • none
    • code
    • token
    • id_token
    • code token
    • code id_token
    • token id_token
    • code token id_token

    If response type code or none is selected, response mode query is enabled. Otherwise, response mode query is cleared and disabled.

    Response modes Response mode indicates how the Authorization Server returns result parameters from the Authorization Endpoint.
    OpenID Connect for Open Banking supports the following response modes:
    • Query
    • Fragment
    • Form POST
    • Query JWT
    • Fragment JWT
    • Form POST JWT
    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 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.

    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.
    Note: When you select this option, the client secret field is hidden.
    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 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.

    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.

    You can add a maximum of 400 URIs.

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

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

    If left as default, both client secret basic and POST are allowed. If this client is a public client, Client secret basic and POST are not allowed. If the relying party supports it, use private key JWT or Mutual TLS as the configuration. For more information about Mutual TLS client authentication, see OpenID Connect mutual TLS client authentication and certificate-bound access token.

    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 private key JWT client authentication method is selected.

    Client assertion signing algorithm This option is displayed only when the private key JWT client authentication method is selected.
    TLS client authentication attribute The certificate attribute that is used for authentication. This option is displayed only when the Mutual TLS client authentication method is selected.
    • Subject DN
    • SAN DNS
    • SAN URI
    • SAN IP
    • SAN email address
    TLS client authentication attribute value The value of the attribute in the certificate that is used for authentication. This option is displayed only when the Mutual TLS 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.
    Require pushed authorization request (PAR) PAR allows clients to push the payload of an authorization request to the authorization server via a direct request and provides them with a request URI that is used as reference to the data in a subsequent call to the authorization endpoint.
    Allow access tokens to be exchanged for SSO session Exchanging access tokens for SSO session.
    • Allow: Access tokens can be exchanged for SSO session.
    • Allow and revoke token: Access tokens can be exchanged for SSO session, but the token is revoked.
    • Deny: Access tokens cannot be exchanged for SSO session.
    • Default: The OIDC application general settings determine if access tokens can be exchanged for SSO session.
    If you are editing an existing application, you can use the following client secret options:
    • Select Show to view the client secret.
    • Select Hide to hide the client secret.
    • Select Copy to copy the client ID or secret to the clipboard.
    • Select List to view rotated client secrets.
      • Select one or more rotated client secrets from the list, and click Delete to delete them.
    • Select Regenerate 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.
      • Select the checkbox for Retain current secret to add the current client secret to the list of rotated client secrets.
      • If the Retain current secret checkbox is selected, choose the client secret description and expiration time (in browser local time). If no expiration time is selected, the tenant's Rotated secret lifetime set in the Application settings will apply.
      • Rotated client secrets are hashed and cannot be retrieved in plain text anymore, but they can still be used until the selected expiration date.
      • After confirmation, the client secret is immediately rotated. The new client secret is shown on the screen.
  3. Configure the JWT settings.
    Table 2. JWT settings
    Field Description
    JWKS URI The URI where the relying party publishes its public keys in JSON Web Keys Set (JWKS) format. This URI is used for JWT signature verification or encryption. 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.
    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.

    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's 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 defaults to the identity source realm that the user identified by the sub belongs to. When the JWT bearer user identification option is set to User ID, this setting is not applicable.
  4. Configure the Request object settings.
    Table 3. Request object settings
    Field Description
    Request object parameters only Require all request parameters to be in the request object.
    Signing algorithm The algorithm that Verify expects the request object to be signed with.
    Choose from the following hashing algorithms to verify the signature:
    • RS256
    • RS384
    • RS512
    • PS256
    • PS384
    • PS512
    • ES256
    • ES384
    • ES512
    Require expiry claim Require the request object to contain the expiry 'exp' property.
    Validity (secs) The maximum amount of time (in seconds) that the request object can be valid for. This is calculated by taking the expiry 'exp' minus the not-before 'nbf' timestamps in the request object.
    Request URIs The URL of a resource that contains a request object. Only request URIs registered here will be allowed during authorization request.
  5. 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 4. 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 Specifies the format of the access token. The following options are available:
    • default
    • JWT
    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.
    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.

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

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

    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 needs to 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.

  6. Specify the ID token signature and encryption options. 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. The token can be encrypted so that only the relying party can decrypt it.
    Table 5. Signature and encryption 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:
    • RS256
    • PS256
    • ES256
    • RS384
    • PS384
    • ES384
    • RS512
    • PS512
    • ES512
    Note:
    • If ES256 signature algorithm is selected, the certificate must be ECDSA with P-256.
    • If ES384 signature algorithm is selected, the certificate must be ECDSA with P-384.
    • If ES512 signature algorithm is selected, the certificate must be ECDSA with P-521.
    Signing Certificate

    This option is displayed only if you selected any of the RS, ES, or PS 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.

    Encryption algorithm The cryptographic algorithm used to encrypt or determine the value of the content encryption key (CEK).
    The following algorithms are supported:
    • RSA-OAEP
    • RSA-OAEP-256
    Content algorithm The content encryption algorithm that is used to perform authenticated encryption on the plain text to produce the ciphertext and the authentication tag.
    The following algorithms are supported:
    • A128GCM
    • A192GCM
    • A256GCM
    Encryption key The certificate label or key ID of the key to use for encryption.
  7. Configure the Proof-of-possession settings. See Demonstrating Proof-of-Possession(DPoP) for more information.
    Table 6. Proof-of-Possession settings
    Field Description
    Certificate-bound access tokens Indicates whether the tokens generated is certificate-bound. For more information about certificate-bound access tokens, see OpenID Connect mutual TLS client authentication and certificate-bound access token.
    Enforce DPoP-bound access tokens Indicates whether DPoP header is required for token requests.
    Validate the JTI of the DPoP JWT Indicates whether the JTI in the DPoP JWT is validated for single-use.
    Signing algorithm for DPoP JWT

    The expected signing algorithm for the DPoP JWT.

    Choose from the following algorithms:

    • RS256

    • RS384

    • RS512

    • PS256

    • PS384

    • PS512

    • ES256

    • ES384

    • ES512

  8. Specify the JWT-secured Authorization Response Mode (JARM) configuration options. The relying party uses the signature to verify the integrity and authenticity of the tokens that are contained in the JWT response. The JWT can also be encrypted so that only the relying party can decrypt it.
    Table 7. JWT-secured Authorization Response Mode
    Field Description
    Signature Algorithm The algorithm that Verify uses to sign the JWT response. The algorithm must match the one that the relying party registered with Verify.
    Choose from the following hashing algorithms:
    • RS256
    • PS256
    • ES256
    • RS384
    • PS384
    • ES384
    • RS512
    • PS512
    • ES512
    Note:
    • If ES256 signature algorithm is selected, the certificate must be ECDSA with P-256.
    • If ES384 signature algorithm is selected, the certificate must be ECDSA with P-384.
    • If ES512 signature algorithm is selected, the certificate must be ECDSA with P-521.
    Signing Certificate This option is displayed only if you selected any of the RS, ES, or PS signature algorithms. Use this certificate to sign the JWT response during single sign-on.

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

    Encryption algorithm The cryptographic algorithm used to encrypt or determine the value of the content encryption key (CEK).
    The following algorithms are supported :
    • RSA-OAEP
    • RSA-OAPE-256
    Content algorithm The content encryption algorithm that is used to perform authenticated encryption on the plain text to produce the ciphertext and the authentication tag.
    The following algorithms are supported:
    • A128GCM
    • A192GCM
    • A256GCM
    Encryption key The certificate label or key ID of the key to use for encryption.
  9. Configure the Token Exchange settings.
    Table 8. Token Exchange
    Field Description
    Subject Token The token type of the subject token, which represents the identity of the party on behalf of whom the token is being requested.
    Actor Token The token type of the actor token, which represents the identity of the party to whom the access rights of the issued token are being delegated.
    Requested Token The type of tokens that can be requested to be generated as part of the token exchange.
    Client groups The list of OpenID Connect client groups. Tokens generated by this client can be used as the subject token for token exchange in the same group. If this list is empty, any client can use the tokens generated from this client as the subject token for token exchange.
    Require actor token Require actor token as part of the token exchange request. This action enforces the delegation scenario and disallows the impersonation scenario.
  10. Configure the device flow settings.
    Table 9. Device flow
    Field Description
    Generate QR code for device flow Indicates whether a QR code is generated together with the user code.
  11. Configure request and response mappings for each of the endpoints.
    1. Configure the request and response mapping for the authorize endpoint.
    2. Configure the response mapping for the token endpoint.
    3. Configure the introspect mapping to add and modify attributes returned from the introspect endpoint.
    4. Configure the user information and ID token attribute mapping to add and modify attributes returned from the userinfo endpoint and in the ID token.
  12. Select the identity providers and the policy that determine how users can access the application.
    1. Select the identity providers that can be used to sign in to this application.

      The default setting is to allow access from all the enterprise identity providers that are configured for the tenant. To limit the identity providers that can be used to sign in to the application, select Select specific supported identity providers. Select the checkboxes for the identity providers 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. Alternatively, you can clear the checkbox, and select the Edit to select from the list of predefined access policies. For more information, see Access policies. When an access policy is selected, choose to apply access policy to the API grant types by selecting the checkbox for each grant type.
  13. Select whether to ask for user consent.
    The request for user consent can be added to OpenID Connect applications. If the default, Ask for consent, remains selected, the user is prompted to explicitly consent to scopes and other transaction information. If Do not ask for consent is selected, no consent is collected but the authorization request is successful. If Ask for unapproved consents only is selected, the user is prompted to provide consent only for anything that was not consented to yet.
  14. 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.
  15. 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 sign-on token API entitlements.
    3. Select Save.
  16. Select Save.

What to do next