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

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

Para configurar uma conexão do Databricks para o driver JDBC do Databricks, você deve combinar as configurações de recursos compute , quaisquer configurações de capacidade do driver e as configurações de autenticação a seguir em uma URL de conexão JDBC ou uma coleção programática de propriedades de conexão JDBC.

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 <http-path>, consulte Configurações de computação para o driver JDBC do Databricks.

• Substitua <setting>=<value> conforme necessário para cada uma das propriedades de conexão listadas nas seções a seguir.

• Você também pode adicionar configurações especiais ou avançadas de capacidade do driver.

Coleções programáticas de propriedades de conexão JDBC podem ser usadas em código Java, como no 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 DATABRICKS_SERVER_HOSTNAME DATABRICKS_HTTP_PATH os valores de ambiente compute e para os valores do servidor hostname e caminho HTTP do recurso do Databricks de destino, respectivamente. Para obter esses valores, consulte Configurações de computação para o driver JDBC do Databricks. Para definir variável 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 listadas nas seções a seguir.

• Você também pode adicionar configurações de capacidade de driver especiais ou avançadas, normalmente como pares <setting> e <value> adicionais.

• Neste exemplo, substitua <query> por uma strings de consulta SQL SELECT .

O uso de um URL de conexão ou de uma coleção de propriedades de conexão dependerá dos requisitos do 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 nestes artigos para cada tipo de autenticação do Databricks com suporte.

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

• access tokenpessoal do Databricks

• tokensOAuth 2.0

• Autenticação usuário-máquina (U2M) OAuth

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

access tokenpessoal do Databricks

Para criar um access token pessoal do Databricks, faça o seguinte:

1. Em seu Databricks workspace, clique em seu nome de usuário Databricks na barra superior e selecione Settings (Configurações ) no menu suspenso.

2. Clique em Desenvolvedor.

3. Ao lado do access token, clique em gerenciar.

4. Clique em Gerar novos tokens.

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 vida útil (não recomendado), deixe a caixa Duração (dias) vazia (em branco).

6. Clique em Gerar.

7. Copie o token exibido em um local seguro e clique em Concluído.

Observação

Certifique-se de salvar os tokens copiados em um local seguro. Não compartilhe seus tokens copiados com outras pessoas. Se você perder os tokens copiados, não poderá regenerar exatamente os mesmos tokens. Em vez disso, você deve repetir este procedimento para criar novos tokens. Se você perder os tokens copiados ou acreditar que os tokens foram comprometidos, o Databricks recomenda fortemente que você exclua imediatamente esses tokens do seu workspace clicando no ícone da lixeira (Revogar) ao lado dos tokens na página access tokens .

Se o senhor não conseguir criar ou usar o site tokens no seu workspace, isso pode ocorrer porque o administrador do workspace desativou o tokens ou não lhe deu permissão para criar ou usar o tokens. Consulte o administrador do site workspace ou os tópicos a seguir:

• Habilitar ou desabilitar a autenticação access token pessoal para o workspace

• Permissões access token pessoal

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

Para uma URL de conexão JDBC com propriedades de configuração geral integradas 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 gerais 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 onde 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 access token pessoal do Databricks para o usuário do seu workspace.

• Para obter os valores de <server-hostname> e <http-path>, consulte Configurações de computação para o driver JDBC do Databricks.

Tokens OAuth 2.0

O driver JDBC 2.6.36 e acima oferece suporte a tokens OAuth 2.0 para um usuário ou entidade de serviço do Databricks. Isso também é conhecido como autenticação de passagemtokens OAuth 2.0.

Para criar tokens OAuth 2.0 para autenticação de passagem tokens , faça o seguinte:

• Para um usuário, você pode usar a CLI do Databricks para gerar os tokens OAuth 2.0 iniciando o processo OAuth U2M e, em seguida, obter os tokens OAuth 2.0 gerados executando o comando databricks auth token. Consulte Autenticação usuário-máquina (U2M) OAuth. Os tokens OAuth 2.0 têm uma vida útil default de 1 hora. Para gerar novos tokens OAuth 2.0, repita esse processo.

• Para uma entidade de serviço, consulte Gerar e usar manualmente access tokens para autenticação OAuth M2M. Anote o valor OAuth access_token da entidade de serviço. OAuth 2.0 tokens têm uma vida útil de default de 1 hora. Para gerar novos tokens OAuth 2.0, repita esse processo.

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

Para uma URL de conexão JDBC com propriedades de configuração geral integradas 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 gerais 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 onde 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 <oauth-token> pelos tokens 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 de usuário para máquina (U2M) OAuth

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

Observação

JDBC A versão 2.6.40.1071 resolve o problema de versões anteriores em que não havia suporte para a conexão usando M2M para o espaço de trabalho de link privado.

A autenticação baseada em navegador OAuth U2M ou OAuth 2.0 não tem pré-requisitos. Os tokens OAuth 2.0 têm uma vida útil default de 1 hora. A autenticação baseada em navegador OAuth U2M ou OAuth 2.0 deve refresh automaticamente os tokens expirados do OAuth 2.0 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 clouds .

Para autenticar usando a autenticação usuário-máquina (U2M) OAuth ou 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 integradas 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 gerais 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 onde 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 senha de sua escolha. O driver usa essa key para refresh tokens criptografia .

• 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 OAuth máquina a máquina (M2M)

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

Observação

JDBC A versão 2.6.40.1071 resolve o problema de versões anteriores em que não havia suporte para a conexão usando M2M para o espaço de trabalho de link privado.

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 do Databricks em seu workspace do Databricks e crie um segredo OAuth para essa entidade de serviço.

   Para criar a entidade de serviço e seu segredo OAuth, consulte Autenticar o acesso ao Databricks com uma entidade de serviço usando OAuth (OAuth M2M). Anote o valor do UUID da entidade de serviço ou do ID do aplicativo e o valor do segredo do OAuth da entidade de serviço.

2. Permitir que a entidade de serviço tenha acesso a seus clusters ou armazéns. Consulte as permissões do sitecompute ou gerenciar a SQL warehouse.

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

Para uma URL de conexão JDBC com propriedades de configuração geral integradas 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 gerais 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 onde 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 UUID/ID do aplicativo da entidade de serviço.

  • Substitua <service-principal-oauth-secret> pelo valor secreto OAuth da entidade de serviço.

  • 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.