Aller au contenu principal
Dernière mise à jour le

Autorisez l'accès du Service Principal à Databricks avec OAuth.

Cette page explique comment autoriser l'accès aux Ressources Databricks depuis des processus non surveillés, tels que des commandes CLI automatisées ou des appels d'API REST effectués à partir de scripts ou d'applications.

Databricks utilise OAuth 2.0 comme protocole préféré pour l’autorisation et l’authentification du Service Principal en dehors de l’interface utilisateur. L'authentification client unifiée automatise la génération et le refresh des jetons. Lorsqu’un Service Principal se connecte et se voit accorder le consentement, OAuth émet un jeton d’accès que la CLI, le SDK ou d’autres outils peuvent utiliser en son nom. Chaque jeton d'accès est valable une heure, après quoi un nouveau jeton est automatiquement demandé.

Sur cette page, l'**autorisation** fait référence à l'utilisation d'OAuth pour accorder à un Service Principal l'accès aux ressources Databricks, tandis que l'**authentification** fait référence à la validation des identifiants via des jetons d'accès.

Pour plus de détails de haut niveau, consultez Autoriser l'accès aux ressources Databricks.

Moyens d'autoriser un Service Principal​

Databricks prend en charge deux méthodes pour autoriser un Service Principal :

  • Automatique (recommandé) : utilisez l’ authentification unifiée avec les outils et les SDK pris en charge, tels que le Databricks Terraform SDK. Cette approche gère la génération et le refresh du jeton automatiquement, et est idéale pour l'automatisation ou d'autres charges de travail sans surveillance.

  • Manuel : Générez un vérificateur de code et un défi, puis échangez-les contre un jeton OAuth. Utilisez cette méthode si votre outil ou API ne prend pas en charge l'authentification unifiée. Vous devrez peut-être créer votre propre mécanisme de refresh de jeton pour votre application. Pour plus de détails, consultez Générer manuellement des jetons d'accès OAuth M2M.

Prérequis​

Avant de configurer OAuth, suivez les étapes suivantes :

  1. Créer un Service Principal Databricks. Consultez Ajouter des services principaux à votre compte.
  2. Accédez à l' tab Configuration du Service Principal et sélectionnez les droits qu'il doit avoir pour ce Workspace.
  3. Accédez à l'onglet Autorisations et accordez l'accès à tous les utilisateurs Databricks, Service Principal et groupes que vous souhaitez gérer et utiliser ce Service Principal. Voir Qui peut gérer et utiliser les Service Principal ?.

Étape 1 : Créez un secret OAuth​

Pour autoriser l'accès à vos Ressources Databricks avec OAuth, vous devez créer un secret OAuth. Le secret est utilisé pour générer des jetons d’accès OAuth à des fins d’authentification. Un Service Principal peut avoir jusqu’à cinq secrets OAuth, et chaque secret peut être valide pendant une durée maximale de deux ans.

Les administrateurs de compte et les administrateurs de Workspace peuvent créer un secret OAuth pour un Service Principal.

  1. Cliquez sur votre nom d'utilisateur dans la barre supérieure et sélectionnez Settings .
  2. Cliquez sur l'onglet **Identity and access tab**.
  3. À côté de **Service principals**, cliquez sur **Gérer**.
  4. Sélectionnez le Service Principal.
  5. Cliquez sur l'onglet tab .
  6. Cliquez sur Générer le secret .
  7. Définissez la durée de vie du secret en jours (730 jours maximum).
  8. Cliquez sur Générer .
  9. Copiez le secret et l'ID client affichés, puis cliquez sur OK . Le secret n'est affiché qu'une seule fois. L'ID client est le même que l'ID d'application du Service Principal.

Les administrateurs de compte peuvent également créer un secret OAuth à partir de la console de compte. Depuis l'onglet **Gestion des utilisateurs**, sélectionnez le Service Principal, puis accédez à l'onglet **Informations d'identification et secrets**.

remarque

Pour permettre au Service Principal d'utiliser des clusters ou des SQL Warehouses, vous devez lui accorder un accès. Consultez les autorisations Compute ou gérez un SQL Warehouse.

Étape 2 : utiliser l'autorisation OAuth​

Pour utiliser l'autorisation OAuth avec l'outil d'authentification unifié, vous devez définir les variables d'environnement, les champs .databrickscfg, les champs Terraform ou les champs Config associés suivants :

  • L'hôte Databricks, spécifié comme https://accounts.cloud.databricks.com pour les opérations de compte ou l'URL du workspace cible, par exemple https://dbc-a1b2345c-d6e7.cloud.databricks.com pour les opérations du workspace.
  • L’ID de compte Databricks, pour les opérations du compte Databricks.
  • L'ID client du Service Principal.
  • Le secret du Service Principal.

