OAuth client authentication

Imply Cloud Auth with SSO support is an alpha feature for Imply Cloud. See About experimental features for more information about alpha features.

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

How it works

With Imply Cloud 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 Cloud Auth administrators can manage token revocation and token lifespans.

Configuring OAuth client access

To configure a custom OAuth client:

  1. As a user with the role administer-clients in the Imply Cloud 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 Cloud 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 SSO on your Imply cluster

Client applications can authenticate with OAuth tokens only if SSO access is enabled for the Imply cluster. 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 Cloud Auth.
  • {client_id} with the name of the client you configured.
  • {client_secret} with the generated secret for the client.
← Configuring LDAP for Imply SSOMonitoring →