Use tokens de um provedor de identidade para autenticar Databricks REST APIs

Esta página explica como fazer a autenticação em Databricks REST APIs usando tokens emitidos pelo provedor de identidade de sua organização.

Databricks suporta a troca de tokensOAuth 2.0 para permitir que o senhor troque tokens de identidade federada por tokens Databricks OAuth . Com a federação de tokens, o Databricks CLI, os SDKs e outras ferramentas podem lidar automaticamente com essa troca e gerenciar o access tokens para o senhor.

O tempo de vida de cada access token é derivado do tempo de vida dos tokens federados que o senhor fornece, que geralmente é de uma hora, mas pode variar. As ferramentas refresh tokens automaticamente, conforme necessário, para que o senhor não precise solicitar ou alternar manualmente as credenciais.

Processo de autenticação

Para autenticar o acesso a Databricks API com tokens de um provedor de identidade federado, primeiro defina a variável de ambiente ou os campos de configuração necessários. Sua ferramenta preferida ou SDK recupera os tokens da Web (JWT) federados JSON do local que o senhor especificar, troca-os por tokens Databricks OAuth e usa os tokens OAuth para autenticar chamadas Databricks REST API .

Pré-requisitos

Antes de começar, execute os seguintes passos:

1. Crie uma política de federação para seu account ou entidade de serviço.
2. Obtenha um JWT válido do seu provedor de identidade que corresponda à política. Os tokens devem ser assinados usando RS256 ou ES256. Os passos variam de acordo com o provedor, portanto, consulte a documentação do seu provedor ou pergunte a um administrador.

Configure seu ambiente

Configure seu ambiente com base na origem de seus tokens federados.

Em todos os casos, o senhor deve definir as seguintes variáveis de ambiente, campos .databrickscfg, campos Terraform ou campos Config:

Variável de ambiente	Descrição
DATABRICKS_HOST	O Databricks host, especificado como https://accounts.cloud.databricks.com para account operações ou o workspace URL de destino, por exemplo,https://dbc-a1b2345c-d6e7.cloud.databricks.com para workspace operações.
DATABRICKS_ACCOUNT_ID	A ID Databricks account , somente se o host for o URL do console account.
DATABRICKS_CLIENT_ID	O ID do cliente da entidade de serviço, apenas para federação de identidade de carga de trabalho. Não deve ser definido se a autenticação for feita usando uma política de federação de tokens account-wide.
DATABRICKS_AUTH_TYPE	O método de autenticação a ser usado. env-oidc se os tokens forem provenientes de uma variável de ambiente. file-oidc se os tokens forem provenientes de um arquivo.
DATABRICKS_OIDC_TOKEN_ENV	O nome da variável de ambiente que contém os tokens. Só se aplica se o método de autenticação for env-oidc. padrão para DATABRICKS_OIDC_TOKEN.
DATABRICKS_OIDC_TOKEN_FILEPATH	Caminho para o arquivo que contém os tokens federados. Só se aplica se o método de autenticação for file-oidc.

Escolha seu método de configuração preferido para configurar o ambiente de autenticação:

Environment

Defina as seguintes variáveis de ambiente:

Bash

export DATABRICKS_HOST=<workspace-url-or-account-console-url>
export DATABRICKS_ACCOUNT_ID=<account-id>  # If DATABRICKS_HOST is the account console URL
export DATABRICKS_CLIENT_ID=<client-id>    # Only for workload identity federation
export DATABRICKS_AUTH_TYPE=<auth-method> # env-oidc or file-oidc
export DATABRICKS_OIDC_TOKEN_ENV=<token-env-name>  # If auth type is env-oidc
export DATABRICKS_OIDC_TOKEN_FILEPATH=<token-filepath-name> # If auth type is file-oidc

Profile

Crie ou identifique um perfil de configuração .databrickscfg com os seguintes campos:

[<profile-name>]
host = <workspace-url-or-account-console-url>
account_id = <account-id>  # If host is the account console URL
client_id = <client-id>    # Only for workload identity federation
auth_type = <auth-method>  # env-oidc or file-oidc
oidc_token_env = <token-env-name>  # If auth type is env-oidc
oidc_token_filepath = <token-filepath-name> # If auth type is file-oidc

CLI

Para a CLI do Databricks, faça um das coisas a seguir:

• Defina a variável de ambiente conforme especificado em Environment tab.
• Defina os valores em seu arquivo .databrickscfg conforme especificado no Profile tab.

As variáveis de ambiente sempre têm precedência sobre os valores em seu arquivo .databrickscfg.

Connect

Para o Databricks Connect, o senhor pode:

• Use um perfil de configuração: Defina os valores de workspace-level em seu arquivo .databrickscfg conforme descrito no Profile tab. Defina também o endereço cluster_id como o URL da instância workspace.
• Use a variável de ambiente: Defina os mesmos valores mostrados em Environment (Ambiente ) tab. Defina também o endereço DATABRICKS_CLUSTER_ID como o URL da instância workspace.

Os valores em .databrickscfg têm precedência sobre a variável de ambiente.

Para inicializar o site Databricks Connect com essas configurações, consulte Compute configuration for Databricks Connect.

VS Code

Para a extensão do Databricks para Visual Studio Code, faça o seguinte:

1. Defina os valores em seu .databrickscfg arquivo para Databricks workspace-level operações conforme especificado no Profile. tab
2. No painel Configuração da extensão do Databricks para Visual Studio Code, clique em Configurar Databricks .
3. Na paleta de comandos , em Databricks Host , digite o URLworkspace, por exemplo, https://dbc-a1b2345c-d6e7.cloud.databricks.com, e pressione Enter.
4. Na paleta de comandos , selecione o nome do perfil de destino na lista para o URL.

Para obter mais detalhes, consulte Configurar autorização para a extensão Databricks para Visual Studio Code.

Terraform

Para account-level operações

provider "databricks" {
  alias = "accounts"
}

Para workspace-level operações:

provider "databricks" {
  alias = "workspace"
}

Python

Para workspace-level operações:

Python

from databricks.sdk import WorkspaceClient

# Uses environment configuration automatically
w = WorkspaceClient()

Para account-level operações:

Python

from databricks.sdk import AccountClient

# Uses environment configuration automatically
a = AccountClient()

Java

Para workspace-level operações:

Java

import com.databricks.sdk.WorkspaceClient;

// Uses environment configuration automatically
WorkspaceClient w = new WorkspaceClient();

Para account-level operações:

Java

import com.databricks.sdk.AccountClient;

// Uses environment configuration automatically
AccountClient a = new AccountClient();

Go

Para workspace-level operações:

Go

import "github.com/databricks/databricks-sdk-go"

// Uses environment configuration automatically
w := databricks.Must(databricks.NewWorkspaceClient())

Para account-level operações:

Go

import "github.com/databricks/databricks-sdk-go"

// Uses environment configuration automatically
a := databricks.Must(databricks.NewAccountClient())

Para obter mais informações sobre a autenticação com Databricks ferramentas e SDKs que usam Go e que implementam a autenticação unificada de clienteDatabricks, consulte Autenticar o Databricks SDK para Go com seu Databricks account ou workspace.

Acessar as APIs da Databricks

Depois de configurar seu ambiente, o senhor pode usar a CLI e os SDKs da Databricks normalmente. Eles lidam automaticamente com a troca de tokens e usam os tokens OAuth resultantes para a autenticação API.

Por exemplo, com a CLI:

Bash

databricks workspace list

Ou com o Python SDK:

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()  # Uses environment configuration
clusters = w.clusters.list()

Implemente um provedor de autorização personalizado

Se os tokens federados forem provenientes de uma fonte diferente da variável de ambiente ou de um arquivo, o senhor poderá usar um dos SDKs do Databricks para escrever uma implementação personalizada para recuperar os tokens federados.

Python

Python

from databricks.sdk import oidc
from databricks.sdk.core import (Config, CredentialsProvider, credentials_strategy, oidc_credentials_provider)


class MyCustomIdTokenSource(oidc.IdTokenSource):
    def id_token(self) -> oidc.IdToken:
        token = ...  # Implement logic to return the ID token here
        return oidc.IdToken(jwt=token)


@credentials_strategy("my-custom-oidc", "")
def my_custom_oidc_strategy(cfg: Config) -> CredentialsProvider:
    return oidc_credentials_provider(cfg, MyCustomIdTokenSource())


if __name__ == "__main__":
    cfg = Config(
        host="https://my-workspace.cloud.databricks.com",
        credentials_strategy=my_custom_oidc_strategy
    )
    from databricks.sdk import WorkspaceClient
    w = WorkspaceClient(config=cfg)
    # Use the client...

Java

Java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
import com.databricks.sdk.core.TokenProvider;
import com.databricks.sdk.core.Token;
import java.time.Instant;

public class CustomOIDCExample {

    // Custom TokenProvider that returns an OIDC ID token
    static class MyCustomIdTokenSource implements TokenProvider {
        @Override
        public Token getToken() {
            // TODO: Implement logic to fetch or generate the ID token
            String jwt = "...";  // your OIDC token here
            return new Token(jwt, Instant.now().plusSeconds(3600)); // token with expiry
        }
    }