Pour effectuer l’authentification de Service Principal OAuth, intégrez ce qui suit dans votre code, en fonction de l’outil ou du SDK participant :

Pour utiliser des variables d'environnement pour un type d'authentification Databricks spécifique avec un outil ou un SDK, consultez Autoriser l'accès aux ressources Databricks ou la documentation de l'outil ou du SDK. Voir aussi Variables et champs d'environnement pour l'authentification unifiée et la Priorité de la méthode d'authentification.

Pour les opérations au niveau du compte, définissez les variables d'environnement suivantes :

  • DATABRICKS_HOST, défini sur la valeur de l'URL de la console de votre compte Databricks, https://accounts.cloud.databricks.com.
  • DATABRICKS_ACCOUNT_ID
  • DATABRICKS_CLIENT_ID
  • DATABRICKS_CLIENT_SECRET

Pour les opérations au niveau du workspace, définissez les variables d'environnement suivantes :

  • DATABRICKS_HOST, défini sur la valeur de l'URL de votre Workspace Databricks, par exemple https://dbc-a1b2345c-d6e7.cloud.databricks.com.
  • DATABRICKS_CLIENT_ID
  • DATABRICKS_CLIENT_SECRET

Générer manuellement des jetons d'accès OAuth M2M​

Cette section est destinée aux outils ou services qui ne prennent pas en charge l'authentification unifiée Databricks. Si vous devez générer, refresh, ou utiliser manuellement des jetons OAuth Databricks pour l'authentification M2M, suivez ces étapes.

Pour générer un jeton d'accès OAuth M2M, utilisez l'ID client du Service Principal et le secret OAuth. Chaque jeton d'accès est valide pendant une heure. Après son expiration, demandez un nouveau jeton. Vous pouvez générer des jetons au niveau du compte ou du Workspace :

Générer un jeton d'accès au niveau du compte​

Utilisez un jeton au niveau du compte pour appeler les APIs REST du compte et de tous les Workspaces auxquels le Service Principal peut accéder.

  1. Localisez votre ID de compte.

  2. Construisez l'URL de l'endpoint de jeton en remplaçant <account-id> dans l'URL suivante par votre ID de compte.

    https://accounts.cloud.databricks.com/oidc/accounts/<my-account-id>/v1/token

  3. Utilisez curl pour demander un jeton d'accès OAuth. Remplacer :

    • <token-endpoint-URL> avec l’URL ci-dessus.
    • <client-id> avec l'ID client du Service Principal (ID d'application).
    • <client-secret> avec le secret OAuth du Service Principal.
    Bash
    export CLIENT_ID=<client-id>
    export CLIENT_SECRET=<client-secret>

      curl --request POST \
      --url <token-endpoint-URL> \
      --user "$CLIENT_ID:$CLIENT_SECRET" \
      --data 'grant_type=client_credentials&scope=all-apis'

    Cela génère une réponse similaire à :

    JSON
    {
      "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
      "token_type": "Bearer",
      "expires_in": 3600
    }

    La portée all-apis demande un jeton d'accès OAuth qui permet au Service Principal d'appeler toute API REST Databricks à laquelle il a l'autorisation d'accéder.

  4. Copiez la valeur access_token de la réponse.

Générez un jeton d'accès au niveau du Workspace​

Utilisez un jeton au niveau du Workspace uniquement avec les APIs REST dans ce Workspace.

  1. Construisez l'URL de l'endpoint du jeton en remplaçant <databricks-instance> par votre <databricks-instance> avec le nom de l'instance de workspace Databricks, par exemple dbc-a1b2345c-d6e7.cloud.databricks.com:

    https://<databricks-instance>/oidc/v1/token

  2. Utilisez curl pour demander un jeton d'accès OAuth. Remplacer :

    • <token-endpoint-URL> avec l’URL ci-dessus.
    • <client-id> avec l'ID client du Service Principal (ID d'application).
    • <client-secret> avec le secret OAuth du Service Principal.
    Bash
    export CLIENT_ID=<client-id>
    export CLIENT_SECRET=<client-secret>

    curl --request POST \
    --url <token-endpoint-URL> \
    --user "$CLIENT_ID:$CLIENT_SECRET" \
    --data 'grant_type=client_credentials&scope=all-apis'

    Cela génère une réponse similaire à :

    JSON
    {
      "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
      "token_type": "Bearer",
      "expires_in": 3600
    }

  3. Copiez la valeur access_token de la réponse.

remarque

Pour générer un jeton pour un endpoint de mise en service, incluez l’ID de l’endpoint et l’action dans votre requête. Consultez Récupérer un jeton OAuth manuellement.

Appeler une API REST Databricks​

Utilisez le jeton d'accès OAuth pour appeler les API REST au niveau du compte ou au niveau du Workspace. Pour appeler les APIs au niveau du compte, le Service Principal doit être un administrateur de compte.

