Managing application API access

Edit online

If a developer builds an application that uses one or more of the Verify functions, the application must be entitled to call the appropriate Verify APIs. Register the in-house application as an application API client in API access to assign it a unique client ID and secret.

Before you begin

You must have administrative permission to complete this task.
Log in to the IBM® Verify administration console as an Administrator.

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

About this task

You can grant API access to your application when you create it or later by using the edit option. API clients can be created for the application and each API client can have a different set of API access entitlements.

You can also implement an IP filter so that token issuance and usage can be limited to or exclude certain IP address range.

For OIDC applications, API access entitlements for the SSO client can also be configured. Those tokens are limited to perform actions that the user who logs in to the application is entitled to perform in Verify.

Procedure

Select API access.

Create the Application API client.

Select Add API client.

Specify the following information for the API client:

Table 1. Application API client
Information	Descriptions
Name	Specify the name of the API client. Note: Only alphanumeric characters and the following special characters are allowed: - . _
Enabled	Indicates whether the API client is enabled or disabled. An enabled API client can call the APIs to which it is entitled to access. A disabled API client cannot call any APIs, including those APIs to which it is entitled to access. Note: It might take up to 1 minute before this setting takes effect. If the API client has an existing valid access token, it can continue to call the APIs. Access tokens have a limited validity period. The token expires in 2 hours. When the access token is expired, the API client cannot call the APIs anymore.
Client ID	Unique identifier of the API client. This information is automatically generated and displayed in the API Clients list after you save the API client.
Client Secret	Used with the client ID to verify the identity of the API client. It is a secret that must be known only to the application and to the authorization server. This information is automatically generated after you save the API client. View the API client details.
Client authentication method	Indicates the client authentication method for the API client: Verify supports the following client authentication methods: `Default` (Default selection) `Client secret basic` `Client secret POST` `Private key JWT` Mutual TLS Note: Mutual TLS is not available for custom applications
TLS client authentication attribute	This option is displayed only when the Mutual TLS client authentication method is selected. The certificate attribute that will be used for authentication. Subject DN SAN DNS SAN URI SAN IP SAN email address
TLS client authentication attribute value	This option is displayed only when the Mutual TLS client authentication method is selected. The value of the attribute in the certificate that will be used for authentication.
Certificate-bound access tokens Note: Certificate-bound access tokens are not available for custom applications	Indicates whether the tokens generated will be certificate-bound. For more information about certificate-bound access tokens, 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 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. Note: You can manually specify the signature verification key. More than one signature verification key can be specified.
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 URI 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.

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 2. 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.

Specify the following information if you want to implement an IP filter to make sure the API client ID and secret are distributed safely.

Table 3. IP filter settings
Field	Description
Enable IP filtering	Indicates whether the IP filter is enabled or disabled.
Allow list. Deny list	Indicates the type of filter, whether the list is an allow or deny list. Required if Enable IP filtering is enabled.
IP filters	List of IP filters. Required if Enable IP filtering is enabled. The IP filters are in the form of a single IP address, IP range, or IP subnet mask. Both IPv4 and IPv6 are supported. For example: `192.0.2.55, 192.0.2.55-192.0.2.61, 192.0.2.55/24, 2001:db8::1, 2001:db8::1-2001:db8::ff, 2001:db8:1234::/48`.

Specify the signature attributes for the ID token and JWT-format access tokens. 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.

Note:

The signature options are only available for custom applications.

Table 4. Signature options
Field	Description
Signature Algorithm	The algorithm that Verify uses to sign the ID token and JWT-format access tokens. 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 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 and JWT-format access tokens during single sign-on. The default selection refers to the default personal certificate that you configured in Configuration > Certificates > Personal Certificates.

Select the Restrict custom scopes checkbox.
If you select Restrict custom scopes, 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. 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. Select to grant more scopes.
Select the APIs that you want to grant access. See Access entitlements for more information.
If Select All is set to Off, select the APIs that you want to grant access to for the client. If Select All is set to ON, the client is granted access to all of the APIs. However, you can clear the check boxes of any APIs that you do not want the client to have access to.
Note:
- You can create an API client that has no initial permission to call any APIs. You can edit it later to grant the specific API access.
- Only the APIs that are relevant to your subscription plan are available for selection.
- For OIDC applications, a default client with a client name that is the same as the application name is in the list of API clients for that application. It cannot be deleted unless the application is deleted or switched to a different sign-on method.
Select Save.
The Client ID and Client Secret are generated and the application API client is created.
View the API client details.
- Scroll or use the search field to find the API client. Any clients that match your search entry are displayed.
- Select the API client whose information you want to view. The API Client Details is displayed.
- Hover over the API client and select the icon when it appears. The Edit API Client dialog box is displayed.
  Use the following options:
  - Select to copy the client ID or secret to the clipboard.
  - Select to view the client secret.
  - Select to hide the client secret.
Edit the API client.
1. Scroll to find the API client.
2. Hover over the API client and select the icon when it appears.
  The Edit API Client dialog box is displayed.
3. Edit the information.
  If you are editing an existing application, 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.
4. Select Save.
Delete the API client.
1. Scroll to find the API client.
2. Choose from one of the following options:
  - Select an API client. When the Details pane is displayed, select Delete.
  - To delete multiple API clients, select the check boxes next to the API clients, then select delete.
3. Select Delete.
4. Confirm that you want to delete the selected API clients. The API clients are permanently deleted when the application is saved.