Autenticar com um token de provedor de identidade

Esta página explica como autenticar no Azure Databricks usando um token emitido pelo provedor de identidade da sua organização.

O Azure Databricks dá suporte ao OAuth 2.0 Token Exchange para permitir que você troque um token de identidade federada por um token OAuth do Databricks. Com a federação de tokens, a CLI do Databricks, SDKs e outras ferramentas podem lidar automaticamente com essa troca e gerenciar tokens de acesso para você.

O tempo de vida de cada token de acesso é derivado do tempo de vida do token federado que você fornece, que geralmente é de uma hora, mas pode variar. As ferramentas atualizam os tokens automaticamente conforme necessário, para que você não precise solicitar ou girar credenciais manualmente.

Processo de autenticação

Para autenticar o acesso à API do Azure Databricks com um token de um provedor de identidade federada, primeiro defina as variáveis de ambiente ou os campos de configuração necessários. Sua ferramenta ou SDK preferido recupera o Token Web JSON federado (JWT) do local especificado, troca-o por um token OAuth do Azure Databricks e usa o token OAuth para autenticar chamadas de API REST do Azure Databricks.

Pré-requisitos

Antes de começar, execute as seguintes etapas:

1. Crie uma política de federação para sua conta 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. As etapas 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 do token federado. Defina as seguintes variáveis de ambiente, .databrickscfg campos, campos Terraform ou Config campos:

• Anfitrião Databricks:https://accounts.azuredatabricks.net para operações de conta ou a URL de destino por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net , para operações de espaço de trabalho.
• ID da conta Databricks: Apenas necessário se o anfitrião for o URL da consola da conta.
• ID do cliente da entidade de serviço: Necessário apenas para a federação de identidades da carga de trabalho. Não deve ser definido se autenticar usando uma política de federação de token em toda a conta.
• Tipo de autenticação Databricks:env-oidc se o token vem de uma variável de ambiente. file-oidc se o token vem de um arquivo.
• Variável de ambiente do token OIDC: O nome da variável de ambiente que contém o token. Apenas necessário se o método de autenticação for env-oidc. O padrão é DATABRICKS_OIDC_TOKEN.
• Caminho do arquivo do token OIDC: Caminho para o arquivo que contém o token federado. Apenas necessário se o método de autenticação for file-oidc.

Para obter uma referência completa de todas as variáveis de ambiente de autenticação unificada e campos de configuração, consulte Variáveis de ambiente e campos para autenticação unificada.

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

Meio Ambiente

Defina as seguintes variáveis de ambiente:

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 .databrickscfgconfiguração 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, siga um destes procedimentos:

• Defina as variáveis de ambiente conforme especificado na guia Ambiente .
• Defina os valores em seu .databrickscfg arquivo conforme especificado na guia Perfil .

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

Connect

Para o Databricks Connect, você pode:

• Use um perfil de configuração: No seu arquivo .databrickscfg, defina valores ao nível do espaço de trabalho conforme descrito na guia Perfil. Também deve definir o URL da instância do seu cluster_id espaço de trabalho.
• Use variáveis de ambiente: Estabeleça os mesmos valores mostrados na guia Ambiente. Defina também a URL da instância do para o seu espaço de trabalho.

Os valores em .databrickscfg têm precedência sobre as variáveis de ambiente.

Para inicializar o Databricks Connect com essas configurações, consulte Configuração de computação para o Databricks Connect.

Código VS

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

1. Defina os valores em seu .databrickscfg arquivo para operações no nível do espaço de trabalho do Azure Databricks, conforme especificado na guia Perfil .
2. No painel Configuração da extensão Databricks para Visual Studio Code, clique em Configurar Databricks.
3. Na Paleta de comandos, para Databricks Host, insira sua URL por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net, e pressione Enter.
4. Na Paleta de comandos, selecione o nome do seu perfil de destino na lista associada ao seu URL.

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

Terraform

Para operações no nível da conta

provider "databricks" {
  alias = "accounts"
}

Para operações no nível do espaço de trabalho:

provider "databricks" {
  alias = "workspace"
}

