Aller au contenu principal
Dernière mise à jour le

S'authentifier avec des jetons ID Google

Pour vous authentifier auprès des APIs REST Databricks, utilisez Databricks OAuth, notre solution recommandée pour toutes les plateformes cloud. OAuth 2.0 est le protocole standard que Databricks utilise pour l'autorisation déléguée. Il fournit un accès sécurisé aux APIs REST et prend en charge des mécanismes tels que les refresh tokens pour maintenir l'accès au fil du temps.

Vous pouvez également utiliser les jetons d’identification Google pour l’authentification, principalement sur Google Cloud. Ces jetons suivent des standards ouverts tels que OpenID Connect (OIDC).

Les APIs REST Databricks ne prennent en charge que les jetons OIDC émis par Google, qui sont communément appelés jetons d'identité Google. Pour éviter toute confusion, le reste de cette page utilise le terme jeton Google ID et non jeton OIDC .

remarque

Si vous utilisez votre propre fournisseur d'identité pour configurer le Single Sign On vers Databricks, vous ne pouvez pas vous authentifier avec des jetons Google ID.

Cette page décrit les étapes pour s'authentifier afin d'utiliser les API REST de Databricks et comment créer les comptes de service Google Cloud requis et générer des jetons pour ces comptes.

Configuration du compte de service et flux d'authentification​

Vous pouvez utiliser un seul jeton d'identité Google pour les APIs au niveau du compte ou les APIs au niveau du Workspace, mais vous ne pouvez pas l'utiliser aux deux fins. Les étapes de configuration des jetons pour les APIs au niveau du workspace et au niveau du compte sont principalement les mêmes. Les différences importantes sont signalées dans les instructions.

Pour les environnements de production, Databricks recommande d'utiliser deux comptes de service Google Cloud :

  • SA-1 : exécute vos workloads et récupère les jetons.
  • SA-2 : Détient les autorisations pour vos ressources Databricks et GCP.

Accordez à SA-1 l'autorisation d'emprunter l'identité de SA-2 afin d'appeler les API REST Databricks.

Avec ce modèle d'usurpation d'identité, une équipe peut gérer la sécurité des charges de travail et une autre équipe peut gérer la sécurité des ressources. Puisque vous n'accordez les permissions d'usurpation d'identité qu'au besoin, cette approche offre sécurité et flexibilité à votre organisation.

Pour le développement ou le test, vous pouvez simplifier la configuration en utilisant l'une des options suivantes :

  • Utilisez votre compte utilisateur Google pour usurper l'identité de SA-2. Vous devez disposer du rôle roles/iam.serviceAccountTokenCreator.
  • Utilisez un *compte de service unique* pour agir à la fois en tant que SA-1 et SA-2.

Transmission des identifiants​

Quelques méthodes d'API REST Databricks nécessitent le pass-through des identifiants . Pour appeler ces méthodes, en plus de l'ID Google, vous devez également transmettre un jeton d'accès Google OAuth avec le périmètre cloud-platform dans un en-tête HTTP. Le serveur Databricks utilise le jeton d'accès Google OAuth pour appeler les APIs Google Cloud au nom de l'appelant.

Databricks ne valide ni ne conserve le jeton d'accès.

important

Pour déterminer si la transmission des identifiants est requise pour une opération, référez-vous à la documentation de l'API pour chaque opération d'API. Ces APIs requièrent l'en-tête HTTP X-Databricks-GCP-SA-Access-Token dans la requête.

