Autenticação da CLI do Databricks

Observação

Essas informações se aplicam às versões da CLI do Databricks 0.205 e superiores, que estão em Versão Prévia Pública. Para localizar sua versão da CLI do Databricks, execute databricks -v.

Este ar descreve como configurar a autenticação entre a CLI do Databricks e suas contas e workspaces do Azure Databricks. Confira O que é a CLI do Databricks?.

Este artigo pressupõe que você já instalou a CLI do Databricks. Confira Instalar ou atualizar a CLI do Databricks.

Antes de executar os comandos da CLI do Databricks, você deve configurar a autenticação entre a CLI do Databricks e suas contas, workspaces ou uma combinação do Azure Databricks, dependendo dos tipos de comandos da CLI que você deseja executar.

Você deve autenticar a CLI do Databricks nos recursos relevantes em tempo de execução para executar comandos de automação do Azure Databricks em uma conta ou workspace do Azure Databricks. Dependendo se você deseja chamar comandos no nível do workspace do Azure Databricks, comandos no nível da conta do Azure Databricks ou ambos, você precisa autenticar-se no workspace, conta ou ambos do Azure Databricks. Para obter uma lista de grupos de comandos da CLI no nível do workspace e do nível da conta do Azure Databricks, execute o comando databricks -h. Para obter uma lista das operações da API REST no nível do workspace e da conta do Azure Databricks que os comandos da CLI do Databricks abrangem, consulte a API REST do Databricks.

Observação

O CLI do Databricks implementa o padrão de autenticação unificada do cliente do Databricks, uma abordagem arquitetônica e programática consolidada e consistente para autenticação. Essa abordagem ajuda a tornar a configuração e a automação da autenticação com o Azure Databricks mais centralizada e previsível. Ela permite que você configure a autenticação do Azure Databricks uma vez e use essa configuração em várias ferramentas e SDKs do Azure Databricks sem mais alterações posteriores na configuração da autenticação. Para obter mais informações sobre esse padrão, consulte Autenticação unificada do cliente do Databricks.

As seções a seguir fornecem informações sobre configurar a autenticação entre a CLI do Databricks e o Azure Databricks:

• Autenticação de token de acesso pessoal do Azure Databricks
• Autenticação OAuth máquina a máquina (M2M)
• Autenticação U2M (usuário para computador) do OAuth
• Autenticação de identidades gerenciadas do Azure
• Autenticação de entidades de serviço do Microsoft Entra ID
• Autenticação da CLI do Azure
• Ordem de avaliação de autenticação

Autenticação de token de acesso pessoal do Azure Databricks

O token de acesso pessoal do Azure Databricks usa um token de acesso pessoal do Azure Databricks para autenticar a entidade de destino do Azure Databricks, como uma conta de usuário do Azure Databricks. Confira Autenticação com tokens de acesso pessoal do Azure Databricks.

Observação

Você não pode usar a autenticação de token de acesso pessoal do Azure Databricks para autenticação com uma conta do Azure Databricks, pois os comandos no nível da conta do Azure Databricks não usam tokens de acesso pessoal do Azure Databricks para autenticação. Para se autenticar com uma conta do Azure Databricks, considere usar um dos seguintes tipos de autenticação em vez disso:

• Autenticação OAuth máquina a máquina (M2M)
• Autenticação U2M (usuário para computador) do OAuth
• Autenticação de identidades gerenciadas do Azure
• Autenticação de entidades de serviço do Microsoft Entra ID
• Autenticação da CLI do Azure

Para criar um token de acesso pessoal, 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:

• Habilitar ou desabilitar a autenticação de token de acesso pessoal para o workspace
• Permissões do token de acesso pessoal

Para configurar e usar a autenticação de token de acesso pessoal do Azure Databricks, faça o seguinte:

Observação

