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 federado por um token OAuth do Databricks. Com a federação de tokens, a CLI do Databricks, os 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 fornecido, que geralmente é de uma hora, mas pode variar. As ferramentas atualizam tokens automaticamente conforme necessário, portanto, você não precisa solicitar ou girar manualmente as credenciais.

Processo de autenticação

Para autenticar o acesso à API do Azure Databricks com um token de um provedor de identidade federado, primeiro defina as variáveis de ambiente ou os campos de configuração necessários. Sua ferramenta preferencial ou SDK recupera o JWT (Token Web JSON) federado do local especificado, troca-o por um token OAuth do Azure Databricks e usa o token OAuth para autenticar chamadas à 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 provedor ou pergunte a um administrador.

Configurar 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:

• Host do Databricks:https://accounts.azuredatabricks.net para operações de conta ou a URL de destino por workspace, por exemplo https://adb-1234567890123456.7.azuredatabricks.net , para operações de workspace.
• ID da conta do Databricks: Necessário somente se o host for a URL do console da conta.
• ID do cliente da entidade de serviço: Necessário apenas para a federação de identidade de carga de trabalho. Não deve ser definido se a autenticação estiver usando uma política de federação de token em toda a conta.
• Tipo de autenticação do 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. Só será necessário se o método de autenticação for env-oidc. Usa DATABRICKS_OIDC_TOKEN como padrão.
• Caminho de arquivo do token OIDC: Caminho para o arquivo que contém o token federado. Só será 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 preferencial para configurar o ambiente de autenticação:

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 .databrickscfgperfil de configuraçã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

Na 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 do arquivo .databrickscfg.

Connect

Você pode fazer o seguinte com o Databricks Connect:

• Use um perfil de configuração: Defina valores no nível do workspace no arquivo .databrickscfg, conforme descrito na guia Perfil. Defina também a URL da instância do workspace cluster_id.
• Use variáveis de ambiente: Defina os mesmos valores mostrados na guia Ambiente. Também defina a URL da instância do workspace DATABRICKS_CLUSTER_ID.

Valores em .databrickscfg têm precedência sobre variáveis de ambiente.

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

VS Code

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

1. Defina os valores em seu .databrickscfg arquivo para operações no nível do workspace do Azure Databricks, conforme especificado na guia Perfil .
2. No painel Configuração da extensão do Databricks para Visual Studio Code, clique em Configurar o Databricks.
3. Na Paleta de Comandos, em Host do Databricks, insira a URL por workspace, 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 para seu URL.

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

Terraform

Para operações no nível da conta

provider "databricks" {
  alias = "accounts"
}

Para operações no nível do workspace:

provider "databricks" {
  alias = "workspace"
}

Python

Para operações no nível do workspace:

from databricks.sdk import WorkspaceClient

# Uses environment configuration automatically
w = WorkspaceClient()

Para operações de nível de conta:

from databricks.sdk import AccountClient

# Uses environment configuration automatically
a = AccountClient()

Java

Para operações no nível do workspace:

import com.databricks.sdk.WorkspaceClient;

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

Para operações de nível de conta:

import com.databricks.sdk.AccountClient;

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

Go

Para operações no nível do workspace:

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

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

Para operações de nível de conta:

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

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

Para obter mais informações sobre como autenticar com as ferramentas e SDKs do Databricks que usam o Go e que implementam a autenticação unificada do cliente do Databricks, consulte Autenticar o SDK do Databricks para o Go com sua conta ou espaço de trabalho do Azure Databricks.

Acessar APIs do Databricks

Depois de configurar seu ambiente, você pode usar a CLI e os SDKs do Databricks normalmente. Eles manipulam automaticamente 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 o token federado for proveniente de uma origem diferente de variáveis de ambiente ou um arquivo, você poderá usar um dos SDKs do Azure Databricks para gravar 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, a CLI ou outras ferramentas do Azure Databricks que dão suporte à autenticação unificada, você 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 do provedor de identidade seguindo a documentação. Em seguida, troque o JWT por um token OAuth do Databricks e use esse token para acessar AS APIs REST do Databricks:

Trocar um JWT federado por um token OAuth do Databricks

Para políticas de federação em toda a conta, esse 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 provedor de identidade for válido e corresponder à política de federação, você receberá uma resposta JSON padrão que inclui um token OAuth do Databricks no campo access_token. Esse token OAuth pode ser usado para acessar APIs do Databricks. O token OAuth do Databricks 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 OAuth do Databricks resultante como um token de portador para acessar AS APIs do Databricks. Por exemplo, para chamar a API do Databricks SCIM Me para recuperar o usuário do Databricks e o nome de exibição:

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