Aller au contenu principal
Dernière mise à jour le

Connectez-vous à une application Databricks API à l'aide de l'authentification par jeton

Vous pouvez appeler une application Databricks qui expose une API HTTP (par exemple, une application FastAPI ou Gradio) à l'aide de l'authentification par jeton Bearer OAuth 2.0. Cette méthode fonctionne depuis votre environnement de développement local, des applications externes et d'autres applications Databricks.

remarque

Cette méthode s'applique uniquement aux applications qui exposent des APIs ou des Endpoints (accessibles à l'aide de /api/ routes). Pour les applications qui ne fournissent qu'une interface utilisateur ou un traitement en arrière-plan, vous ne pouvez pas vous connecter à l'aide de l'authentification par jeton.

Exigences​

Pour vous connecter à une application Databricks à l'aide de l'authentification par jeton, vous devez remplir les conditions suivantes :

  • L'application doit exposer au moins un Endpoint API accessible via /api/ routes.
  • Vous devez disposer de l'autorisation CAN USE sur l'application. Voir Configurer les autorisations d'une application Databricks.
  • Vous devez pouvoir générer un jeton d'accès Databricks à l’aide de l'une des méthodes d'authentification prises en charge.

Méthodes d'authentification​

Choisissez la méthode d'authentification qui correspond à votre scénario de connexion :

Développement local​

Pour vous connecter depuis votre environnement de développement local, utilisez la CLI Databricks ou les SDK avec vos identifiants utilisateur.

  1. Connexion avec la CLI :

    Bash
    databricks auth login --host https://<workspace-url> --profile my-env

    Databricks recommande d'utiliser l'authentification OAuth utilisateur-machine (U2M).

  2. Générer un jeton d'accès :

Bash
databricks auth token --profile my-env

Applications externes​

Pour un accès programmatique depuis des applications externes, utilisez l'authentification de service principal avec des identifiants machine-to-machine (M2M). Consultez Autoriser l'accès de service principal à Databricks avec OAuth.

  1. Créez un Service Principal et obtenez l'ID client et le secret. See Service Principal.

  2. Générer un jeton d'accès à l'aide du SDK Databricks :

    Python
    from databricks.sdk import WorkspaceClient
    import requests

    # Option 1: Explicit credentials
    wc = WorkspaceClient(
        host="https://<workspace-url>",
        client_id="<service-principal-client-id>",
        client_secret="<service-principal-client-secret>"
    )

    # Option 2: Environment variables
    # Set DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET
    wc = WorkspaceClient()

    # Generate Bearer token
    headers = wc.config.authenticate()

Depuis d'autres applications Databricks​

Lorsque vous vous connectez d'une application Databricks à une autre, l'application gère automatiquement l'authentification à l'aide de son Service Principal attribué.

Python
from databricks.sdk import WorkspaceClient
import requests

# No explicit credentials needed, uses app's service principal
wc = WorkspaceClient()
headers = wc.config.authenticate()

À partir d'un Notebook Databricks​

Pour appeler une API d'application à partir d'un Notebook Databricks, vous devez échanger le jeton interne du Notebook contre un jeton OAuth à portée d'audience, puis utiliser ce jeton pour query l'application.

  1. Obtenez l'ID client de l'application OAuth. Récupérez l'ID à l'aide du Databricks SDK :

    Python
    from databricks.sdk import WorkspaceClient

    w = WorkspaceClient()
    app_client_id = w.apps.get("<app-name>").oauth2_app_client_id

  2. Échangez le jeton Notebook contre un jeton d’accès à l’étendue d’un public :

    Python
    import requests

    url = "https://<workspace-url>/oidc/v1/token"
    notebook_token = (
        dbutils.notebook.entry_point.getDbutils()
        .notebook().getContext().apiToken().get()
    )

    data = {
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "subject_token": notebook_token,
        "subject_token_type": "urn:databricks:params:oauth:token-type:personal-access-token",
        "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
        "scope": "all-apis",
        "audience": app_client_id,
    }

    response = requests.post(url=url, data=data)
    audience_token = response.json()["access_token"]

  3. Utilisez le audience_token comme jeton porteur pour appeler votre application. Pour des exemples, consultez Envoyer des requêtes à l'application.

