In this guide you will learn how to create an API Client definition in the IBM Security Verify Admin UI.
A privileged API client is required when an application needs to access APIs protected by OAuth without the delegated authority of an end user. A privileged API client uses the OAuth client credentials grant flow to obtain an Access Token.
IBM Security Verify's own APIs are protected with OAuth and so creating an API Client is the way that an application is granted authority to call privileged IBM Security Verify functions. The specific permissions granted to an API client are set as part of the client definition.
There are no pre-requisites for creating a stand-alone API Client. If you want to create an API Client that is associated with a custom application then that application definition must already exist.
A privileged API client can be defined as a stand-alone client or it can be defined within a custom application definition.
If the API client is required for an application that has no need for an application definition (because it only requires privileged API access), then it should be set up as a stand-alone client.
If the API client is required for a custom application which also needs an application definition (to support single sign-on or other OAuth flows), it makes sense to define the API client within that application definition).
In the Admin UI, navigate to the Security > API Access page and select the Add API client button.
In the Admin UI, navigate to the Applications > Applications page and edit the custom application that needs the privileged API client. In the application definition, select the API access tab and select Add API client button.
This is where you grant the permissions needed by the application using this API client.
Common permissions for a custom authentication application include:
- Authenticate any user
- Read users and groups
- Read second-factor authentication enrollment for all users
Common permissions for a custom registration application include:
- Authenticate any user
- Manage users and standard groups
- Manage second-factor authentication enrollment for all users
Read vs Manage permissions
Many permissions have read and manage variants. In most cases, clients that are granted the manage permission are also able to perform read actions without being specifically granted that permission.
By default, an API client can request any scope. If you want to restrict the scopes that the client can request, select the Allow configured scopes only checkbox and add the scopes you want to allow.
Scopes are only relevant to a privileged API client if it will be used to call custom APIs. Scopes are not used for granting authority to IBM Security Verify APIs.
By default, an API client can request an access token from any IP address. If you want to limit the IP addresses that are valid for this API client, select the Enable IP filtering checkbox and enter the required IP address filter.
You can assign custom attributes to an API client. These can be used to store properties related to the API client. These values are not used by IBM Security Verify but can be accessed via API to lookup information about the API client.
The name and description of the API client are human-readable and used for administration and reporting only.
The client credentials (client id and client secret) are generated when the API client definition is saved for the first time.
After saving the client definition, select the three dots on the client tile and select Connection details from the action menu. The client id and client secret values are shown on the connection details page. You can use the copy button by each item to add it to your paste-buffer.
Updated 6 months ago