Incluez le jeton dans l'en-tête d'autorisation avec l'authentification Bearer.

Exemple de requête API REST au niveau du compte​

Cet exemple liste tous les Workspace pour un compte. Remplacer :

  • <oauth-access-token> avec le jeton d'accès OAuth du Service Principal.
  • <account-id> avec votre ID de compte.
Bash
export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://accounts.cloud.databricks.com/api/2.0/accounts/<account-id>/workspaces'

Exemple de requête d'API REST au niveau Workspace​

Cet exemple liste tous les clusters disponibles dans un Workspace. Remplacer :

  • <oauth-access-token> avec le jeton d'accès OAuth du Service Principal.
  • <databricks-instance> avec le nom d'instance du workspace Databricks, par exemple dbc-a1b2345c-d6e7.cloud.databricks.com.
Bash
export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://<workspace-URL>/api/2.0/clusters/list'

Dépanner l'authentification OAuth M2M​

Suivez ces étapes pour résoudre les problèmes les plus courants liés à l'authentification M2M OAuth de Databricks pour les Service Principals.

Vérifications rapides​

Start par vérifier ces problèmes de configuration courants qui entraînent des échecs d'authentification OAuth M2M :

  • Identifiants : DATABRICKS_CLIENT_ID est défini sur l'ID d'application (ID client) du Service Principal, et DATABRICKS_CLIENT_SECRET est défini sur la valeur secrète OAuth, tous deux sans espaces supplémentaires.
  • Hôte : DATABRICKS_HOST pointe vers https://accounts.cloud.databricks.com pour les Opérations de compte ou l'URL du workspace cible, par exemple https://dbc-a1b2345c-d6e7.cloud.databricks.com pour les Opérations de workspace. Ne pas inclure /api.
  • Attribution : Le Service Principal est attribué au Workspace cible.
  • Autorisations : Le service principal dispose des autorisations requises sur la ressource cible.
  • Conflits : aucune variable conflictuelle n'est définie telle que DATABRICKS_TOKEN, DATABRICKS_USERNAME. Exécutez env | grep DATABRICKS et résolvez les conflits.
  • Outils : utilisez l'authentification unifiée et les versions actuelles de la CLI ou du SDK.

401 Non autorisé​

Causes probables et correctifs :

  • Mauvais ID client ou secret : Copiez à nouveau DATABRICKS_CLIENT_ID et DATABRICKS_CLIENT_SECRET. Régénérez le secret en cas de doute.
  • Secret expiré : Créez un nouveau secret si celui actuel est expiré.
  • Émetteur de jeton incorrect : Pour M2M, utilisez l'Endpoint de jeton OAuth Databricks, et non votre Endpoint de jeton IdP ou cloud.
  • Incompatibilité d'hôte : Si vous vous authentifiez pour les APIs de Workspace, DATABRICKS_HOST doit être l'URL du Workspace que vous appelez.

403 Interdit​

Causes probables et correctifs :

  • Autorisations de ressources manquantes : Accordez le Service Principal CAN USE ou CAN MANAGE sur les clusters ou les SQL Warehouses, et les autorisations de niveau objet requises pour les Notebooks, les Jobs ou les objets de données.
  • Aucune affectation de Workspace : attribuez le Service Principal au Workspace dans la console du compte.
  • Accès API administrateur : pour les APIs réservées aux administrateurs, affectez le Service Principal au groupe d'administrateurs du Workspace ou accordez les autorisations d'administrateur de compte.

Problèmes de configuration​

Les symptômes comprennent les timeouts, « hôte introuvable », « compte introuvable » ou « Workspace introuvable ».

Correctifs :

  • Règles d'hôte : Utilisez l'URL de la console de compte pour les APIs de compte. Utilisez l'URL du Workspace pour les APIs du Workspace. N'incluez pas le suffixe /api.
  • ID du compte : Fournissez DATABRICKS_ACCOUNT_ID uniquement pour les opérations au niveau du compte. Utilisez l'UUID à partir de la console du compte.
  • Sélection de profil : Si vous utilisez plusieurs profils, transmettez --profile <name> ou définissez DATABRICKS_CONFIG_PROFILE.

Connectivité​

Si l'authentification OAuth M2M échoue en raison de problèmes réseau, utilisez ces tests pour vérifier que votre environnement peut atteindre les endpoints Databricks :

  • DNS : nslookup <your-host> (doit renvoyer des adresses IP pour le Hostname)
  • TLS et atteignabilité : curl -I https://<your-host> (devrait renvoyer le code de statut HTTP 200, 401 ou 403)
  • **Réseau d'entreprise :** Confirmez que les règles de proxy ou de pare-feu autorisent le HTTPS vers les Endpoint Databricks.

Ressources supplémentaires​

Sur cette page