Skip to main content

Configure a federation policy

Databricks OAuth token federation enables you to securely access Databricks APIs using tokens from your identity provider (IdP). To enable OAuth token federation, you must configure a federation policy, either as Databricks account-wide or for workloads.

This article describes how to create and configure an OAuth token federation policy.

Workload identity federation​

Workload identity federation allows your automated workloads running outside of Databricks to access Databricks APIs without the need for Databricks secrets. Account admins can configure workload identity federation using a service principal federation policy.

A service principal federation policy is associated with a service principal in your Databricks account, and specifies:

  • The identity provider (or issuer) from which the service principal can authenticate.
  • The workload identity (or subject) that is permitted to authenticate as the Databricks service principal.

For example, given the following service principal federation policy for a Github Actions workload:

  • Issuer: https://token.actions.githubusercontent.com
  • Audiences: https://github.com/my-github-org
  • Subject: repo:my-github-org/my-repo:environment:prod

You can use this JWT body to authenticate to Databricks:

JSON
{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://github.com/my-github-org",
  "sub": "repo:my-github-org/my-repo:environment:prod"
}

Configure a service principal federation policy​

Account admins can configure a service principal federation policy using the Databricks CLI or the Databricks API. You can create a maximum of 20 service principal federation policies per Databricks service principal.

To configure a service principal federation policy, you must specify the following:

  • Issuer URL: An HTTPS URL that identifies the workload identity provider, specified in the iss claim of workload identity tokens.
  • Subject: The unique identifier for the workload in the workload runtime environment. The default is sub unless you
  • Audiences: The intended recipient of the token, specified in the aud claim. The token is considered a match if its audience matches at least one audience in the policy. If unspecified, the default is your Databricks account ID.
  • Subject claim: (Optional) Specifies the token claim that contains the workload identity (also called the subject) of the token. If not set, Databricks uses sub by default. Databricks recommends keeping the default sub claim for workload identity federation. Only choose a different claim if sub isn't a suitable or stable subject identifier, which is rare. For details, see Example service principal federation policies.
  • Token signature validation: (Optional) The public keys, or their URL, in JSON Web Key Sets (JWKS) format used to validate token signatures. If unspecified, Databricks automatically retrieves them from the issuer’s well-known endpoint, which is the recommended approach. If you don't specify public keys, your identity provider must serve OpenID Provider Metadata at <issuer-url>/.well-known/openid-configuration. The metadata must include a jwks_uri that specifies the location of the public keys used to verify token signatures.
  1. As an account admin, sign in to the Databricks account console at https://accounts.cloud.databricks.com.
  2. Click User management.
  3. Go to the Service principals tab.
  4. Select the service principal to create the policy for.
  5. Go to the Credentials & secrets tab.
  6. Under Federation policies tab, click Create policy.
  7. Select a federated credential provider and configure the corresponding fields.
  8. Click Create policy.

Example Databricks service principal federation policies​

The following table provides example service principal federation policies and the matching JWT body.

For complete configuration steps for enabling workload identity federation for some of these common identity providers, see Enable workload identity federation in CI/CD.

Tool

Federation policy

Example matching token

GitHub Actions

Issuer: https://token.actions.githubusercontent.com
Audience: https://github.com/<github-org>
Subject: repo:<github-org>/<repo>:environment:prod

{
"iss": "https://token.actions.githubusercontent.com",
"aud": "https://github.com/<github-org>",
"sub": "repo:<github-org>/<repo>:environment:prod"
}

Kubernetes

Issuer: https://kubernetes.default.svc
Audience: https://kubernetes.default.svc
Subject: system:serviceaccount:namespace:podname
JWKS JSON: {"keys":[{"kty":"rsa","e":"AQAB","use":"sig","kid":"<key-id>","alg":"RS256","n":"uPUViFv..."}]}

{
"iss": "https://kubernetes.default.svc",
"aud": ["https://kubernetes.default.svc"],
"sub": "system:serviceaccount:namespace:podname"
}

Azure DevOps

Issuer: https://vstoken.dev.azure.com/<org_id>
Audience: api://AzureADTokenExchange
Subject: sc://my-org/my-project/my-connection

{
"iss": "https://vstoken.dev.azure.com/<org_id>",
"aud": "api://AzureADTokenExchange",
"sub": "sc://my-org/my-project/my-connection"
}

GitLab

Issuer: https://gitlab.example.com
Audience: https://gitlab.example.com
Subject: project_path:my-group/my-project:...

{
"iss": "https://gitlab.example.com",
"aud": "https://gitlab.example.com",
"sub": "project_path:my-group/my-project:..."
}

CircleCI