O procedimento a seguir cria um perfil de configuração do Azure Databricks com o nome DEFAULT. Se você já tiver um perfil de configuração DEFAULT que deseja usar, ignore este procedimento. Caso contrário, esse procedimento substituirá seu perfil de configuração DEFAULT existente. Para ver os nomes e os hosts de qualquer perfil de configuração existente, execute o comando databricks auth profiles.

Para criar um perfil de configuração com um nome diferente de DEFAULT, adicione --profile <configuration-profile-name> ou -p <configuration-profile-name> ao final do comando databricks configure a seguir, substituindo <configuration-profile-name> pelo nome do novo perfil de configuração.

1. Use a CLI do Databricks para executar o seguinte comando:

   databricks configure
   

2. Para o prompt de Host do Databricks, insira sua URL de por workspace do Azure Databricks, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

3. Para o token de acesso pessoal de prompt, insira o token de acesso pessoal do Azure Databricks para seu workspace.

   Depois de inserir o token de acesso pessoal do Azure Databricks, um perfil de configuração correspondente será adicionado ao arquivo .databrickscfg. Se a CLI do Databricks não conseguir encontrar esse arquivo em seu local padrão, ele criará esse arquivo para você primeiro e, em seguida, adicionará esse perfil de configuração ao novo arquivo. A localização padrão para esse arquivo é na sua pasta ~ (sua página inicial do usuário) no Unix, Linux ou macOS ou sua pasta %USERPROFILE% (sua página inicial do usuário) no Windows.

4. Você pode usar agora a opção da CLI do Databricks --profile ou -p seguida pelo nome do seu perfil de configuração, como parte da chamada de comando da CLI do Databricks, por exemplo databricks clusters list -p <configuration-profile-name>.

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

Em vez de autenticar com o Azure Databricks usando a autenticação de token de acesso pessoal do Azure Databricks, você pode usar a autenticação OAuth. O OAuth fornece tokens com tempos de expiração mais rápidos do que os tokens de acesso pessoal do Azure Databricks e oferece melhor invalidação e escopo de sessão do lado do servidor. Como os tokens de acesso OAuth expiram em menos de uma hora, isso reduz o risco associado à verificação acidental de tokens no controle do código-fonte. Consulte também Autenticação máquina a máquina (M2M) do OAuth.

Para configurar e usar a autenticação M2M do OAuth, faça o seguinte:

1. Conclua as instruções de configuração de autenticação M2M do OAuth. Confira Autenticação OAuth M2M (computador para computador)

2. Crie ou identifique um perfil de configuração do Azure Databricks com os seguintes campos em seu arquivo do .databrickscfg. Se você criar o perfil, substitua os espaços reservados pelos valores apropriados.

   Para comandos no nível da conta, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host          = <account-console-url>
   account_id    = <account-id>
   client_id     = <service-principal-client-id>
   client_secret = <service-principal-oauth-secret>
   

   Para comandos no nível do workspace, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host          = <workspace-url>
   client_id     = <service-principal-client-id>
   client_secret = <service-principal-oauth-secret>
   

   Observação

   O local padrão do arquivo .databrickscfg está no diretório inicial do usuário. Ou seja, ~ para Linux e macOS e %USERPROFILE% para Windows.

3. Use a opção --profile ou -p da CLI do Databricks seguida pelo nome do seu perfil de configuração, como parte da chamada de comando da CLI do Databricks, por exemplo, databricks account groups list -p <configuration-profile-name> ou databricks clusters list -p <configuration-profile-name>.

   Dica

   Pressione Tab depois de --profile ou -p para visualizar uma lista de perfis de configuração existentes disponíveis para sua escolha, em vez de inserir o nome do perfil de configuração manualmente.

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

Em vez de autenticar com o Azure Databricks usando a autenticação de token, você pode usar a autenticação OAuth. O OAuth fornece tokens com tempos de expiração mais rápidos do que os tokens de acesso pessoal do Azure Databricks e oferece melhor invalidação e escopo de sessão do lado do servidor. Como os tokens de acesso OAuth expiram em menos de uma hora, isso reduz o risco associado à verificação acidental de tokens no controle do código-fonte. Consulte também a Autenticação U2M (usuário para computador) do OAuth.

