Managing API clients

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.
Note: Only users with the proper entitlements can see the client secret. For more information, see Security updates for entitlements.

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.

Procedure

  1. Select Security > API access > API clients
  2. Add an API client.
    1. Select Add API Client.
    2. Select the checkboxes for the entitlements that you want to grant.
      The Permission name checkbox grants all the entitlements to the API client.
    3. Select Next.
    4. 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
    5. Select Next.
    6. 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.

    7. Select Next.
    8. 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.
    9. Select Next.
    10. 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.

      • 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

    11. Select Next.
    12. Optional: Add properties and values to associate with the API client.
    13. Select Next.
    14. 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.
    15. 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.

Viewing connection details

Procedure

  1. Select the API client whose API credentials you want to view.
  2. Select the Menu icon.
  3. Select Connection details.
  4. Depending on your connection requirements, copy the Client ID and secret and download the Kubernetes secret YAML file.

Viewing the API client details

Procedure

  1. Scroll or use the search field to find the API client. Any clients that match your search entry are displayed.
  2. Select the API client name whose information you want to view. Select the API client name whose information you want to view.
    The API Client Details pop out is displayed. It lists the API client's status, Client ID , scopes, entitlements, and IP filters.
  3. Select the X to close the pop out.

Editing the API client

Procedure

  1. Scroll or use the search field to find the API client.
  2. Select the Menu icon.
  3. Select Edit.
    The Configuration tab is displayed.
  4. Edit the information.
    You can change the client name and description.
    For API credentials, use the following options:
    • Select Show to view the client secret.
    • Select Hide to hide the client secret.
    • Select Copy to copy the client ID or secret to the clipboard.
    • Select List to view rotated client secrets.
      • Select one or more rotated client secrets from the list, and click Delete to delete them.
    • Select Regenerate 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.
    You can also change the following information:
    • Scopes
    • IP filters
    • Additional properties
  5. Select Save.
  6. Select the Entitlements tab.
  7. Select Manage entitlements.
    Select or clear the checkboxes for the entitlements that you want to add or remove.
  8. If you have custom restrictions, click Next to add or remove groups that have the restricted entitlements.
  9. Click Save.

Deleting the API client

Procedure

  1. Scroll or use the search field to find the API client. Any clients that match your search entry are displayed.
    Any clients that match your search entry are displayed.
  2. On the API client that you want to delete, select the Menu icon.
  3. Select Delete.
  4. Confirm that you want to permanently delete the selected API client.