Managing STS clients

Edit online

Use Security Token Service (STS) client to exchange tokens. Follow the specifications for OAuth token exchange when you create and manage your STS clients in IBM® Verify. You can validate your third-party apps with the OAuth as a protected resource.

Before you begin

Log in to the IBM Verify administration console as an Administrator.
Create the custom token types that are to be used by the STS client. See Managing custom token types.

Note: Only users with the proper entitlements can see the client secret. For more information, see Security updates for entitlements.

About this task

Configure an STS client for token exchange. A client requests a security token to the authorization server's token endpoint by using the token extension grant type mechanism. The external applications that are built by using Verify as an identity provider can accept the API REST requests that are authenticated with an OAuth 2.0 access token and different authentication methods. For more information, see https://www.rfc-editor.org/rfc/rfc8693.html.

Procedure

Select Applications > STS Clients.
Select Add STS client.
Provide the general information.
1. Optional: Provide a client ID.
  If you do not provide a client ID, an ID is created when you complete the setup.
2. Provide a unique name for the STS client.
3. Keep the Enabled checkbox selected.
  You can enable or disable this STS client.
4. Allow access tokens to be exchanged for SSO session. If Default is selected, the OIDC application general settings determine whether access tokens can be exchanged for SSO session.
Select Next.
Select the client authentication method.
The setting determines how the client is authenticated.
- For the Default, Client secret basic, and Client secret POST methods, the client secret is automatically generated when you complete the setup.
- For the Private key JWT method, you must select a client assertion signing algorithm and allowed signature verification keys. You can also select the Validate client assertion JTI to validate the client assertion.
- For the Mutual TLS method, you must provide the TLS client authentication attribute and the TLS client authentication attribute value.
- If you are editing an existing STS client, you can use the following client secret options:
  - Select to view the client secret.
  - Select to hide the client secret.
  - Select to copy the client ID or secret to the clipboard.
  - Select to view rotated client secrets.
    - Select one or more rotated client secrets from the list, and click Delete to delete them.
  - 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.
    - 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.
Note: The default client authentication method is default.
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.
Select Next.

Select the allowed token types for the subject token and the requested token.

Optional: Select the allowed token types for the actor token.

Table 1. 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.

To create a custom token type to use for the client, see Managing custom token types.

Select Next.

Select or specify the requested token settings.

Table 2. Requested token settings
Field	Description
Access token format	Specifies the format of the access token. The following options are available: Default JWT
Access token expiry(sec)	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 `3600` seconds. The minimum allowed value is `1` and the maximum is `2147483647` seconds.
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 RS384 RS512 PS256 PS384 PS512 ES256 ES384 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	Select the certificate that is used to sign the ID token. The default selection refers to the default that you configured in Security > Certificates. .
Encryption algorithm	The cryptographic algorithm that is used to encrypt or determine the value of the content encryption key (CEK). The following algorithms are supported. None RSA-OAEP RSA-OAEP-256
Content algorithm	The content encryption algorithm that is used to authenticated encryption on the plain text to produce the ciphertext and the authentication tag. The following algorithms are supported: None A128GCM A192GCM A256GCM
Encryption certificate	Enter a value or select from the list of signer certificates that you already uploaded to the tenant. Note: For instructions about uploading signer certificates, see Managing certificates.
JWKS URI	The URI where the token issuer or 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 URI if the JWKS size is too large. If the token issuer does not publish a JWKS URI, a public key can be added, in the form of an 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. For example, `https://{yourDomain}/.well-known/jwks.json`

Select Next .

Select the checkboxes for Proof-of-possession settings.

Table 3. Proof-of-Possession settings
Field	Description
Certificate-bound access tokens	Indicates whether the tokens generated are 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

Select Next.
Configure request and response mappings for each of the endpoints.
1. Configure the introspect mapping to add and modify attributes that are returned from the introspect endpoint.
  See OpenID Connect introspect, ID token, and user info mapping.
2. Configure the user information and ID token attribute mapping to add and modify attributes that are returned from the userinfo endpoint and in the ID token.
  See OpenID Connect introspect, ID token, and user info mapping.
Select Next.
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 unavailable, 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 check-box 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.
Select the user and nonuser permissions that you want to grant to the access token.
Restrict API access is the default setting. To grant entitlements for API access, perform the following steps. 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.
Select Complete setup.