Partager via

Paramètres d’authentification pour le pilote JDBC Databricks

  • Article

Cet article vous explique comment configurer les paramètres d’authentification Azure Databricks pour le pilote JDBC Databricks.

Pour configurer une connexion Azure Databricks pour le pilote JDBC Databricks, vous devez combiner vos paramètres de ressource de calcul, les paramètres de capacité du pilote et les paramètres d’authentification suivants dans une URL de connexion JDBC ou une collection programmatique des propriétés de connexion JDBC.

Les URL de connexion JDBC utilisent le format suivant :

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>[;<setting1>=<value1>;<setting2>=<value2>;<settingN>=<valueN>]

Vous pouvez utiliser des collections programmatiques de propriétés de connexion JDBC dans du code Java comme dans l’exemple suivant :

package org.example;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class Main {
  public static void main(String[] args) throws Exception {
    Class.forName("com.databricks.client.jdbc.Driver");
    String url = "jdbc:databricks://" + System.getenv("DATABRICKS_SERVER_HOSTNAME") + ":443";
    Properties p = new java.util.Properties();
    p.put("httpPath", System.getenv("DATABRICKS_HTTP_PATH"));
    p.put("<setting1>", "<value1");
    p.put("<setting2>", "<value2");
    p.put("<settingN>", "<valueN");
    try (Connection conn = DriverManager.getConnection(url, p)) {
      Statement stmt = conn.createStatement();
      try (ResultSet rs = stmt.executeQuery("<query>")) {
        ResultSetMetaData md = rs.getMetaData();
        String[] columns = new String[md.getColumnCount()];
        for (int i = 0; i < columns.length; i++) {
          columns[i] = md.getColumnName(i + 1);
        }
        while (rs.next()) {
          System.out.print("Row " + rs.getRow() + "=[");
          for (int i = 0; i < columns.length; i++) {
            if (i != 0) {
              System.out.print(", ");
            }
            System.out.print(columns[i] + "='" + rs.getObject(i + 1) + "'");
          }
          System.out.println(")]");
        }
      }
    }
    System.exit(0);
  }
}
  • Définissez les valeurs d’environnement DATABRICKS_SERVER_HOSTNAME et DATABRICKS_HTTP_PATH sur les valeurs Nom d’hôte du serveur et Chemin d’accès HTTP de la ressource de calcul Azure Databricks cible, respectivement. Pour obtenir ces valeurs, consultez Paramètres de calcul pour le pilote JDBC Databricks. Pour définir des variables d’environnement, consultez la documentation de votre système d’exploitation.
  • Remplacez <setting> et <value> si nécessaire pour chacune des propriétés de connexion, comme indiqué dans les sections suivantes.
  • Vous pouvez également ajouter des paramètres de capacité du pilote avancés ou spéciaux, généralement en tant que paires <setting> et <value> supplémentaires.
  • Pour cet exemple, remplacez <query> par une chaîne de requête SELECT SQL.

L’utilisation d’une URL de connexion ou d’une collection de propriétés de connexion dépend des exigences de votre API, Kit de développement logiciel (SDK), client, outil ou application cible. Des exemples d’URL de connexion JDBC et de collections programmatiques de propriétés de connexion JDBC sont fournis dans cet article pour chaque type d’authentification Azure Databricks pris en charge.

Le pilote JDBC Databricks prend en charge les types d’authentification Azure Databricks suivants :

Jeton d’accès personnel Azure Databricks

Pour créer un jeton d’accès personnel Azure Databricks, effectuez la procédure suivante :

  1. Dans votre espace de travail Azure Databricks, cliquez sur votre nom d’utilisateur Azure Databricks dans la barre du haut, puis sélectionnez Paramètres dans la liste déroulante.
  2. Cliquez sur Développeur.
  3. À côté de Jetons d’accès, cliquez sur Gérer.
  4. Cliquez sur Générer un nouveau jeton.
  5. (Facultatif) Entrez un commentaire qui vous aide à identifier ce jeton à l’avenir et modifiez sa durée de vie par défaut (90 jours). Pour créer un jeton sans durée de vie (non recommandé), laissez vide la zone Durée de vie (en jours).
  6. Cliquez sur Générer.
  7. Copiez le jeton affiché dans un emplacement sécurisé, puis cliquez sur Terminé.

