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 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® Security Verify
administration console as an Administrator.
About this task
Every API client that you add in API access, is assigned with a client
ID and client secret that you must provide to the application developer. The developer must store
these credentials securely.
All exposed runtime interfaces of the Verify authentication services
are protected by OAuth access tokens. The calling applications must supply an OAuth client ID and
secret at run time to exchange for an OAuth access token at the authorization service within your
tenant. The access token is then used to call the target Verify API. The token must be
provided on every API call.
You can also implement an IP filter so that token issuance and usage can be
limited to or exclude certain IP address range.
See the API documentation at https://docs.verify.ibm.com/verify/page/api-documentation to learn more
about the API operations, responses, and constraints.
You can perform the following tasks:
Procedure
-
Select
-
Add an API client.
-
Select Add API Client.
-
Select the checkboxes for the entitlements that you want to grant.
The Permission name checkbox grants all the entitlements to the API
client.
-
Select Next.
- Set restrictions.
Note: Restrict API client management to specific user populations is a requestable feature,
CI-102537. To request this feature, contact your IBM Sales representative or IBM contact and
indicate your interest in enabling this capability. If you have permission to create a support
ticket, create it with the public preview numbers. IBM Security Verify trial subscriptions cannot
create support tickets.
This step is available if you selected any of the entitlements with a
restrictable type.
manageGroupMembers
manageGroups
manageUsers
manageUserGroups
readGroups
readGroupMembers
readUserGroups
readUserGroupMembership
readUsers
resetPasswordAnyUser
Select the checkbox to restrict these entitlements to select groups.
Note: Group restrictions
can not be used if any of the following entitlements are selected.
manageAllUserGroups
manageStandardGroupMembers
manageUsersInStandardGroups
manageStandardGroups
manageUsersStandardGroups
readStandardGroupMembers
readStandardGroupMembership
readStandardGroups
updateAnyUser
-
Select Next.
- In the API credentials section, specify the
following information to enable the application to connect to the tenant through the API:
Table 1. API credentials
settings
Field |
Description |
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.
|
Client authentication method |
Verify supports the
following client authentication methods:
- Default (Default selection)
- Client secret basic
- Client secret POST
- Private key JWT
|
For Private key JWT authentication, these fields are available. |
|
Validate client assertion JTI |
This option is displayed only when the private key JWT client authentication method is
selected. Indicates whether the JTI in the client assertion JWT is validated for single-use.
|
Allowed signature verification keys |
This option is displayed only when the private key JWT client authentication method is
selected. The signature verification key IDs that can be used to verify the client assertion JWT.
|
JWKS URI |
This option is displayed only when the private key JWT client authentication method is
selected. 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 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.
|
- Select Next.
- Optional:
Select the checkbox to allow configured scopes only.
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 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. Select to grant more scopes.
-
Select Next.
- Optional:
In the IP filter section, 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 2. IP filter settings
Field |
Description |
Enable IP filtering |
Indicates whether the IP filter is enabled or disabled.
|
|
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
|
-
Select Next.
- Optional:
Add properties and values to associate with the API client.
-
Select Next.
-
Specify the following information for the API client to complete the configuration.
- Name
-
Note: Only alphanumeric characters and the following special characters are allowed:
- Description
- An explanation to easily identify the purpose of the API client.
- Enabled
-
Indicates whether the API client is enabled or disabled. The default setting is enabled.
An
enabled API client can call the APIs to which it is entitled to access.
A If the checkbox is cleared, 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.
-
Select Create API client.
The Client ID and Client Secret
and Kubernetes secret are generated.
What to do next
Add the domains from which your API client can call the Verify APIs. See Managing domains.