Para configurar e usar a autenticação U2M do OAuth, faça o seguinte:

1. Antes de chamar comandos no nível da conta do Azure Databricks, você precisa iniciar o gerenciamento de token OAuth localmente executando o comando a seguir. Esse comando precisa ser executado separadamente para cada conta em que você deseja executar comandos. Se você não quiser chamar nenhuma operação no nível da conta, vá para a etapa 5.

   No comando anterior, substitua os seguintes espaços reservados:

   • Substitua <account-console-url> pelo https://accounts.azuredatabricks.net do Azure Databricks.
   • Substitua <account-id> pela ID da conta do Azure Databricks. Confira Localizar a ID da conta.

   databricks auth login --host <account-console-url> --account-id <account-id>
   

2. A CLI do Databricks solicita que você salve a URL do console da conta e a ID da conta localmente como um perfil de configuração do Azure Databricks. Pressione Enter para aceitar o nome de perfil sugerido ou digite o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome será substituído por essa URL do console da conta e ID da conta.

   Para obter uma lista de quaisquer perfis existentes, em um terminal ou prompt de comando separado, execute o comando databricks auth profiles. Para visualizar as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.

3. No seu navegador da Web, complete as instruções na tela para fazer logon na sua conta do Azure Databricks.

4. Para exibir o valor atual do token OAuth e o carimbo de data/hora de expiração futura, execute o comando databricks auth token --host <account-console-url> --account-id <account-id>.

5. Antes de chamar comandos no nível de workspace do Azure Databricks, você precisa iniciar o gerenciamento de token OAuth localmente executando o comando a seguir. Esse comando precisa ser executado separadamente para cada workspace em que você deseja executar comandos.

   No comando a seguir, substitua <workspace-url> pela URL por workspace do Azure Databricks, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

   databricks auth login --host <workspace-url>
   

6. A CLI do Databricks solicita que você salve a URL do workspace localmente como um perfil de configuração do Azure Databricks. Pressione Enter para aceitar o nome de perfil sugerido ou digite o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome será substituído por esta URL do workspace.

   Para obter uma lista de quaisquer perfis existentes, em um terminal ou prompt de comando separado, execute o comando databricks auth profiles. Para visualizar as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.

7. No seu navegador da Web, complete as instruções na tela para iniciar sessão no seu workspace do Azure Databricks.

8. Para exibir o valor atual do token OAuth e o carimbo de data/hora de expiração futura, execute o comando databricks auth token --host <workspace-url>.

9. Use a opção da CLI do Databricks --profile ou -p seguida pelo nome do seu perfil de configuração, como parte da chamada de comando da CLI do Databricks, por exemplo databricks account groups list -p <configuration-profile-name> ou databricks clusters list -p <configuration-profile-name>.

   Dica

   Pressione Tab depois de --profile ou -p para visualizar uma lista de perfis de configuração disponíveis existentes para sua escolha, em vez de inserir o nome do perfil de configuração manualmente.

Autenticação de identidades gerenciadas do Azure

A autenticação Identidades gerenciadas do Azure usa identidades gerenciadas para recursos do Azure (anteriormente MSI [Identidades de Serviço Gerenciado]) para autenticação. Consulte O que são identidades gerenciadas para recursos do Azure?. Consulte também Autenticação de identidades gerenciadas do Azure.

Para criar uma identidade gerida atribuída pelo utilizador do Azure, faça o seguinte:

1. Crie ou identifique uma VM do Azure e instale a CLI do Databricks nela e, em seguida, atribua sua identidade gerenciada à sua VM do Azure e às contas, aos espaços de trabalho do Azure Databricks de destino ou a ambos. Veja Configurar e usar a autenticação de identidades gerenciadas do Azure para automação do Azure Databricks.