remarque

Le jeton échangé est limité à l'application spécifique, vous ne pouvez donc pas l'utiliser pour appeler d'autres API Databricks. Le paramètre scope de la requête d'échange de jeton doit correspondre ou être un sur-ensemble des périmètres configurés pour l'application dans l'autorisation utilisateur.

Spécifiez les périmètres OAuth pour l'autorisation de l'utilisateur​

Si votre application utilise l'autorisation de l'utilisateur, votre jeton d'accès doit inclure des étendues qui sont un sur-ensemble des étendues configurées pour l'application. Si le jeton n'a pas les étendues requises, les requêtes peuvent échouer avec des erreurs 401 ou 403.

Un jeton généré à l’aide de l’interface CLI Databricks inclut le périmètre all-apis par default, ce qui satisfait les exigences d’autorisation utilisateur pour toute application :

Bash
databricks auth token --profile my-env

Pour demander des champs d'application spécifiques au lieu de all-apis, vous pouvez demander manuellement un jeton d'accès avec des champs d'application explicites à l'aide d'un flux OAuth personnalisé. Par exemple, la requête suivante demande explicitement un jeton d'accès avec les champs d'application sql, files et genie :

Bash
curl --request POST \
https://<databricks-instance>/oidc/v1/token \
--data "client_id=databricks-cli" \
--data "grant_type=authorization_code" \
--data "redirect_uri=<redirect-url>" \
--data "code_verifier=<code-verifier>" \
--data "code=<authorization-code>" \
--data "scope=sql+files+genie"

Pour obtenir des instructions complètes, consultez Générer manuellement des jetons d'accès OAuth U2M.

Envoyer des requêtes à l'application​

Lorsque vous appelez les Endpoint API de votre application, incluez le jeton Bearer dans l'en-tête Authorization et remplacez <your-endpoint> par le chemin d'API réel de votre application :

Bash
curl "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>" \
     -H "Authorization: Bearer <YOUR_TOKEN>"

Considérations de sécurité​

Lorsque vous vous connectez à des applications depuis votre environnement local, suivez ces bonnes pratiques de sécurité :

  • Ne jamais coder en dur les jetons d'accès dans votre code source. Utilisez des variables d'environnement ou des magasins d'informations d'identification sécurisés.
  • refresh les tokens régulièrement afin de minimiser les risques de sécurité s'ils sont compromis.
  • Évitez de journaliser les jetons d'accès ou les données sensibles dans les logs de votre application.

Dépannage​

Si vous rencontrez des problèmes lors de la connexion à votre application depuis une machine locale, essayez ces solutions.

Échecs d'authentification (erreurs 401)​

Vérifier ce qui suit :

  • Votre jeton est valide (exécution databricks auth token --profile my-env)
  • Votre profil est correctement configuré avec databricks auth login
  • Le jeton n'a pas expiré.
  • Votre jeton inclut les portées OAuth requises. Les portées de votre jeton doivent être un surensemble des portées configurées pour l'application dans l'autorisation utilisateur.

Autorisation refusée (erreurs 403)​

Vérifier ce qui suit :

  • Vous avez CAN USE autorisation sur l'application
  • Votre jeton inclut les portées OAuth requises. Des portées insuffisantes peuvent provoquer des erreurs 403 même avec des autorisations valides.

Application introuvable (erreurs 404)​

Vérifier ce qui suit :

  • L'ID et l'URL du workspace sont corrects
  • L'application est déployée et en cours d'exécution.
  • Le chemin de l'endpoint existe dans l'application.

Problèmes de connectivité réseau​

Vérifier ce qui suit :

  • Votre réseau autorise les connexions HTTPS sortantes
  • Le domaine *.databricksapps.com est accessible depuis votre réseau

De plus, vérifiez si votre organisation utilise un proxy qui nécessite une configuration.

Ressources supplémentaires​

Pour plus d'informations, consultez les Ressources suivantes :

Sur cette page