Issuer: https://oidc.circleci.com/org/<org_id>
Audience: <org_id>
Subject: 7cc1d11b-46c8-4eb2-9482-4c56a910c7ce
Subject claim: oidc.circleci.com/project-id

{
"iss": "https://oidc.circleci.com/org/<org_id>",
"aud": "<org_id>",
"oidc.circleci.com/project-id": "7cc1d11b-46c8-4eb2-9482-4c56a910c7ce"
}

Account-wide token federation​

Account admins can configure OAuth token federation in the Databricks account using an account federation policy. An account federation policy enables all users and service principals in your Databricks account to access Databricks APIs using tokens from your identity provider. An account federation policy specifies:

  • The identity provider or issuer from which Databricks will accept tokens.
  • The criteria for mapping a token to the corresponding Databricks user or service principal.

For example, given a federation policy with the following fields:

  • Issuer: https://idp.mycompany.com/oidc
  • Audiences: databricks
  • Subject claim: sub

Use this JWT body to authenticate to Databricks as username@mycompany.com:

JSON
{
  "iss": "https://idp.mycompany.com/oidc",
  "aud": "databricks",
  "sub": "username@mycompany.com"
}

Configure an account federation policy​

Account admins can configure an account federation policy using the Databricks UI, the Databricks CLI or the Databricks REST API. You can specify a maximum of 20 account federation policies in your Databricks account.

To configure an account federation policy, you must specify the following:

  • Issuer URL: An HTTPS URL that identifies your identity provider, specified in the iss claim of your tokens.
  • Audiences: The intended recipient of the token, specified in the aud claim. The token is considered a match if its audience matches at least one audience in the policy. If unspecified, the default is your Databricks account ID.
  • Subject claim: The token claim that contains the Databricks username of the user that the token was issued for. If unspecified, the default is sub.
  • Token signature validation: (Optional) The public keys, or their URL, in JSON Web Key Sets (JWKS) format used to validate token signatures. If unspecified, Databricks automatically retrieves them from your issuer's well-known endpoint, which is the recommended approach. If you don't specify public keys, your identity provider must serve OpenID Provider Metadata at <issuer-url>/.well-known/openid-configuration. The metadata must include a jwks_uri that specifies the location of the public keys used to verify token signatures.
important

For account-wide federation, only register IdPs that are fully managed and trusted by your organization, such as your company’s own IdP. Don't configure account-wide federation with external IdPs that you don't control, such as those managed by customers or partners.

  1. As an account admin, sign in to the Databricks account console at https://accounts.cloud.databricks.com.
  2. Click Settings and go to the Authentication tab.
  3. Under Federation policies, click Create policy.
  4. Enter the issuer URL, audiences, subject claim, and optional token signature validation.
  5. Click Create policy.

Example account federation policies​

The following table provides example account federation policies and the matching JWT body.

Federation policy

Example matching token

Issuer: https://idp.mycompany.com/oidc
Audience: 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d

{
"iss": "https://idp.mycompany.com/oidc",
"aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d",
"sub": "username@mycompany.com"
}

Issuer: https://idp.mycompany.com/oidc
Audience: 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d
Subject claim: preferred_username

{
"iss": "https://idp.mycompany.com/oidc",
"aud": ["2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "other-audience"],
"preferred_username": "username@mycompany.com",
"sub": "some-other-ignored-value"
}

Issuer: https://idp.mycompany.com/oidc
Audience: 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d
JWKS JSON: {"keys":[{"kty":"RSA","e":"AQAB","use":"sig","kid":"<key-id>","alg":"RS256","n":"uPUViFv..."}]}

{
"iss": "https://idp.mycompany.com/oidc",
"aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d",
"sub": "username@mycompany.com"
}
(signature verified using public key in policy)

Issuer: https://idp.mycompany.com/oidc
Audience: 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d
JWKS URI: https://idp.mycompany.com/jwks.json

{
"iss": "https://idp.mycompany.com/oidc",
"aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d",
"sub": "username@mycompany.com"
}
(signature verified using public key fetched from jwks_uri)

Next steps​

After you configure a federation policy for your account:

  • Configure your identity provider (IdP) to generate tokens that your users can exchange with Databricks. Refer to your IdP’s documentation for setup details. For instructions to enable workload identity federation with common IdPs, see Enable workload identity federation in CI/CD.
  • Use a JWT from your IdP to access the Databricks API by first exchanging it for a Databricks OAuth token. Include the Databricks OAuth token in the Bearer: header of your API call to complete the request. The JWT must be valid and signed using the RS256 or ES256 algorithms. For implementation details, see Use an identity provider token to authenticate Databricks REST APIs.
Last updated on