Autenticación con un token de proveedor de identidades

En esta página se explica cómo autenticarse en Azure Databricks mediante un token emitido por el proveedor de identidades de la organización.

Azure Databricks admite OAuth 2.0 Token Exchange para permitirle intercambiar un token de identidad federada para un token de OAuth de Databricks. Con la federación de tokens, la CLI de Databricks, los SDK y otras herramientas pueden controlar automáticamente este intercambio y administrar los tokens de acceso automáticamente.

La duración de cada token de acceso se deriva de la duración del token federado que proporcione, que suele ser de una hora, pero puede variar. Las herramientas actualizan los tokens automáticamente según sea necesario, por lo que no es necesario solicitar ni rotar las credenciales manualmente.

Proceso de autenticación

Para autenticar el acceso a la API de Azure Databricks con un token de un proveedor de identidades federado, establezca primero las variables de entorno o los campos de configuración necesarios. La herramienta o el SDK preferidos recuperan el token web JSON federado (JWT) de la ubicación que especifique, lo intercambia por un token de OAuth de Azure Databricks y usa el token de OAuth para autenticar las llamadas a la API rest de Azure Databricks.

Prerrequisitos

Antes de comenzar, realice los pasos siguientes:

1. Cree una directiva de federación para su cuenta o entidad de servicio.
2. Obtenga un JWT válido del proveedor de identidades que coincida con la directiva. Los tokens deben estar firmados mediante RS256 o ES256. Los pasos varían según el proveedor, por lo que consulte la documentación del proveedor o pregunte a un administrador.

Configuración del entorno

Configure el entorno en función de dónde procede el token federado. Establezca las siguientes variables de entorno, .databrickscfg campos, campos de Terraform o Config campos:

• Host de Databricks:https://accounts.azuredatabricks.net para las operaciones de cuenta o la dirección URL de destino por área de trabajo, por ejemplo https://adb-1234567890123456.7.azuredatabricks.net , para las operaciones del área de trabajo.
• Identificador de cuenta de Databricks: Solo es necesario si el host es la dirección URL de la consola de la cuenta.
• Identificador de cliente de la entidad de servicio: Solo es necesario para la federación de identidades de carga de trabajo. No se debe establecer si se autentica con una directiva de federación de tokens para toda la cuenta.
• Tipo de autenticación de Databricks:env-oidc si el token procede de una variable de entorno. file-oidc si el token procede de un archivo.
• Variable de entorno de token de OIDC: Nombre de la variable de entorno que contiene el token. Solo es necesario si el método de autenticación es env-oidc. Tiene como valor predeterminado DATABRICKS_OIDC_TOKEN.
• Ruta de archivo de token de OIDC: Ruta de acceso al archivo que contiene el token federado. Solo es necesario si el método de autenticación es file-oidc.

Para obtener una referencia completa de todas las variables de entorno de autenticación unificada y los campos de configuración, consulte Variables de entorno y campos para la autenticación unificada.

Elija su método de configuración preferido para configurar el entorno de autenticación:

Medio ambiente

Establezca estas variables de entorno:

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

Cree o identifique un .databrickscfgperfil de configuración con los siguientes 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

Interfaz de línea de comandos (CLI)

Para la CLI de Databricks, realice una de las siguientes acciones:

• Establezca las variables de entorno como se especifica en la pestaña Entorno .
• Establezca los valores del .databrickscfg archivo como se especifica en la pestaña Perfil .

Las variables de entorno siempre tienen prioridad sobre los valores del archivo .databrickscfg.

Conexión

Para Databricks Connect, puede optar por:

• Use un perfil de configuración: Establezca los valores a nivel de área de trabajo en el .databrickscfg archivo según lo descrito en la pestaña Perfil. También configure la cluster_id dirección URL de la instancia de su área de trabajo.
• Usar variables de entorno: Establezca los mismos valores que se muestran en la pestaña Entorno. Además, establezca la dirección URL de la instancia del área de trabajo en DATABRICKS_CLUSTER_ID.

Los valores de .databrickscfg tienen prioridad sobre las variables de entorno.

Para inicializar Databricks Connect con estas opciones, consulte Configuración de proceso para Databricks Connect.

Código de VS

