Skip to main content

Authenticate with OAuth

To enable Imply Hybrid (formerly Imply Cloud) Auth for your organization, contact your Imply account representative.

With Imply Hybrid Auth enabled, you can create custom API clients to authenticate REST API requests to the Imply API using the OAuth 2.0 authorization framework.

Prerequisites​

To create and manage API clients, you must have one of the following roles:

  • administer-account: Administer the entire organization, including managing users, creating API clients, and setting password policies.
  • administer-clients: Create, manage, and delete API clients.

See User roles for more information.

Authentication flow​

To authenticate with OAuth:

  1. Enable the OAuth 2.0 feature flag.
  2. Create an API client to obtain OAuth 2.0 credentials.
  3. Obtain an access token. The access token is tied to the client and grants API access.
  4. Send the access token in the HTTP Authorization header using Bearer authentication: Authorization: Bearer TOKEN.

Enable the OAuth 2.0 feature flag​

To authenticate with OAuth, you must first enable the OAuth 2.0 feature flag for your Imply Hybrid account. It's disabled by default.

To enable the OAuth 2.0 feature flag:

  1. From the Imply Manager, click Manage for the cluster.
  2. Click Setup in the left sidebar.
  3. Scroll down and expand the Advanced config settings.
  4. Under Feature flags, click the edit icon to open the feature flags dialog.
  5. Select the OAuth 2.0 feature flag.
  6. Click OK. Manager Feature flags
  7. Restart the cluster to apply the changes. This interrupts service for a few minutes.

Create an API client​

You configure and manage API clients from the User management console, the same console you use to manage Imply Hybrid users.

To create a custom API client:

  1. Navigate to the User management console.
  2. Click API Clients in the left sidebar.
  3. Click Create API Client.
  4. Enter a client identifier in the API Client ID field.
  5. Click Save.
  6. Optionally configure the access token lifespan:
    • By default, API tokens expire after five minutes.
    • If you can't acquire new tokens at this cadence, modify the lifespan in the Access Token Lifespan field.
    • Tokens are automatically revoked when they reach the configured lifespan. Configure access token lifespan
  7. Go to the Client Permissions tab.
  8. Click Assign permissions and select the role you want to assign.
  9. Click Save.

To download the token, go to the Tokens tab and click Download Token. Alternatively, you can obtain the token through the API as shown in the following section.

Get the token by API​

After creating the API client, you can acquire access tokens programmatically:

curl --request POST 'https://id.imply.io/auth/realms/{organization_name}/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_secret={client_secret}' \
--data-urlencode 'grant_type=client_credentials'

Replace the following placeholders with your own values:

  • {organization_name}: Your organization name in Imply Hybrid Auth
  • {client_id}: The client ID you configured
  • {client_secret}: Your client secret (visible in the Credentials tab)

Modify an API client​

To modify an API client:

  1. Click API Clients in the left sidebar.
  2. Click the ellipsis next to the API client and select Edit.
  3. Modify the general settings, roles, or other properties as needed.

Regenerate the client secret​

Regenerating the secret invalidates the current secret. Applications using the old secret will stop working.

To regenerate the secret:

  1. Click API Clients in the left sidebar.
  2. Click the ellipsis next to the API client.
  3. Go to the Credentials tab.
  4. Click Regenerate.
  5. Confirm your selection.
  6. Update your applications with the new secret.

Delete an API client​

This action is irreversible.

After you delete the client:

  • You can't create new tokens.
  • Existing tokens expire in five minutes or at the configured time to live (TTL), whichever comes first.

If you have any long-lived tokens, contact Imply.

To delete an API client:

  1. Click API Clients in the left sidebar.
  2. Click the ellipsis next to the API client and select Delete.
  3. Confirm your selection when prompted.