Compartilhar via

Configurações de autenticação para o Driver JDBC do Databricks

  • Artigo

Este artigo descreve como definir as configurações de autenticação do Azure Databricks para o Driver JDBC do Databricks.

Para configurar uma conexão do Azure Databricks para o Driver ODBC do Databricks, você precisa combinar suas configurações de recursos de computação, quaisquer configurações de funcionalidade de driver e as configurações de autenticação a seguir em uma URL de conexão JDBC ou coleção programática de propriedades de conexão JDBC.

As URLs de conexão JDBC usam o seguinte formato:

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

Coleções programáticas de propriedades de conexão JDBC podem ser usadas no código Java, como o seguinte exemplo:

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);
  }
}
  • Defina os valores de ambiente de DATABRICKS_SERVER_HOSTNAME e DATABRICKS_HTTP_PATH para os valores de Nome do host do servidor e Caminho HTTP do recurso de computação do Azure Databricks, respectivamente. Para obter esses valores, consulte Configurações de computação para o Driver JDBC do Databricks. Para definir variáveis de ambiente, confira a documentação do sistema operacional.
  • Substitua <setting> e <value>, conforme necessário, para cada uma das propriedades de conexão, conforme listado nas seções a seguir.
  • Você também pode adicionar configurações especiais ou avançadas de funcionalidade do driver, normalmente como pares <setting> e <value> adicionais.
  • Para este exemplo, substitua <query> por uma cadeia de caracteres de consulta SELECT do SQL.

Se você usará uma URL de conexão ou então uma coleção de propriedades de conexão é algo que dependerá dos requisitos de seu aplicativo, ferramenta, cliente, SDK ou API de destino. Exemplos de URLs de conexão JDBC e coleções programáticas de propriedades de conexão JDBC são fornecidos neste artigo para cada tipo de autenticação do Azure Databricks com suporte.

O Driver JDBC do Databricks dá suporte aos seguintes tipos de autenticação do Azure Databricks:

Token de acesso pessoal do Azure Databricks

Para criar um token de acesso pessoal do Azure Databricks, siga as etapas em Tokens de acesso pessoal do Azure Databricks para usuários do workspace.

Para autenticar usando um token de acesso pessoal do Azure Databricks, defina a configuração a seguir.

Para configurar uma URL de conexão JDBC com propriedades de configuração geral incorporadas e propriedades de credenciais confidenciais, usando seu PAT:

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

Para código Java com propriedades de configuração gerais e propriedades de credencial confidenciais definidas fora da URL de conexão 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);
// ...
  • Para obter um exemplo de código Java completo em que você pode adaptar o snippet de código anterior às suas necessidades, consulte o exemplo de código no início deste artigo.
  • Na URL anterior ou no código Java, substitua <personal-access-token> pelo token de acesso pessoal do Databricks para o usuário do workspace.
  • Para obter os valores de <server-hostname> e <http-path>, consulte Configurações de computação para o Driver JDBC do Databricks.

Token do Microsoft Entra ID

Os drivers ODBC e JDBC 2.6.15 e posteriores dão suporte a tokens do Microsoft Entra ID para um usuário do Azure Databricks ou uma entidade de serviço do Microsoft Entra ID.

Para criar um token de acesso do Microsoft Entra ID, faça o seguinte:

Os tokens de acesso do Microsoft Entra ID têm um tempo de vida padrão de cerca de 1 hora. Um token de acesso pode ser atualizado programaticamente para uma sessão existente sem interromper a conexão executando o código em Atualizar um token de acesso do Microsoft Entra ID. Para obter instruções sobre como atualizar o token, consulte a seção Configuring Authentication > Using OAuth 2.0 no Guia do driver JDBC do Databricks.

Para autenticar usando um token do Microsoft Entra ID, defina a configuração a seguir.

Para uma URL de conexão JDBC com propriedades de configuração geral inseridas e propriedades de credencial confidenciais:

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

Para código Java com propriedades de configuração gerais e propriedades de credencial confidenciais definidas fora da URL de conexão 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);
// ...
  • Para obter um exemplo de código Java completo em que você pode adaptar o snippet de código anterior às suas necessidades, consulte o exemplo de código no início deste artigo.
  • Na URL anterior ou no código Java, substitua <microsoft-entra-id-token> pelo token do Microsoft Entra ID.
  • Para obter os valores de <server-hostname> e <http-path>, consulte Configurações de computação para o Driver JDBC do Databricks.

Para obter mais informações, consulte a seção Token Pass-through no Guia do driver JDBC do Databricks.

Tokens OAuth 2.0

O driver JDBC 2.6.36 e posterior dá suporte a um token OAuth 2.0 para uma entidade de serviço do Microsoft Entra ID. Isso também é conhecido como autenticação de passagem do OAuth 2.0.

Importante

O driver JDBC 2.6.36 e posterior dão suporte ao uso de segredos do Azure Databricks OAuth para criar tokens OAuth 2.0. Não há suporte para segredos do Microsoft Entra ID.

Os tokens OAuth 2.0 têm um tempo de vida padrão de 1 hora. Para gerar um novo token OAuth 2.0, repita esse processo.

Para autenticar usando a autenticação de passagem de token OAuth 2.0, defina a configuração a seguir.