Étape 1 : Créer deux comptes de service​

  1. Créez deux nouveaux comptes de service Google Cloud. Suivez les instructions de l'article Google Création d'un compte de service. Pour utiliser la Google Cloud Console, accédez à la page Comptes de service et choisissez un projet Google Cloud dans lequel le créer. Le projet Google Cloud dans lequel vous créez ces comptes de service n'a pas besoin de correspondre au projet que vous utilisez pour le workspace Databricks, et les nouveaux comptes de service n'ont pas non plus besoin d'utiliser le même projet Google Cloud que les autres.

    • Compte de service de création de jetons (SA-1) : ce compte de service automatise la création de jetons pour le compte de service principal. Ces jetons seront utilisés pour appeler les API REST Databricks. La documentation Google appelle cela SA-1 .
    • Compte de service principal pour les API REST Databricks (SA-2) : ce compte de service agit en tant que principal (l'utilisateur d'automatisation) pour les API REST Databricks et les workflows automatisés. La documentation Google appelle cela SA-2 .

    Enregistrez l'adresse e-mail des deux comptes de service pour les étapes ultérieures.

  2. Créez une clé de compte de service pour votre compte de service de création de jetons (SA-1) et enregistrez-la dans un fichier local appelé SA-1-key.json.

    1. Depuis la console Google Cloud, page Comptes de service, cliquez sur l'adresse e-mail de SA-1.
    2. Accédez à l'onglet tab .
    3. Cliquez sur Ajouter une clé > Créer une nouvelle clé .
    4. Pour le type de clé, choisissez **JSON**.
    5. Cliquez sur Créer .
    6. La page web effectue un download d'un fichier clé dans votre navigateur. Déplacez ce fichier vers votre répertoire de travail local et renommez-le SA-1-key.json.

    Pour des instructions supplémentaires, consultez l'article Google Création de clés de compte de service.

  3. Accordez à votre compte de service de création de jetons (SA-1) le rôle de créateur de jetons de compte de service sur votre compte de service principal (SA-2).

    1. Dans la console Google Cloud, sur la page Comptes de service, cliquez sur l'adresse e-mail de SA-2.
    2. Allez à l'onglet Autorisations .
    3. Cliquez sur Principaux avec accès .
    4. Cliquez sur Accorder l'accès .
    5. Dans le champ Nouveaux principaux , collez l'adresse e-mail de votre SA de création de jeton (SA-1).
    6. Dans le champ Rôle , choisissez Créateur de jetons de compte de service .
    7. Cliquez sur Enregistrer .

Étape 2 : créer un jeton d'identification Google​

Databricks recommande d'utiliser l'interface de ligne de commande Google Cloud (CLI) (gcloud) pour générer des jetons d'identification afin d'appeler les API REST de Databricks.

important

Le jeton d'ID généré expire dans une heure. Vous devez terminer toutes les étapes restantes dans ce délai. Si le jeton expire avant que vous ne terminiez les étapes ultérieures, telles que l'appel d'APIs Databricks, vous devez répéter cette étape pour générer un nouveau jeton d'ID Google.

  1. Installez le Google Cloud CLI sur votre machine. Consultez l'article Google sur l'installation de l'outil gcloud.

  2. Générez des jetons d'ID pour votre compte de service principal en exécutant les commandes suivantes.

    • Remplacez <SA-1-key-json> par le chemin d'accès à votre fichier de clé SA-1 au format JSON.
    • Remplacez <SA-2-email> par l'adresse e-mail de SA-2.
    • Remplacez <audience> comme suit en fonction de votre cas d'utilisation :
      • Pour les API de niveau workspace , remplacez par l'URL de votre workspace, qui se présente sous la forme https://999999999992360.0.gcp.databricks.com. Chaque workspace possède une URL de workspace unique et différente. Pour appeler les APIs sur plusieurs Workspace, créez plusieurs jetons d'ID Google avec différentes valeurs audience.
      • Pour l'API au niveau du compte , remplacez par https://accounts.gcp.databricks.com. Différents comptes partagent tous la même valeur audience.

    Exécutez les commandes suivantes pour une utilisation avec les systèmes de production :

    Bash
    gcloud auth login --cred-file=<SA-1-key-json>

    gcloud auth print-identity-token \
     --impersonate-service-account="<SA-2-email>" \
     --include-email \
     --audiences="<audience>"

    Pour une utilisation hors production, si vous utilisez votre compte utilisateur pour usurper l'identité de SA-2, utilisez ces commandes :

    Bash
    gcloud auth login

    gcloud auth print-identity-token \
     --impersonate-service-account="<SA-2-email>" \
     --audiences="<audience>" --include-email

    Pour une utilisation hors production, si vous utilisez un compte de service pour SA-1 et SA-2, utilisez ces commandes avec le fichier JSON de la clé du compte de service :

    Bash
    gcloud auth login --cred-file=<SA-key-json>

    gcloud auth print-identity-token --audiences="<audience>"

  3. Enregistrez la longue ligne à la fin de la sortie dans un fichier appelé google-id-token-sa-2.txt.

    Il produit un texte similaire à ce qui suit :

    WARNING: This command is using service account impersonation. All API calls will be executed as [<SA-2-email>].

    eyJhba7s86dfa9s8f6a99das7fa68s7d6...N8s67f6saa78sa8s7dfiLlA

