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, faça o seguinte:

  1. No workspace do Azure Databricks, clique no nome de usuário do Azure Databricks na barra superior e selecione Configurações na lista suspensa.
  2. Clique em Desenvolvedor.
  3. Ao lado de Tokens de acesso, clique em Gerenciar.
  4. Clique em Gerar novo token.
  5. (Opcional) Insira um comentário que ajude você a identificar esse token no futuro e altere o tempo de vida padrão do token de 90 dias. Para criar um token sem tempo de vida (não recomendado), deixe a caixa Tempo de vida (dias) vazia (em branco).
  6. Clique em Gerar.
  7. Copie o token exibido para um local seguro e clique em Concluído.

Observação

Lembre-se de salvar o token copiado em um local seguro. Não compartilhe seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente aquele mesmo token. Em vez disso, será necessário repetir esse procedimento para criar um novo token. Caso você tenha perdido o token copiado ou acredite que ele tenha sido comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu workspace clicando no ícone de lixeira (Revogar) ao lado do token na página de Tokens de acesso.

Se você não conseguir criar ou usar tokens em seu workspace, isso pode ocorrer porque o administrador do workspace desabilitou tokens ou não deu permissão para criar ou usar tokens. Veja o administrador do workspace ou o seguinte:

Para autenticar usando um token de acesso pessoal do Azure Databricks, 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=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 (antigo Azure Active Directory)

Os drivers ODBC e JDBC 2.6.15 e posteriores dão suporte a tokens do Microsoft Entra ID (antigo Azure Active Directory) 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.

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.

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, confira Gerar e usar manualmente tokens de acesso para autenticação OAuth máquina-a-máquina (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.