Partilhar via

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

  • Artigo

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

Para configurar uma conexão do Azure Databricks para o Databricks JDBC Driver, você deve combinar suas configurações de recursos de computação, quaisquer configurações de capacidade de driver e as seguintes configurações de autenticação 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>]
  • Para obter os valores de <server-hostname> e , consulte Configurações de computação para o driver JDBC Databricks<http-path>.
  • Substitua <setting>=<value> , conforme necessário, cada uma das propriedades de conexão, conforme listado nas seções a seguir.
  • Você também pode adicionar configurações de capacidade de driver especiais ou avançadas.

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

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 DATABRICKS_SERVER_HOSTNAME valores e DATABRICKS_HTTP_PATH de ambiente para os valores Nome do Host do Servidor e Caminho HTTP do recurso de computação do Azure Databricks de destino, respectivamente. Para obter esses valores, consulte Configurações de computação para o driver JDBC Databricks. Para definir variáveis de ambiente, consulte a documentação do seu 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 de capacidade de driver especiais ou avançadas, geralmente como adicionais <setting> e <value> pares.
  • Para este exemplo, substitua <query> por uma cadeia de caracteres de consulta SQL SELECT .

Se você usa uma URL de conexão ou uma coleção de propriedades de conexão dependerá dos requisitos do 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 Databricks JDBC Driver 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 seu espaço de trabalho do Azure Databricks, clique no seu nome de utilizador do Azure Databricks na barra superior e, em seguida, selecione Definições na lista pendente.
  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 o ajude 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 Generate (Gerar).
  7. Copie o token exibido para um local seguro e clique em Concluído.

Nota

Certifique-se de salvar o token copiado em um local seguro. Não partilhe o seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente o mesmo token. Em vez disso, você deve repetir esse procedimento para criar um novo token. Se você perder o token copiado ou acreditar que o token foi comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu espaço de trabalho clicando no ícone da lixeira (Revogar) ao lado do token na página de tokens do Access.

Se você não conseguir criar ou usar tokens em seu espaço de trabalho, isso pode ser porque o administrador do espaço de trabalho desabilitou tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do espaço de trabalho ou o seguinte:

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

Para uma URL de conexão JDBC com propriedades de configuração geral incorporadas e propriedades de credenciais 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 geral e propriedades de credenciais 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 que você pode adaptar o trecho de código anterior às suas próprias necessidades, consulte o exemplo de código no início deste artigo.
  • No URL ou código Java anterior, substitua <personal-access-token> pelo token de acesso pessoal Databricks para o usuário do espaço de trabalho.
  • Para obter os valores de <server-hostname> e , consulte Configurações de computação para o driver JDBC Databricks<http-path>.

Token Microsoft Entra ID (anteriormente Azure Ative Directory)

Os drivers ODBC e JDBC 2.6.15 e superiores oferecem suporte a tokens Microsoft Entra ID (anteriormente Azure Ative Directory) para um usuário do Azure Databricks ou uma entidade de serviço 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 Databricks JDBC Driver Guide.

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

Para uma URL de conexão JDBC com propriedades de configuração geral incorporadas e propriedades de credenciais 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 geral e propriedades de credenciais 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 que você pode adaptar o trecho de código anterior às suas próprias necessidades, consulte o exemplo de código no início deste artigo.
  • No URL ou código Java anterior, substitua <microsoft-entra-id-token> pelo token ID do Microsoft Entra.
  • Para obter os valores de <server-hostname> e , consulte Configurações de computação para o driver JDBC Databricks<http-path>.

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

Tokens OAuth 2.0

O driver JDBC 2.6.36 e superior suporta um token OAuth 2.0 para uma entidade de serviço Microsoft Entra ID. Isso também é conhecido como autenticação de passagem de token OAuth 2.0.

  • Para criar um token OAuth 2.0 para autenticação de passagem de token para uma entidade de serviço do Microsoft Entra ID, consulte Gerar e usar manualmente tokens de acesso para autenticação OAuth M2M. Anote o valor OAuth access_token da entidade de serviço.

  • Para criar uma entidade de serviço gerenciada do Microsoft Entra ID, consulte Gerenciar entidades de serviço.

    Importante

    O driver JDBC 2.6.36 e superior oferece suporte ao uso de segredos OAuth do Azure Databricks para criar tokens OAuth 2.0. Os segredos de ID do Microsoft Entra não são suportados.

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 este processo.

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

Para uma URL de conexão JDBC com propriedades de configuração geral incorporadas e propriedades de credenciais 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 geral e propriedades de credenciais 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 que você pode adaptar o trecho de código anterior às suas próprias necessidades, consulte o exemplo de código no início deste artigo.
  • Na URL ou código Java anterior, substitua <oauth-token> pelo token OAuth do Azure Databricks. (Os tokens de ID do Microsoft Entra não são suportados para autenticação de passagem de token OAuth 2.0.)
  • Para obter os valores de <server-hostname> e , consulte Configurações de computação para o driver JDBC Databricks<http-path>.

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

Autenticação OAuth user-to-machine (U2M)

O driver JDBC 2.6.36 e superior oferece suporte à autenticação U2M (usuário para máquina) 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 os tokens OAuth 2.0 expirados para você automaticamente.

Nota

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 em nuvem.

Para autenticar usando a autenticação OAuth user-to-machine (U2M) ou OAuth 2.0 baseada em navegador, defina a seguinte configuração.

Para uma URL de conexão JDBC com propriedades de configuração geral incorporadas e propriedades de credenciais 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 geral e propriedades de credenciais 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 que você pode adaptar o trecho de código anterior às suas próprias necessidades, consulte o exemplo de código no início deste artigo.
  • No URL ou código Java anterior, 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 , consulte Configurações de computação para o driver JDBC Databricks<http-path>.

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

Autenticação OAuth máquina-a-máquina (M2M)

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

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

  1. Crie uma entidade de serviço gerenciado do Microsoft Entra ID e atribua-a a contas e espaços de trabalho do Azure Databricks. Para fazer isso, consulte Gerenciar entidades de serviço.

    Importante

    O driver JDBC 2.6.36 e superior oferece suporte aos segredos OAuth do Azure Databricks para autenticação de credenciais de cliente OAuth M2M ou OAuth 2.0. Os segredos de ID do Microsoft Entra não são suportados.

  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. Dê à entidade de serviço acesso ao seu cluster ou depósito. Consulte Permissões de computação ou Gerenciar um armazém SQL.

Para autenticar usando a autenticação de credenciais de cliente OAuth máquina-a-máquina (M2M) ou OAuth 2.0, defina a seguinte configuração.

Para uma URL de conexão JDBC com propriedades de configuração geral incorporadas e propriedades de credenciais 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 geral e propriedades de credenciais 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 que você pode adaptar o trecho de código anterior às suas próprias necessidades, consulte o exemplo de código no início deste artigo.
  • No URL ou código Java anterior, substitua os seguintes espaços reservados:
    • Substitua <service-principal-application-id> pelo valor de ID do aplicativo (cliente) da entidade de serviço.
    • Substitua <service-principal-oauth-secret> pelo segredo OAuth do Azure Databricks da entidade de serviço. (Os segredos de ID do Microsoft Entra não são suportados para autenticação de credenciais de cliente OAuth M2M ou OAuth 2.0.)
    • Para obter os valores de <server-hostname> e , consulte Configurações de computação para o driver JDBC Databricks<http-path>.

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