Étape 3 : Créez un jeton d’accès Google OAuth (uniquement pour les APIs nécessitant un transfert d’informations d’identification).​

remarque

Cette étape est requise uniquement pour appeler des APIs qui nécessitent la transmission des identifiants. Pour déterminer si le passthrough d'identifiants est requis pour une opération, consultez la documentation API pour chaque opération API.

La demande de génération d'un jeton d'accès inclut un champ lifetime qui définit la durée de validité du jeton d'accès. Si vous n'avez besoin que le jeton soit actif pendant cinq minutes, définissez-le sur 300s (300 secondes). L'exemple suivant utilise 3600s, ce qui représente une heure.

important
  • Vous devez terminer toutes les étapes restantes dans ce délai imparti. Si le délai expire avant que vous ne complétiez les étapes ultérieures, telles que l'appel d'APIs Databricks, vous devez répéter cette étape pour générer un nouveau jeton d'accès Google OAuth.
  • Par default, une heure (3600s) est la durée maximale que vous pouvez définir pour le champ lifetime. Pour étendre cette limite, contactez l'assistance client Google et demandez une exception.

  1. Exécutez la commande suivante. Remplacez <SA-2-email> par l'adresse e-mail du compte de service pour SA-2. Pour une utilisation hors production ou des tests, si vous utilisez un seul compte de service ou si vous utilisez un compte utilisateur pour usurper l'identité d'un compte de service, remplacez <SA-2-email> par l'adresse e-mail du compte de service.

    Bash
    gcloud auth print-access-token --impersonate-service-account=<SA-2-email>

  2. Enregistrez la longue ligne à la fin de la sortie dans un fichier appelé access-token-sa-2.txt.

    Il produit un texte similaire à ce qui suit :

    WARNING: This command is using service account impersonation. All API calls will be executed as [<SA-2-email>].

    eyJhba7s86dfa9s8f6a99das7fa68s7d6...N8s67f6saa78sa8s7dfiLlA

Étape 4 : Ajouter le compte de service principal en tant qu'utilisateur​

Pour utiliser les jetons Google ID afin d'appeler les APIs au niveau du workspace ou les APIs au niveau du compte Databricks, ajoutez le compte de service principal (SA-2) en tant qu'utilisateur dans l'environnement Databricks approprié :

Vous devez générer un jeton d’identification Google distinct pour chaque type d’API, car le champ audience change en fonction de l’URL de base. Pour plus de détails, consultez Créer un jeton d’identification Google.

remarque

Databricks utilise SA-2 comme identité de l'appelant dans les requêtes API. Vous n'avez pas besoin d'ajouter le compte de service de création de jetons (SA-1) à Databricks. SA-1 n’emprunte l’identité de SA-2 que pour générer des jetons et n’interagit pas directement avec Databricks.

Workspace APIs​

Pour authentifier les APIs au niveau du Workspace avec le jeton d'identification Google, suivez les étapes de la Workspace admin settings tab dans Ajouter des utilisateurs à votre compte. Saisissez l'adresse e-mail de votre compte de service principal (SA-2) lorsque vous y êtes invité.

Ajoutez éventuellement les appartenances à des groupes et les paramètres de contrôle d'accès Databricks nécessaires pour votre nouveau compte de service, en fonction des API REST que vous prévoyez d'appeler et des objets de données que vous souhaitez utiliser. Voir Groupes et Listes de contrôle d'accès.

APIs au niveau du compte​

Pour authentifier les API au niveau du compte avec le jeton d’identification Google, suivez les étapes de la tab Console du compte dans Ajouter des utilisateurs à votre compte. Saisissez l'adresse e-mail de votre compte de service principal (SA-2) lorsque vous y êtes invité. Définissez le nom de manière à refléter clairement l'objectif du compte de service.

Étape 5 : Appeler une API Databricks​

Les jetons que vous devez fournir lors de l'authentification de l'API REST varient en fonction de votre utilisation prévue : soit l'API de compte, soit les APIs au niveau du Workspace. Notez que vous ne pouvez pas utiliser un seul jeton d'identité Google pour accéder aux deux types d'APIs en raison de la différence dans le champ audiences lors de la création du jeton d'identité Google.

