Configuring OpenID Connect single sign-on in the custom application

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. This application uses the OpenID Connect provider with the discovery endpoint https://<tenant-host>/oidc/endpoint/default/.well-known/openid-configuration.

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. Context-based authorization 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.
   Kubernetes secret	The Kubernetes secret YAML file is used to connect with Red Hat OpenShift. You must download the Kubernetes secret YAML file to obtain the metadata.
   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. While wildcards are not supported in the URI path, the "*" character is a valid URI path character and is treated as a literal string. 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.
   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 to copy the client ID or secret to the clipboard.
   • Select to view the client secret.
   • Select to hide the client secret.
   • Select 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. The following attribute names cannot be used: aud, exp, groupIds, groupUids, at_hash, c_hash, rt_hash, s_hash, iat, iss, nonce, sub, client_id, grant_id, grant_type, and scope.
   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 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 2. 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: HS256 HS384 HS512 ES256 ES384 ES512 PS256 PS384 PS512 RS256 (default value) RS384 RS512 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. 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, 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 cipher text 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.

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. 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.The following attribute names cannot be used: aud, exp, groupIds, groupUids, at_hash, c_hash, rt_hash, s_hash, iat, iss, nonce, client_id, grant_id, grant_type, and scope. If the attribute name is sub, this attribute mapping modifies the value of sub in the introspection response, JWT access token, userinfo response, and ID token.
   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 enterprise 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 to select from the list of predefined access policies. When an access policy is selected, you can apply the access policy to API grant types by selecting the checkbox for each grant type. 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 sign-on token API entitlements.
    3. Select Save.
11. Select Save.