Remarque

Veillez à enregistrer le jeton copié dans un emplacement sécurisé. Ne partagez pas votre jeton copié avec d'autres. Si vous le perdez, vous ne pouvez pas régénérer exactement le même. Vous devez donc répéter cette procédure pour créer un jeton. Si vous perdez le jeton copié ou si vous pensez que le jeton a été compromis, Databricks vous recommande vivement de supprimer immédiatement ce jeton de votre espace de travail en cliquant sur l’icône de la corbeille (Révoquer) à côté du jeton de la page Jetons d’accès.

Si vous n'êtes pas en mesure de créer ou d'utiliser des jetons dans votre espace de travail, cela peut être dû au fait que votre administrateur d'espace de travail a désactivé les jetons ou ne vous a pas donné l'autorisation de créer ou d'utiliser des jetons. Consultez votre administrateur d'espace de travail ou les personnes suivantes :

Pour vous authentifier en utilisant un jeton d’accès personnel Azure Databricks, définissez la configuration suivante.

Pour une URL de connexion JDBC avec des propriétés de configuration générales incorporées et des propriétés d’informations d’identification sensibles :

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=3;UID=token;PWD=<personal-access-token>

Pour le code Java avec des propriétés de configuration générales et des propriétés d’informations d’identification sensibles définies en dehors de l’URL de connexion JDBC :

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "3");
p.put("UID", "token");
p.put("PWD", "<personal-access-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...
  • Pour obtenir un exemple complet de code Java dans lequel vous pouvez adapter l’extrait de code précédent en fonction de vos propres besoins, consultez l’exemple de code au début de cet article.
  • Dans le code Java ou l’URL précédent, remplacez <personal-access-token> par le jeton d’accès personnel Databricks pour l’utilisateur de votre espace de travail.
  • Pour obtenir les valeurs de <server-hostname> et de <http-path>, consultez Paramètres de calcul pour le pilote JDBC Databricks.

Jeton Microsoft Entra ID (anciennement Azure Active Directory)

Les pilotes ODBC et JDBC 2.6.15 et versions ultérieures prennent en charge les jetons Microsoft Entra ID (anciennement Azure Active Directory) pour un utilisateur Azure Databricks ou un principal de service Microsoft Entra ID.

Pour créer un jeton d’accès Microsoft Entra ID, effectuez ce qui suit :

Les jetons d’accès Microsoft Entra ID ont une durée de vie par défaut d’une heure. Vous pouvez actualiser un jeton d’accès par programmation pour une session existante sans rompre la connexion en exécutant le code dans Actualiser un jeton d’accès Microsoft Entra ID. Si vous souhaitez obtenir des instructions sur l’actualisation du jeton, consultez la section Configuring Authentication > Using OAuth 2.0 dans le Guide du pilote JDBC Databricks.

Pour vous authentifier en utilisant un jeton Microsoft Entra ID, définissez la configuration suivante.

Pour une URL de connexion JDBC avec des propriétés de configuration générales incorporées et des propriétés d’informations d’identification sensibles :

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=<microsoft-entra-id-token>

Pour le code Java avec des propriétés de configuration générales et des propriétés d’informations d’identification sensibles définies en dehors de l’URL de connexion JDBC :

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "0");
p.put("Auth_AccessToken", "<microsoft-entra-id-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...
  • Pour obtenir un exemple complet de code Java dans lequel vous pouvez adapter l’extrait de code précédent en fonction de vos propres besoins, consultez l’exemple de code au début de cet article.
  • Dans le code Java ou l’URL précédent, remplacez <microsoft-entra-id-token> par le jeton Microsoft Entra ID.
  • Pour obtenir les valeurs de <server-hostname> et de <http-path>, consultez Paramètres de calcul pour le pilote JDBC Databricks.

Si vous souhaitez obtenir plus d’informations, consultez la section Token Pass-through dans le Guide du pilote JDBC Databricks.

Jetons OAuth 2.0

Le pilote JDBC 2.6.36 et versions ultérieures prennent en charge un jeton OAuth 2.0 pour un principal de service Microsoft Entra ID. Cette opération est également appelée authentification directe de jeton OAuth 2.0.

  • Pour créer un jeton OAuth 2.0 pour l’authentification directe par jeton pour un principal de service Microsoft Entra ID, consultez Générer et utiliser manuellement des jetons d’accès pour l’authentification M2M OAuth. Prenez note de la valeur OAuth access_token du principal du service.

  • Pour créer un principal de service géré par Microsoft Entra ID, consultez Gérer les principaux de service.

    Important

    Le pilote JDBC 2.6.36 et versions ultérieures prennent en charge l’utilisation de secrets OAuth Azure Databricks pour créer des jetons OAuth 2.0. Les secrets Microsoft Entra ID ne sont pas pris en charge.

Les jetons OAuth 2.0 ont une durée de vie par défaut de 1 heure. Pour générer un token OAuth 2.0, répétez ce processus.

Pour vous authentifier en utilisant une authentification directe de jeton OAuth 2.0, définissez la configuration suivante.

Pour une URL de connexion JDBC avec des propriétés de configuration générales incorporées et des propriétés d’informations d’identification sensibles :

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=<oauth-token>

Pour le code Java avec des propriétés de configuration générales et des propriétés d’informations d’identification sensibles définies en dehors de l’URL de connexion JDBC :

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "0");
p.put("Auth_AccessToken", "<oauth-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...
  • Pour obtenir un exemple complet de code Java dans lequel vous pouvez adapter l’extrait de code précédent en fonction de vos propres besoins, consultez l’exemple de code au début de cet article.
  • Dans le code Java ou l’URL précédent, remplacez <oauth-token> par le jeton OAuth Azure Databricks. (Les jetons Microsoft Entra ID ne sont pas pris en charge pour l’authentification directe de jeton OAuth 2.0.)
  • Pour obtenir les valeurs de <server-hostname> et de <http-path>, consultez Paramètres de calcul pour le pilote JDBC Databricks.

Si vous souhaitez obtenir plus d’informations, consultez la section Token Pass-through dans le Guide du pilote JDBC Databricks.

Authentification utilisateur à machine (U2M) OAuth

Le pilote JDBC 2.6.36 et versions ultérieures prennent en charge l’authentification utilisateur à machine (U2M) OAuth pour un utilisateur Azure Databricks. Elle est également appelée authentification basée sur un navigateur OAuth 2.0.

L’authentification basée sur un navigateur OAuth U2M ou OAuth 2.0 a des prérequis. Les jetons OAuth 2.0 ont une durée de vie par défaut de 1 heure. L’authentification basée sur un navigateur OAuth U2M ou OAuth 2.0 doit automatiquement actualiser des jetons OAuth 2.0 expirés pour vous.

Remarque

L’authentification basée sur un navigateur OAuth U2M ou OAuth 2.0 fonctionne uniquement avec des applications s’exécutant localement. Elle ne fonctionne pas avec des applications basées sur un cloud ou sur un serveur.

Pour vous authentifier en utilisant une authentification basée sur un navigateur OAuth utilisateur à machine (U2M) ou OAuth 2.0, définissez la configuration suivante.

Pour une URL de connexion JDBC avec des propriétés de configuration générales incorporées et des propriétés d’informations d’identification sensibles :

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=2;TokenCachePassPhrase=<passphrase>;EnableTokenCache=0

Pour le code Java avec des propriétés de configuration générales et des propriétés d’informations d’identification sensibles définies en dehors de l’URL de connexion JDBC :

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "2")
p.put("TokenCachePassPhrase", "<passphrase>");
p.put("EnableTokenCache", "0");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...
  • Pour obtenir un exemple complet de code Java dans lequel vous pouvez adapter l’extrait de code précédent en fonction de vos propres besoins, consultez l’exemple de code au début de cet article.
  • Dans le code Java ou l’URL précédent, remplacez <passphrase> par une phrase secrète de votre choix. Le pilote utilise cette clé pour le chiffrement du jeton d’actualisation.
  • Pour obtenir les valeurs de <server-hostname> et de <http-path>, consultez Paramètres de calcul pour le pilote JDBC Databricks.

