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.

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.
      The Create API Client wizard opens.
    2. Select the checkboxes for the entitlements that you want to grant.
      The Select all checkbox grants all the entitlements to the API client.
    3. Select Next.
    4. 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
      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.

    5. 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.
    6. Select Next.
    7. 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

    8. Optional: Add properties and values to associate with the API client.
    9. Select Next.
    10. 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.
    11. Select Create API client.
      The Client ID and Client Secret and Kubernetes secret are generated.
  3. View the connection details.
    1. Select the API client whose API credentials you want to view.
    2. Click 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.
      The Kubernetes secret YAML file metadata is used to connect with Red Hat OpenShift.
  4. View the API client details.
    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 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.
  5. Edit the API client.
    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. Select the Edit icon.
      The Edit API Client dialog box is displayed.
    3. Edit the information.
      Use the following options:
      • Select the Copy to clipboard to copy the client ID or secret to the clipboard.
      • Select Show to view the client secret.
      • Select Hide to hide the client secret.
      • 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.
      You can change the following information:
      • API client name
      • Description
      • Entitlements
      • Scopes
      • IP filters
      • Additional properties
    4. Select Save.
  6. Delete the API client.
    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.

What to do next

Add the domains from which your API client can call the Verify APIs. See Managing domains.