Para uma URL de conexão JDBC com propriedades de configuração geral inseridas e propriedades de credencial confidenciais:

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

Para código Java com propriedades de configuração gerais e propriedades de credencial confidenciais definidas fora da URL de conexão 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);
// ...
  • Para obter um exemplo de código Java completo em que você pode adaptar o snippet de código anterior às suas necessidades, consulte o exemplo de código no início deste artigo.
  • Na URL anterior ou no código Java, substitua <oauth-token> pelo token OAuth do Azure Databricks. (Não há suporte para tokens do Microsoft Entra ID autenticação de passagem de token do OAuth 2.0).
  • Para obter os valores de <server-hostname> e <http-path>, consulte Configurações de computação para o Driver JDBC do Databricks.

Para obter mais informações, consulte a seção Token Pass-through no Guia do driver JDBC do Databricks.

Autenticação U2M (usuário para computador) do OAuth

O driver JDBC 2.6.36 e posterior dá suporte à autenticação U2M (usuário para máquina) do OAuth para um usuário do Azure Databricks. Isso também é conhecido como autenticação baseada em navegador OAuth 2.0.

A autenticação baseada em navegador OAuth U2M ou OAuth 2.0 não tem pré-requisitos. Os tokens OAuth 2.0 têm um tempo de vida padrão de 1 hora. A autenticação baseada em navegador OAuth U2M ou OAuth 2.0 deve atualizar tokens OAuth 2.0 expirados automaticamente para você.

Observação

A autenticação baseada em navegador OAuth U2M ou OAuth 2.0 funciona apenas com aplicativos executados localmente. Ele não funciona com aplicativos baseados em servidor ou na nuvem.

Para autenticar usando u2M (usuário para máquina) do OAuth ou autenticação baseada em navegador OAuth 2.0, defina a configuração a seguir.

Para uma URL de conexão JDBC com propriedades de configuração geral inseridas e propriedades de credencial confidenciais:

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

Para código Java com propriedades de configuração gerais e propriedades de credencial confidenciais definidas fora da URL de conexão 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);
// ...
  • Para obter um exemplo de código Java completo em que você pode adaptar o snippet de código anterior às suas necessidades, consulte o exemplo de código no início deste artigo.
  • Na URL anterior ou no código Java, substitua <passphrase> por uma frase secreta de sua escolha. O driver usa essa chave para atualizar a criptografia de token.
  • Para obter os valores de <server-hostname> e <http-path>, consulte Configurações de computação para o Driver JDBC do Databricks.

Para obter mais informações, consulte a seção Using Browser Based Authentication no Guia do driver JDBC do Databricks.

Autenticação M2M (de computador para computador) do OAuth

O driver JDBC 2.6.36 e posterior dá suporte à autenticação M2M (máquina a máquina) do OAuth para uma entidade de serviço do Microsoft Entra ID. Isso também é conhecido como autenticação de credenciais de cliente OAuth 2.0.

Observação

O JDBC 2.6.40.1071 resolve o problema em versões mais antigas em que a conexão usando M2M para áreas de trabalho de link privado não era suportada.

Para configurar a autenticação de credenciais do cliente OAuth M2M ou OAuth 2.0, faça o seguinte:

  1. Crie uma entidade de serviço gerenciada do Microsoft Entra ID e, em seguida, atribua-a a contas e Workspaces do Azure Databricks. Para fazer isso, confira Gerenciar entidades de serviço.

    Importante

    O driver ODBC 2.6.36 e posterior dão suporte aos segredos do OAuth do Azure Databricks para autenticação OAuth M2M ou de credenciais de cliente OAuth 2.0. Não há suporte para segredos do Microsoft Entra ID.

  2. Crie um segredo OAuth do Azure Databricks para a entidade de serviço. Para fazer isso, consulte Gerar e usar manualmente tokens de acesso para autenticação OAuth M2M.

  3. Conceda à entidade de serviço acesso ao cluster ou ao warehouse. Consulte Permissões de computação ou Gerenciar um SQL warehouse.

Para autenticar usando a autenticação de credenciais de cliente OAuth de computador para computador (M2M) ou OAuth 2.0, defina a configuração a seguir.

Para uma URL de conexão JDBC com propriedades de configuração geral inseridas e propriedades de credencial confidenciais:

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

Para código Java com propriedades de configuração gerais e propriedades de credencial confidenciais definidas fora da URL de conexão 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);
// ...
  • Para obter um exemplo de código Java completo em que você pode adaptar o snippet de código anterior às suas necessidades, consulte o exemplo de código no início deste artigo.
  • Na URL anterior ou no código Java, substitua os seguintes espaços reservados:
    • Substitua <service-principal-application-id> pelo valor da ID do aplicativo (cliente) da entidade de serviço.
    • Substitua <service-principal-oauth-secret> pelo segredo do OAuth do Azure Databricks da entidade de serviço. (Não há suporte para segredos do Microsoft Entra ID para autenticação de credenciais de cliente OAuth M2M ou OAuth 2.0).
    • Para obter os valores de <server-hostname> e <http-path>, consulte Configurações de computação para o Driver JDBC do Databricks.

Para obter mais informações, consulte a seção Using M2M Based Authentication no Guia do driver JDBC do Databricks.