2. Na VM do Azure, crie ou identifique um perfil de configuração do Azure Databricks com os seguintes campos em seu arquivo .databrickscfg. Se você criar o perfil, substitua os espaços reservados pelos valores apropriados.

   Para comandos no nível da conta, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host            = <account-console-url>
   account_id      = <account-id>
   azure_client_id = <azure-managed-identity-application-id>
   azure_use_msi   = true
   

   Para comandos no nível do workspace, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host            = <workspace-url>
   azure_client_id = <azure-managed-identity-application-id>
   azure_use_msi   = true
   

   Para comandos no nível do workspace, se a identidade de destino ainda não foi adicionada ao workspace, especifique azure_workspace_resource_id junto com a ID do recurso do Azure, em vez de host junto com a URL do workspace. Nesse caso, a identidade de destino deve ter, no mínimo, permissões de Colaborador ou Proprietário no recurso do Azure.

   Observação

   O local padrão do arquivo .databrickscfg está no diretório inicial do usuário. Ou seja, ~ para Linux e macOS e %USERPROFILE% para Windows.

3. Na VM do Azure, use a opção --profile ou -p da CLI do Databricks seguida do nome do seu perfil de configuração para definir o perfil a ser usado pelo Databricks, por exemplo, databricks account groups list -p <configuration-profile-name> ou databricks clusters list -p <configuration-profile-name>.

   Dica

   Pressione Tab depois de --profile ou -p para visualizar uma lista de perfis de configuração disponíveis existentes para sua escolha, em vez de inserir o nome do perfil de configuração manualmente.

Autenticação de entidades de serviço do Microsoft Entra ID

A autenticação de entidades de serviço do Microsoft Entra ID usa as credenciais de uma entidade de serviço do Microsoft Entra ID para autenticar. Para criar e gerenciar entidades de serviço para o Azure Databricks, confira Gerenciar entidades de serviço. Confira também Autenticação de entidades de serviço do Microsoft Entra ID.

Para configurar e usar a autenticação de entidades de serviço do Microsoft Entra ID, você precisa ter a CLI do Azure instalada localmente. Você também deve fazer o seguinte:

1. Crie ou identifique um perfil de configuração do Azure Databricks com os seguintes campos em seu arquivo do .databrickscfg. Se você criar o perfil, substitua os espaços reservados pelos valores apropriados.

   Para comandos no nível da conta, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host                = <account-console-url>
   account_id          = <account-id>
   azure_tenant_id     = <azure-service-principal-tenant-id>
   azure_client_id     = <azure-service-principal-application-id>
   azure_client_secret = <azure-service-principal-client-secret>
   

   Para comandos no nível do workspace, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host                = <workspace-url>
   azure_tenant_id     = <azure-service-principal-tenant-id>
   azure_client_id     = <azure-service-principal-application-id>
   azure_client_secret = <azure-service-principal-client-secret>
   

   Para comandos no nível do workspace, se a entidade de serviço do Microsoft Entra ID de destino ainda não tiver sido adicionada ao workspace, especifique azure_workspace_resource_id junto com a ID do recurso do Azure em vez do host junto com a URL do workspace. Nesse caso, a entidade de serviço do Microsoft Entra ID de destino precisa ter pelo menos permissões de Colaborador ou Proprietário no recurso do Azure.

   Observação

   O local padrão do arquivo .databrickscfg está no diretório inicial do usuário. Ou seja, ~ para Linux e macOS e %USERPROFILE% para Windows.

2. Use a opção da CLI do Databricks --profile ou -p seguida pelo nome do seu perfil de configuração, como parte da chamada de comando da CLI do Databricks, por exemplo databricks account groups list -p <configuration-profile-name> ou databricks clusters list -p <configuration-profile-name>.

   Dica

   Pressione Tab depois de --profile ou -p para visualizar uma lista de perfis de configuração disponíveis existentes para sua escolha, em vez de inserir o nome do perfil de configuração manualmente.

Autenticação da CLI do Azure

A autenticação da CLI do Azure usa a CLI do Azure para autenticar a entidade de entrada. Consulte também Autenticação da CLI do Azure.