Si vous souhaitez obtenir plus d’informations, consultez la section Using Browser Based Authentication dans le Guide du pilote JDBC Databricks.

Authentification OAuth machine à machine (M2M)

Le pilote JDBC 2.6.36 et versions ultérieures prennent en charge l’authentification machine à machine (M2M) OAuth pour un principal de service Microsoft Entra ID. Elle est également appelée authentification des informations d’identification du client OAuth 2.0.

Pour configurer l’authentification des informations d’identification du client OAuth M2M ou OAuth 2.0, effectuez ces étapes :

  1. Créez un principal de service géré Microsoft Entra ID, puis affectez-le aux comptes et aux espaces de travail Azure Databricks. Pour cela, consultez Gérer les principaux de service.

    Important

    Le pilote JDBC 2.6.36 et versions ultérieures prennent en charge des secrets OAuth Azure Databricks pour l’authentification des informations d’identification du client OAuth 2.0 ou OAuth M2M. Les secrets Microsoft Entra ID ne sont pas pris en charge.

  2. Créez un secret OAuth Azure Databricks pour le principal de service. Pour cela, consultez Générer et utiliser manuellement des jetons d’accès pour l’authentification M2M OAuth.

  3. Accordez au principal de service l’accès à votre cluster ou entrepôt. Consultez Autorisations de calcul ou Gérer un entrepôt SQL.