Les en-têtes HTTP suivants sont utilisés pour l'authentification Databricks avec les ID Google.

Nom de l'en-tête HTTP

Description

Quels types d'APIs le requièrent ?

Authorization

Jeton d'ID Google pour SA-2 en tant que jeton porteur. La syntaxe est Authentication: Bearer <token>.

Toutes les APIs

X-Databricks-GCP-SA-Access-Token

Jeton d'accès OAuth Google pour SA-2.

Uniquement les APIs au niveau du compte.

Nom de l'en-tête HTTP

Description

Quels types d'APIs le requièrent ?

Authorization

Jeton d'ID Google pour SA-2 en tant que jeton porteur. La syntaxe est Authentication: Bearer <token>.

Toutes les APIs

X-Databricks-GCP-SA-Access-Token

Jeton d'accès OAuth Google pour SA-2.

Uniquement les APIs au niveau du compte.

Exemple de requête d'API au niveau du workspace​

Pour appeler une API REST Databricks pour un Workspace, transmettez un jeton d'identification Google dans l'en-tête HTTP Authorization avec la syntaxe suivante :

Authorization: Bearer <google-id-token>

Le jeton que vous fournissez doit avoir les attributs suivants :

  • The Workspace you access must match the Workspace URL that you provided when you created the token. Consultez Étape 2 : Créer un jeton d'ID Google.
  • Le compte de service qui est utilisé pour l'usurpation d'identité (SA-2) doit être un utilisateur du workspace. Consultez les APIs du Workspace.

L'exemple suivant appelle une API de niveau Workspace pour lister les clusters.

  • Remplacez <google-id-token> par le jeton d'identification Google que vous avez enregistré dans le fichier google-id-token-sa-2.txt.
  • Remplacez <workspace-URL> par l'URL de votre Workspace de base, qui a une forme similaire à https://1234567890123456.7.gcp.databricks.com.
Bash
curl \
  -X GET \
  --header 'Authorization: Bearer <google-id-token>' \
  <workspace-URL>/api/2.0/clusters/list

Exemple de requête API au niveau du compte pour une API qui n'utilise pas la transmission des identifiants​

L'exemple suivant appelle l'API Account pour obtenir une liste d'espaces de travail.

  • Remplacez <google-id-token> par le jeton d'identification Google que vous avez enregistré dans le fichier google-id-token-sa-2.txt.
  • Remplacez <account-id> par votre ID de compte. Pour trouver votre ID de compte :
    1. En tant qu'administrateur de compte, accédez à la console de compte Databricks.
    2. Cliquez sur la flèche vers le bas à côté de votre nom d'utilisateur dans le coin supérieur droit.
    3. Dans le menu déroulant, vous pouvez copier votre ID de compte .
Bash
curl \
  -X GET \
  --header 'Authorization: Bearer <google-id-token>' \
  https://accounts.gcp.databricks.com/api/2.0/accounts/<account-id>/workspaces

Exemple de requête d'API au niveau du compte avec transmission des identifiants​

L'exemple suivant appelle l'API Account pour obtenir une liste d'espaces de travail.

  • Remplacez <google-id-token> par le jeton d'identification Google que vous avez enregistré dans le fichier google-id-token-sa-2.txt.

  • Remplacez <access-token-sa-2> par le jeton d'accès SA-2 que vous avez enregistré dans le fichier access-token-sa-2.txt.

  • Remplacez <account-id> par votre ID de compte. Pour trouver votre ID de compte :

    1. En tant qu'administrateur de compte, accédez à la console de compte Databricks.
    2. En haut à droite, cliquez sur l'icône de profil utilisateur.
    3. Dans la fenêtre contextuelle qui apparaît, copiez l'ID du compte en cliquant sur l'icône à droite de l'ID.

    Trouvez votre ID de compte.

Bash
curl \
  -X GET \
  --header 'Authorization: Bearer <google-id-token>' \
  --header 'X-Databricks-GCP-SA-Access-Token: <access-token-sa-2>' \
  https://accounts.gcp.databricks.com/api/2.0/accounts/<account-id>/workspaces
Sur cette page