Para la extensión de Databricks para Visual Studio Code, haga lo siguiente:

1. Establezca los valores del .databrickscfg archivo para las operaciones de nivel de área de trabajo de Azure Databricks tal como se especifica en la pestaña Perfil .
2. En el panel Configuración de la extensión de Databricks para Visual Studio Code, haga clic en Configurar Databricks.
3. En la Paleta de comandos, para Host de Databricks, escriba su URL por área de trabajo, como, por ejemplo, https://adb-1234567890123456.7.azuredatabricks.net, y presione Enter.
4. En la paleta de comandos, seleccione el nombre del perfil de destino en la lista de la dirección URL.

Para obtener más información, consulte Configuración de la autorización para la extensión de Databricks para Visual Studio Code.

Terraform

Para las operaciones de nivel de cuenta

provider "databricks" {
  alias = "accounts"
}

Para las operaciones de nivel de área de trabajo:

provider "databricks" {
  alias = "workspace"
}

Pitón

Para las operaciones de nivel de área de trabajo:

from databricks.sdk import WorkspaceClient

# Uses environment configuration automatically
w = WorkspaceClient()

Para las operaciones de nivel de cuenta:

from databricks.sdk import AccountClient

# Uses environment configuration automatically
a = AccountClient()

Java

Para las operaciones de nivel de área de trabajo:

import com.databricks.sdk.WorkspaceClient;

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

Para las operaciones de nivel de cuenta:

import com.databricks.sdk.AccountClient;

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

Go

Para las operaciones de nivel de área de trabajo:

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

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

Para las operaciones de nivel de cuenta:

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

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

Para obtener más información sobre la autenticación con herramientas y SDK de Databricks que usan Go y que implementan la autenticación unificada de cliente de Databricks, consulte Autenticación del SDK de Databricks para Go con su cuenta de Azure Databricks o su área de trabajo.

Acceso a las API de Databricks

Después de configurar el entorno, puede usar normalmente la CLI y los SDK de Databricks. Controlan automáticamente el intercambio de tokens y usan el token de OAuth resultante para la autenticación de API.

Interfaz de línea de comandos (CLI)

databricks clusters list

Pitón

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{})

Implementación de un proveedor de autorización personalizado

Si el token federado procede de un origen distinto de las variables de entorno o un archivo, puede usar uno de los SDK de Azure Databricks para escribir una implementación personalizada para recuperar el token federado.

Pitón

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

Intercambio manual de un token

Si no usa los SDK de Azure Databricks, la CLI u otras herramientas que admiten la autenticación unificada, puede intercambiar manualmente un JWT desde el proveedor de identidades para un token de OAuth de Databricks. Para ello, envíe una solicitud al punto de conexión del token de Azure Databricks mediante el intercambio de tokens de OAuth 2.0 (RFC 8693).

En primer lugar, obtenga un JWT federado del proveedor de identidades siguiendo su documentación. A continuación, intercambie el JWT para un token de OAuth de Databricks y use ese token para acceder a las API rest de Databricks:

Intercambio de un JWT federado para un token de OAuth de Databricks

Para las directivas de federación de toda la cuenta, este comando intercambia un JWT federado para un token de OAuth de 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'

En el caso de las directivas de federación de la entidad de servicio, incluya el identificador de cliente en la solicitud:

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'

Reemplaza CLIENT_ID por el UUID del principal de servicio (por ejemplo, 7cb2f8a4-49a7-4147-83db-35cb69e5cede).

Si el token del proveedor de identidades es válido y coincide con la directiva de federación, recibirá una respuesta JSON estándar que incluye un token de OAuth de Databricks en el campo access_token. Este token de OAuth se puede usar para acceder a las API de Databricks. El token de OAuth de Databricks resultante tiene la misma notificación de expiración (exp) que el JWT proporcionado en el parámetro subject_token.

Respuesta de ejemplo:

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

Uso del token de OAuth para llamar a las API de Databricks

A continuación, puede usar el token de OAuth de Databricks resultante como token de portador para acceder a las API de Databricks. Por ejemplo, para utilizar la API SCIM Me de Databricks y recuperar tu usuario de Databricks y tu nombre mostrado:

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

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

La respuesta debe ser similar a la siguiente:

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