Pour vous authentifier en utilisant une authentification des informations d’identification du client OAuth machine à machine (M2M) ou OAuth 2.0, définissez la configuration suivante.

Pour une URL de connexion JDBC avec des propriétés de configuration générales incorporées et des propriétés d’informations d’identification sensibles :

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=1;OAuth2ClientId=<service-principal-application-id>;OAuth2Secret=<service-principal-oauth-secret>

Pour le code Java avec des propriétés de configuration générales et des propriétés d’informations d’identification sensibles définies en dehors de l’URL de connexion JDBC :

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "1");
p.put("OAuth2ClientId", "<service-principal-application-id>");
p.put("OAuth2Secret", "<service-principal-oauth-secret>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...
  • Pour obtenir un exemple complet de code Java dans lequel vous pouvez adapter l’extrait de code précédent en fonction de vos propres besoins, consultez l’exemple de code au début de cet article.
  • Dans le code Java ou l’URL précédent, remplacez les espaces réservés suivants :
    • Remplacez <service-principal-application-id> par la valeur ID d’application (client) du principal de service.
    • Remplacez <service-principal-oauth-secret> par le secret OAuth Azure Databricks du principal de service. (Les secrets Microsoft Entra ID ne sont pas pris en charge pour l’authentification des informations d’identification de client OAuth M2M ou OAuth 2.0.)
    • Pour obtenir les valeurs de <server-hostname> et de <http-path>, consultez Paramètres de calcul pour le pilote JDBC Databricks.

Si vous souhaitez obtenir plus d’informations, consultez la section Using M2M Based Authentication dans le Guide du pilote JDBC Databricks.