    public static void main(String[] args) {
        // Configure with workspace host
        DatabricksConfig cfg = new DatabricksConfig()
            .setHost("https://my-workspace.cloud.databricks.com")
            .setTokenProvider(new MyCustomIdTokenSource()); // plug in custom OIDC provider

        // Initialize the workspace client
        WorkspaceClient w = new WorkspaceClient(cfg);

        System.out.println("Databricks client initialized: " + w);

        // Use the client...
    }
}

Go

Go

package main

import (
    "context"
    "fmt"

    "github.com/databricks/databricks-sdk-go"
    "github.com/databricks/databricks-sdk-go/config"
    "github.com/databricks/databricks-sdk-go/credentials"
)

// MyCustomIdTokenSource implements a custom OIDC token source
type MyCustomIdTokenSource struct{}

func (s *MyCustomIdTokenSource) IDToken(ctx context.Context) (*credentials.IDToken, error) {
    // TODO: Implement logic to return the ID token
    token := "..."
    return &credentials.IDToken{JWT: token}, nil
}

// myCustomOIDCStrategy is a custom credentials strategy
func myCustomOIDCStrategy(cfg *config.Config) (credentials.CredentialsProvider, error) {
    return credentials.NewOIDCCredentialsProvider(cfg, &MyCustomIdTokenSource{}), nil
}

func main() {
    cfg := &config.Config{
        Host: "https://my-workspace.cloud.databricks.com",
    }

    // Register the custom credentials strategy
    credentials.Register("my-custom-oidc", myCustomOIDCStrategy)

    // Initialize the Databricks workspace client with custom auth
    w, err := databricks.NewWorkspaceClientWithConfig(cfg)
    if err != nil {
        panic(err)
    }

    fmt.Println("Databricks client initialized:", w)
    // Use the client...
}

Troca manual de tokens

Se o senhor não estiver usando os SDKs Databricks, CLI ou outras ferramentas compatíveis com a autenticação unificada de clientes, poderá trocar manualmente um JWT do seu provedor de identidade por um token Databricks OAuth . Para isso, envie uma solicitação para os tokens Databricks endpoint usando o OAuth 2.0 tokens Exchange(RFC 8693).

Primeiro, obtenha um JWT federado do seu provedor de identidade seguindo a documentação. Em seguida, troque o JWT por um token Databricks OAuth e use esse token para acessar Databricks REST APIs:

Troque um JWT federado por um Databricks OAuth tokens

Para políticas de federação em todo o site account, esse comando troca um JWT federado por um Databricks OAuth tokens:

Bash

curl --request POST https://<databricks-workspace-host>/oidc/v1/token \
  --data "subject_token=${FEDERATED_JWT_TOKEN}" \
  --data 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data 'scope=all-apis'

dica

Para acessar Databricks account recurso, use o URL https://<databricks-account-host>/oidc/accounts/<account-id>/v1/token.

Para políticas de federação de entidades de serviço, inclua o ID do cliente na solicitação:

Bash

curl --request POST https://<databricks-workspace-host>/oidc/v1/token \
  --data "client_id=${CLIENT_ID}" \
  --data "subject_token=${FEDERATED_JWT_TOKEN}" \
  --data 'subject_token_type=urn:ietf:params:oauth:token-type:jwt' \
  --data 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data 'scope=all-apis'

Substitua CLIENT_ID pelo UUID da entidade de serviço (por exemplo, 7cb2f8a4-49a7-4147-83db-35cb69e5cede).

Se os tokens do seu provedor de identidade forem válidos e corresponderem à sua política de federação, o senhor receberá uma resposta padrão JSON que inclui um Databricks OAuth tokens no campo access_token. Esses tokens OAuth podem ser usados para acessar Databricks APIs. Os tokens Databricks OAuth resultantes têm a mesma reivindicação de expiração (exp) que o JWT fornecido no parâmetro subject_token.

Resposta de exemplo:

JSON

{
  "access_token": "eyJraWQ...odi0WFNqQw",
  "scope": "all-apis",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use os tokens OAuth para chamar Databricks APIs

O senhor pode então usar os tokens Databricks OAuth resultantes como tokens portadores para acessar Databricks APIs. Por exemplo, para chamar a API do Databricks SCIM Me para recuperar seu usuário e nome de exibição do Databricks:

Bash

TOKEN='<your-databricks-oauth-token>'

curl --header "Authorization: Bearer $TOKEN" \
  --url https://${DATABRICKS_WORKSPACE_HOSTNAME}/api/2.0/preview/scim/v2/Me

A resposta deve ser semelhante à seguinte:

JSON

{
  "userName": "username@mycompany.com",
  "displayName": "Firstname Lastname"
}