OAuth client authentication

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

With Imply Hybrid Auth, you can configure OAuth-based authentication for Imply API clients. You can manage permissions for Imply API clients, including scripts, third-party apps, or other automated clients, from within the User management console, the same interface you use to manage other Imply Hybrid users.

How it works

With Imply Hybrid Auth, you create custom OAuth clients. Applications acquire API tokens through these clients to access Imply APIs, to which role-based access controls apply.

Currently custom OAuth clients only support service user accounts. A service user account represents non-human users; it is intended for scenarios where an external application needs to access resources or perform actions on its own.

Imply Hybrid Auth administrators can manage token revocation and token lifespans.

Configuring OAuth client access

To configure a custom OAuth client, as a user with the administer-clients role, follow these steps:

  1. In the Imply Hybrid Auth console, click OAuth Clients from the navigation tree.

  2. Click Create.

  3. Enter an identifier for the client in the OAuth Client ID field. Applications will need to reference this value in their client requests. The console automatically generates a secret used to acquire the token. The Settings tab for the OAuth client appears.

  4. By default, API tokens expire after five minutes. Applications should acquire tokens as needed, given this token lifespan and frequency of requests. If acquiring new tokens at this cadence is not possible for a given application, you can modify the lifespan of the token in the Access Token Lifespan field. Tokens are automatically revoked when their lifespan reaches the configured amount of time.

    OAuth config

  5. In Service Account Roles, assign the organization and client roles that may use this token by role. For the OAuth Client Roles, choose the entity that contains the roles you would like to assign.

  6. You can download the token from the client either by clicking the Tokens tab and then Download Token, or programmatically by following Get the token by API.

Revoking tokens

If you have set an extended life span for tokens and need to revoke them, you can do so using the following token revocation steps:

  1. In the Imply Hybrid Auth console, click on the OAuth client for which you would like to revoke access.
  2. Go to the Revocation tab.
  3. In the Not before field, click Set to now or enter the date in the following format: Mon Jul 19 2021 16:22:05 GMT-0700 (Pacific Daylight Time).

Removing OAuth clients

You can remove an OAuth client at any time from the OAuth Clients page as follows. New tokens will not be available for the client, but long-lived existing tokens need to be revoked before removing the client, as described in the previous section.

  1. Click OAuth Clients from the navigation menu.
  2. Find the ID of the client you want to remove.
  3. Click Delete next to the name of the client.
  4. Confirm when prompted.

Modifying OAuth client access

To modify an existing OAuth client, for example, by changing its secret, click Edit next to the client ID in the OAuth Clients page.

Modify the general settings, roles, or other properties as needed. To change the secret, under the Credentials tab click Regenerate Secret.

Enabling Cloud Auth on your Imply cluster

Client applications can authenticate with OAuth tokens only if Cloud Auth is enabled for their Imply Hybrid account. It is disabled by default.

To enable it in an existing cluster, follow these steps:

  1. From the Imply Manager, click the Manage button for the cluster.
  2. Click Setup from the left menu.
  3. Scroll down and expand the Advanced config settings.
  4. Under Feature flags, click the edit icon to open the feature flags dialog, which appears as follows: Manager Feature flags
  5. Find and enable the SSO feature flag and click OK.
  6. Restart the cluster to have the change take effect.

For a new cluster, in the New cluster page, expand the Advanced config settings and click the edit icon next to Feature flags. Find and enable the SSO feature flag.

Getting the token by API

You can download tokens from the UI manually, but more realistically, applications and scripts will acquire tokens programmatically. The following shows an example using curl to acquire a token:

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:

  • {organization_name} with the name of your organization in Imply Hybrid Auth.
  • {client_id} with the name of the client you configured.
  • {client_secret} with the generated secret for the client.
Last updated on 4/20/2022
← LDAP integrationMonitoring →