S’authentifier avec un jeton de fournisseur d’identité

Cette page explique comment s’authentifier auprès d’Azure Databricks à l’aide d’un jeton émis par le fournisseur d’identité de votre organisation.

Azure Databricks prend en charge OAuth 2.0 Token Exchange pour vous permettre d’échanger un jeton d’identité fédéré pour un jeton OAuth Databricks. Avec la fédération de jetons, l’interface CLI Databricks, les kits SDK et d’autres outils peuvent gérer automatiquement cet échange et gérer les jetons d’accès pour vous.

La durée de vie de chaque jeton d’accès est dérivée de la durée de vie du jeton fédéré que vous fournissez, ce qui est le plus souvent une heure, mais peut varier. Les outils actualisent automatiquement les jetons en fonction des besoins. Vous n’avez donc pas besoin de demander ou de faire pivoter manuellement les informations d’identification.

Processus d’authentification

Pour authentifier l’accès à l’API Azure Databricks avec un jeton à partir d’un fournisseur d’identité fédéré, commencez par définir les variables d’environnement ou les champs de configuration requis. Votre outil ou sdk préféré récupère le jeton Web JSON fédéré (JWT) à partir de l’emplacement que vous spécifiez, l’échange pour un jeton OAuth Azure Databricks et utilise le jeton OAuth pour authentifier les appels d’API REST Azure Databricks.

Prerequisites

Avant de commencer, procédez comme suit :

1. Créez une stratégie de fédération pour votre compte ou principal de service.
2. Obtenez un JWT valide auprès de votre fournisseur d’identité qui correspond à la stratégie. Les jetons doivent être signés à l’aide de RS256 ou ES256. Les étapes varient selon le fournisseur. Reportez-vous donc à la documentation de votre fournisseur ou demandez à un administrateur.

Configurer votre environnement

Configurez votre environnement en fonction de l’emplacement de votre jeton fédéré. Définissez les variables d’environnement, les champs, .databrickscfg les champs Terraform ou Config les champs suivants :

• Hôte Databricks :https://accounts.azuredatabricks.net pour les opérations de compte ou l’URL cible par espace de travail, par exemple https://adb-1234567890123456.7.azuredatabricks.net pour les opérations d’espace de travail.
• ID de compte Databricks : Obligatoire uniquement si l’hôte est l’URL de la console de compte.
• ID client du principal de service : Obligatoire uniquement pour la fédération d’identité de charge de travail. Ne doit pas être défini si l’authentification à l’aide d’une stratégie de fédération de jeton à l’échelle du compte.
• Type d’authentification Databricks :env-oidc si le jeton provient d’une variable d’environnement. file-oidc si le jeton provient d’un fichier.
• Variable d’environnement de jeton OIDC : Nom de la variable d’environnement qui contient le jeton. Obligatoire uniquement si la méthode d’authentification est env-oidc. La valeur par défaut est DATABRICKS_OIDC_TOKEN.
• Chemin de fichier de jeton OIDC : Chemin d’accès au fichier qui contient le jeton fédéré. Obligatoire uniquement si la méthode d’authentification est file-oidc.

Pour obtenir une référence complète de toutes les variables d’environnement d’authentification unifiée et des champs de configuration, consultez Variables d’environnement et champs pour l’authentification unifiée.

Choisissez votre méthode de configuration préférée pour configurer l’environnement d’authentification :

Environnement

Définissez les variables d’environnement suivantes :

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

Profil

Créez ou identifiez un .databrickscfgprofil de configuration avec les champs suivants :