Python

Para operações no nível do espaço de trabalho:

from databricks.sdk import WorkspaceClient

# Uses environment configuration automatically
w = WorkspaceClient()

Para operações no nível da conta:

from databricks.sdk import AccountClient

# Uses environment configuration automatically
a = AccountClient()

Java

Para operações no nível do espaço de trabalho:

import com.databricks.sdk.WorkspaceClient;

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

Para operações no nível da conta:

import com.databricks.sdk.AccountClient;

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

Go

Para operações no nível do espaço de trabalho:

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

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

Para operações no nível da conta:

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 ferramentas e SDKs do Databricks que usam o Go e que implementam a autenticação unificada do cliente Databricks, consulte Autenticar o SDK do Databricks para Go com sua conta ou espaço de trabalho do Azure Databricks.

Aceder às APIs do Databricks

Depois de configurar seu ambiente, você pode usar a CLI e os SDKs do Databricks normalmente. Eles lidam automaticamente com a troca de tokens e usam o token OAuth resultante para autenticação de API.

CLI

databricks clusters list

Python

from databricks.sdk import WorkspaceClient

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

Java

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();
List<ClusterDetails> clusters = w.clusters().list();

Go

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

w := databricks.Must(databricks.NewWorkspaceClient())
clusters := w.Clusters.ListAll(context.Background(), compute.List{})

Implementar um provedor de autorização personalizado

Se seu token federado vier de uma fonte diferente de variáveis de ambiente ou de um arquivo, você poderá usar um dos SDKs do Azure Databricks para escrever uma implementação personalizada para recuperar seu token federado.

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

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
import com.databricks.sdk.core.CredentialsProvider;
import com.databricks.sdk.core.oauth.IDTokenSource;
import com.databricks.sdk.core.oauth.IDToken;

public class CustomOIDCExample {

    // Custom IDTokenSource that returns an OIDC ID token
    static class MyCustomIdTokenSource implements IDTokenSource {
        @Override
        public IDToken getIDToken(String audience) {
            // TODO: Implement logic to fetch or generate the ID token
            String jwt = "...";  // your OIDC token here
            return new IDToken(jwt);
        }
    }

    public static void main(String[] args) {
        // TODO: Wrap MyCustomIdTokenSource in a CredentialsProvider
        // See the SDK documentation for the appropriate method
        CredentialsProvider provider = ...; // Configure with MyCustomIdTokenSource

        // Configure with workspace host and custom OIDC provider
        DatabricksConfig cfg = new DatabricksConfig()
            .setHost("https://my-workspace.cloud.databricks.com")
            .setCredentialsProvider(provider);

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

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

        // Use the client...
    }
}

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...
}

Trocar manualmente um token

Se você não estiver usando os SDKs do Azure Databricks, CLI ou outras ferramentas que dão suporte à autenticação unificada, poderá trocar manualmente um JWT do seu provedor de identidade por um token OAuth do Databricks. Para fazer isso, envie uma solicitação para o ponto de extremidade de token do Azure Databricks usando o OAuth 2.0 Token Exchange (RFC 8693).

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

Troque um JWT federado por um token OAuth Databricks

Para políticas de federação em toda a conta, este comando troca um JWT federado por um token OAuth do Databricks:

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'

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

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 do principal de serviço (por exemplo, 7cb2f8a4-49a7-4147-83db-35cb69e5cede).

Se o token do seu provedor de identidade for válido e corresponder à sua política de federação, você receberá uma resposta JSON padrão que inclui um token OAuth do Databricks no campo access_token. Este token OAuth pode ser usado para acessar APIs do Databricks. O token Databricks OAuth resultante tem a mesma declaração de expiração (exp) que o JWT fornecido no parâmetro subject_token.

Resposta de exemplo:

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

Usar o token OAuth para chamar APIs do Databricks

Em seguida, você pode usar o token Databricks OAuth resultante como um token de portador para acessar APIs do Databricks. Por exemplo, para chamar a API SCIM Me do Databricks para recuperar o usuário e o nome de exibição do Databricks:

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:

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