auth command group

Note

This information applies to Databricks CLI versions 0.100 and higher, which are in Private Preview. To try them, reach out to your Databricks contact. To find your version of the Databricks CLI, run databricks -v.

The auth command group within the Databricks CLI enables you to:

  • List any available authentication configuration profiles.

  • Get information about an individual authentication configuration profile.

  • Use OAuth user-to-machine (U2M) authentication to authenticate the Databricks CLI with your Databricks accounts and workspaces.

  • Get information about any OAuth access tokens that the Databricks CLI might have cached.

Important

Before you use the Databricks CLI, be sure to set up the Databricks CLI and set up authentication for the Databricks CLI.

You run auth commands by appending them to databricks auth. To display help for the auth command, run databricks auth -h.

List configuration profiles

To get information about all of your available configuration profiles, run the auth profiles command, as follows:

databricks auth profiles

Output (the ellipses represent omitted content, for brevity):

{
  "profiles": [
    {
      "name": "<profile-name>",
      "host": "<workspace-url>",
      "cloud": "<cloud-id>",
      "auth_type": "<auth-type>",
      "valid": true
    },
    {
      "...": "..."
    }
  ]
}

The output of the auth profiles command does not display any access tokens. To display an access token, see Get information about a configuration profile.

Configuration profiles are stored in the file ~/.databrickscfg on Linux or macOS, or %USERPROFILE%\.databrickscfg on Windows by default. You can change the default path of this file by setting the environment variable DATABRICKS_CONFIG_FILE. To learn how to set environment variables, see your operating system’s documentation.

To create configuration profiles, see the configure command group.

Get information about a configuration profile

To get information about an existing configuration profile, run the auth env command, where <profile-name> represents the name of the profile, and <account-or-workspace-url> represents the Databricks account console URL or the Databricks workspace URL, as follows:

databricks auth env --profile <profile-name>

# Or:
databricks auth env --host <account-or-workspace-url>

For example, here is the output for a profile that is configured with Databricks access token authentication:

{
  "env": {
    "DATABRICKS_AUTH_TYPE": "pat",
    "DATABRICKS_CONFIG_PROFILE": "<profile-name>",
    "DATABRICKS_HOST": "<workspace-url>",
    "DATABRICKS_TOKEN": "<token-value>"
  }
}

Note

If more than one profile matches the --host value, an error displays, stating that it cannot find a single matching profile. For example, you might have one profile that has only a host value and another profile that has the same host value but also a token value. In this case, the Databricks CLI does not choose a profile and stops. To help the Databricks CLI choose the desired profile, try specifying a different --host value. For --host values that are account console URLs, try specifying an --account-id value instead of a --host value.

To create a configuration profile, see the configure command group.

Authenticate with OAuth

Instead of authenticating with Databricks by using access tokens and configuration profiles, you can use OAuth user-to-machine (U2M) authentication. OAuth provides tokens with faster expiration times than Databricks personal access tokens, and offers better server-side session invalidation and scoping. Because OAuth access tokens expire in less than an hour, this reduces the risk associated with accidentally checking tokens into source control. See OAuth user-to-machine (U2M) authentication.

To configure and set up OAuth U2M authentication, see OAuth user-to-machine (U2M) authentication.

Get OAuth access token details

If you want to see information about the cached OAuth access token that the Databricks CLI previously generated for a Databricks workspace, run the auth token command, where <workspace-url> represents the Databricks workspace’s URL, as follows:

databricks auth token <workspace-url>

Output:

{
  "access_token": "<token-value>",
  "token_type": "Bearer",
  "expiry": "<token-expiration-date-time>"
}