[<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

Interface de ligne de commande (CLI)

Pour l’interface CLI Databricks, effectuez l’une des opérations suivantes :

• Définissez les variables d’environnement comme spécifié sous l’onglet Environnement .
• Définissez les valeurs de votre .databrickscfg fichier comme spécifié sous l’onglet Profil .

Les variables d’environnement sont toujours prioritaires sur les valeurs de votre fichier .databrickscfg.

Connectez-vous

Pour Databricks Connect, vous pouvez :

• Utilisez un profil de configuration : Définissez les valeurs au niveau de l’espace de travail dans votre .databrickscfg fichier, comme décrit sous l’onglet Profil . Définissez également l’URL cluster_id de votre instance d’espace de travail.
• Utilisez des variables d’environnement : Définissez les mêmes valeurs que celles affichées sous l’onglet Environnement . Définissez également l’URL DATABRICKS_CLUSTER_ID de votre instance d’espace de travail.

Les valeurs dans .databrickscfg prennent le pas sur les variables d’environnement.

Pour initialiser Databricks Connect avec ces paramètres, consultez Configuration de calcul pour Databricks Connect.

VS Code

Pour l’extension Databricks pour Visual Studio Code, procédez comme suit :

1. Définissez les valeurs dans votre fichier pour les .databrickscfg de travail Azure Databricks, comme spécifié sous l’onglet Profil.
2. Dans le volet Configuration de l’extension Databricks pour Visual Studio Code, cliquez sur Configurer Databricks.
3. Dans la palette de commandes, pour Hôte Databricks, entrez votre URL par espace de travail, par exemple https://adb-1234567890123456.7.azuredatabricks.net, puis appuyez sur Enter.
4. Dans la palette de commandes, sélectionnez le nom de votre profil cible dans la liste de votre URL.

Pour plus d’informations, consultez Configurer l’autorisation pour l’extension Databricks pour Visual Studio Code.

Terraform

Pour les opérations au niveau du compte

provider "databricks" {
  alias = "accounts"
}

Pour les opérations au niveau de l’espace de travail :

provider "databricks" {
  alias = "workspace"
}

Python

Pour les opérations au niveau de l’espace de travail :

from databricks.sdk import WorkspaceClient

# Uses environment configuration automatically
w = WorkspaceClient()

Pour les opérations au niveau du compte :

from databricks.sdk import AccountClient

# Uses environment configuration automatically
a = AccountClient()

Java

Pour les opérations au niveau de l’espace de travail :

import com.databricks.sdk.WorkspaceClient;

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

Pour les opérations au niveau du compte :

import com.databricks.sdk.AccountClient;

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

Go

Pour les opérations au niveau de l’espace de travail :

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

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

Pour les opérations au niveau du compte :

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

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

Pour plus d’informations sur l’authentification avec les outils et les kits de développement logiciel (SDK) Databricks qui utilisent Go et qui implémentent l’Authentification unifiée du client Databricks, consultez Authentifier le kit de développement logiciel (SDK) Databricks pour Go avec votre compte ou votre espace de travail Azure Databricks.

Accéder aux API Databricks

Après avoir configuré votre environnement, vous pouvez utiliser l’interface CLI Databricks et les kits SDK normalement. Ils gèrent automatiquement l’échange de jetons et utilisent le jeton OAuth obtenu pour l’authentification d’API.

Interface de ligne de commande (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{})

Implémenter un fournisseur d’autorisation personnalisé

Si votre jeton fédéré provient d’une source autre que des variables d’environnement ou d’un fichier, vous pouvez utiliser l’un des sdk Azure Databricks pour écrire une implémentation personnalisée pour récupérer votre jeton fédéré.

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

Échanger manuellement un jeton

Si vous n’utilisez pas les kits sdk Azure Databricks, l’interface CLI ou d’autres outils qui prennent en charge l’authentification unifiée, vous pouvez échanger manuellement un JWT à partir de votre fournisseur d’identité pour un jeton OAuth Databricks. Pour ce faire, envoyez une demande au point de terminaison de jeton Azure Databricks à l’aide de l’échange de jetonS OAuth 2.0 (RFC 8693).

Tout d’abord, obtenez un JWT fédéré auprès de votre fournisseur d’identité en suivant leur documentation. Ensuite, échangez le JWT pour un jeton OAuth Databricks et utilisez ce jeton pour accéder aux API REST Databricks :

Échanger un JWT fédéré pour un jeton OAuth Databricks

Pour les stratégies de fédération à l’échelle du compte, cette commande échange un JWT fédéré pour un jeton OAuth 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'

Pour les stratégies de fédération du principal de service, incluez l’ID client dans la requête :

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'

Remplacez CLIENT_ID par l’UUID du principal de service (par exemple, 7cb2f8a4-49a7-4147-83db-35cb69e5cede).

Si le jeton de votre fournisseur d’identité est valide et correspond à votre stratégie de fédération, vous recevez une réponse JSON standard qui inclut un jeton OAuth Databricks dans le champ access_token. Ce jeton OAuth peut être utilisé pour accéder aux API Databricks. Le jeton Databricks OAuth résultant a la même revendication d’expiration (exp) que le JWT fourni dans le paramètre subject_token.

Exemple de réponse :

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

Utiliser le jeton OAuth pour appeler les API Databricks

Vous pouvez ensuite utiliser le jeton OAuth Databricks obtenu comme jeton du porteur pour accéder aux API Databricks. Par exemple, pour appeler l’API Databricks SCIM Me pour récupérer votre utilisateur Databricks et le nom d’affichage :

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

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

La réponse doit ressembler à ce qui suit :

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