Para configurar a autenticação da CLI do Azure, você deve fazer o seguinte:

1. Ter a CLI do Azure instalada localmente.

2. Use a CLI do Azure para fazer logon no Azure Databricks executando o comando az login. Confira Logon da CLI do Azure com uma conta de usuário do Azure Databricks.

3. Crie ou identifique um perfil de configuração do Azure Databricks com os seguintes campos em seu arquivo do .databrickscfg. Se você criar o perfil, substitua os espaços reservados pelos valores apropriados.

   Para comandos no nível da conta, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host       = <account-console-url>
   account_id = <account-id>
   

   Para comandos no nível do workspace, defina os seguintes valores no seu arquivo .databrickscfg:

   [<some-unique-configuration-profile-name>]
   host = <workspace-url>
   

   Observação

   O local padrão do arquivo .databrickscfg está no diretório inicial do usuário. Ou seja, ~ para Linux e macOS e %USERPROFILE% para Windows.

4. Use a opção da CLI do Databricks --profile ou -p seguida pelo nome do seu perfil de configuração, como parte da chamada de comando da CLI do Databricks, por exemplo databricks account groups list -p <configuration-profile-name> ou databricks clusters list -p <configuration-profile-name>.

   Dica

   Pressione Tab depois de --profile ou -p para visualizar uma lista de perfis de configuração disponíveis existentes para sua escolha, em vez de inserir o nome do perfil de configuração manualmente.

Ordem de avaliação de autenticação

Sempre que a CLI do Databricks precisar coletar as configurações necessárias para tentar se autenticar com um workspace ou conta do Azure Databricks, ela pesquisa essas configurações nos locais a seguir, na ordem a seguir.

1. Para comandos de pacote, os valores dos campos dentro dos arquivos de configuração de pacote de um projeto. (Os arquivos de configuração de pacote não dão suporte à inclusão direta de valores de credencial de acesso.)
2. Os valores das variáveis de ambiente, conforme listado neste artigo e em Variáveis de ambiente e campos para autenticação unificada do cliente.
3. Valores de campo de perfil de configuração dentro do .databrickscfg arquivo, conforme listado anteriormente neste artigo.

Sempre que a CLI do Databricks encontrar as configurações necessárias, ela interromperá a pesquisa em outros locais. Por exemplo:

• A CLI do Databricks precisa do valor de um token de acesso pessoal do Azure Databricks. Uma variável de ambiente DATABRICKS_TOKEN é definida e o arquivo .databrickscfg também contém vários tokens de acesso pessoal. Neste exemplo, a CLI do Databricks usa o valor da variável de ambiente DATABRICKS_TOKEN e não pesquisa o arquivo .databrickscfg.
• O comando databricks bundle deploy -e development precisa do valor de um token de acesso pessoal do Azure Databricks. Uma variável de ambiente DATABRICKS_TOKEN não é definida e o arquivo .databrickscfg contém vários tokens de acesso pessoal. O arquivo de configurações de pacote do projeto contém uma development declaração de ambiente que faz referência por meio de seu campo profile a um perfil de configuração chamado DEV. Neste exemplo, a CLI do Databricks pesquisa um perfil .databrickscfg chamado DEV e usa o valor do campo token desse perfil.
• O comando databricks bundle run -e development hello-job precisa do valor de um token de acesso pessoal do Azure Databricks. Uma variável de ambiente DATABRICKS_TOKEN não é definida e o arquivo .databrickscfg contém vários tokens de acesso pessoal. O arquivo de configurações de pacote do projeto contém uma development declaração de ambiente que faz referência por meio de seu campo host a uma URL do workspace do Azure Databricks específica. Neste exemplo, a CLI do Databricks pesquisa nos perfis de configuração no .databrickscfg arquivo um perfil que contém um host campo com uma URL de workspace correspondente. A CLI do Databricks localiza um campo correspondente host e, em seguida, usa o valor de campo token desse perfil.