Criar um objeto do destinatário para usuários que não são do Databricks usando tokens de portador (compartilhamento aberto)

Este artigo descreve como criar destinatários do Delta Sharing que não têm acesso a um workspace do Databricks habilitado pelo Catálogo do Unity e conceder a esses destinatários acesso a dados compartilhados com segurança usando tokens de portador. Esse fluxo de autenticação, juntamente com o fluxo de autenticação de federação de token OIDC, é chamado de compartilhamento aberto.

Veja como funciona:

1. Como provedor de dados, você cria o objeto destinatário no metastore do Catálogo do Unity.

2. Quando você cria o objeto de destinatário, seleciona o método de token de portador, o Azure Databricks gera um token, um arquivo de credencial que inclui o token e um link de ativação para você compartilhar com o destinatário.

   O objeto destinatário tem o tipo de autenticação de TOKEN. Você pode atualizar e revogar o token conforme necessário.

3. O destinatário acessa o link de ativação, baixa o arquivo de credencial e usa o arquivo de credencial para autenticar e obter acesso de leitura às tabelas que você inclui nos compartilhamentos aos quais você lhes dá acesso.

O fluxo de federação OIDC é uma alternativa ao fluxo de tokens de portador descrito neste artigo. Ele tem vantagens de segurança e praticidade em relação ao fluxo de token de portador. Para obter detalhes, consulte Usar a federação OIDC (Open ID Connect) para habilitar a autenticação nos compartilhamentos Delta Sharing (compartilhamento aberto).

Criar o destinatário

Para criar um destinatário para compartilhamento aberto, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo do Unity Databricks ou o comando SQL CREATE RECIPIENT em um bloco de anotações do Azure Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias: Administrador do Metastore ou usuário com o privilégio CREATE RECIPIENT para o metastore do Catálogo do Unity no qual os dados que você deseja compartilhar estão registrados.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Novo destinatário.

4. Insira o nome do destinatário

5. Para o tipo destinatário, selecione Abrir.

6. Selecione Token.

7. (Opcional) Defina o tempo de expiração do tempo de vida do token (em segundos, minutos, horas ou dia a partir do tempo de criação do destinatário). Deixe Definir expiração selecionado para estabelecer um tempo de expiração. Os tokens são válidos por um máximo de um ano após a criação.

   Se você selecionar Definir expiração e deixar o campo em branco, o tempo de vida do token será padrão para o valor de tempo de vida do token de destinatário definido na configuração do metastore. Consulte Modificar o tempo de vida do token do destinatário. Para obter informações sobre como alterar a duração de vida do token e rotacionar tokens, consulte Gerenciar tokens de destinatário.

8. (Opcional) Insira um comentário.

9. Clique em Criar.

10. Copie o link de ativação.

    Como alternativa, você pode obter o link de ativação mais tarde. Consulte Obter o link de ativação.

11. (Opcional) Criar propriedades do Destinatário personalizadas.

    Na guia Visão geral do destinatário, clique no ao lado das propriedades do destinatário. Em seguida, adicione um nome de propriedade (Chave) e Valor. Para obter detalhes, consulte Gerenciar propriedades do destinatário.

SQL

Execute o seguinte comando em um notebook ou no editor de consultas SQL do Databricks:

CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
[COMMENT "<comment>"];

Você também pode adicionar propriedades personalizadas para o destinatário. Para obter detalhes, consulte Gerenciar propriedades do destinatário.

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients create <recipient-name>

Você também pode adicionar propriedades personalizadas para o destinatário. Para obter detalhes, consulte Gerenciar propriedades do destinatário.

A saída inclui o activation_url que você compartilha com o destinatário.

O destinatário é criado com o authentication_type do TOKEN.

Obter o link de ativação

Para obter o link de ativação do novo destinatário, você pode usar o Catalog Explorer, a CLI do Catálogo do Databricks Unity ou o DESCRIBE RECIPIENT comando SQL em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Se o destinatário já tiver baixado o arquivo de credencial, o link de ativação não será retornado ou exibido.

Permissões necessárias: Administrador do metastore, usuário com o privilégio USE RECIPIENT ou o proprietário do objeto do destinatário.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

3. Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

4. Na página de detalhes do destinatário, copie o link Ativação.

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks.

DESCRIBE RECIPIENT <recipient-name>;

A saída inclui o activation_link.

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks recipients get <recipient-name>

A saída inclui o activation_url.

Conceder ao destinatário acesso a um compartilhamento

Depois de criar o destinatário e criar compartilhamentos, você poderá conceder ao destinatário acesso a esses compartilhamentos.

Para conceder acesso de compartilhamento aos destinatários, você pode usar o Explorador de catálogos, a CLI do Catálogo do Unity do Databricks ou o comando GRANT ON SHARE SQL em um Notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias: uma das seguintes:

• Administrador de metastore.
• Permissões delegadas ou de propriedade no compartilhamento e nos objetos destinatários ((USE SHARE + SET SHARE PERMISSION) ou proprietário do compartilhamento) E (USE RECIPIENT ou proprietário do destinatário).

Para obter instruções, veja Gerenciar o acesso aos compartilhamentos de dados do Delta Sharing (para provedores).

Enviar ao destinatário suas informações de conexão

Você deve informar ao destinatário como acessar os dados que está compartilhando com ele. Use um canal seguro para compartilhar o link de ativação e um link para instruções para usá-lo.

Você pode baixar o arquivo de credenciais apenas uma vez. Os destinatários precisam tratar a credencial baixada como um segredo e não devem compartilhá-la fora da organização. Se você tiver preocupações de que uma credencial possa ter sido tratada de forma insegura, você poderá girar a credencial de um destinatário a qualquer momento. Para obter mais informações sobre como gerenciar credenciais para garantir o acesso seguro ao destinatário, consulte Considerações de segurança para tokens.

Gerenciar tokens de destinatário

Se você estiver compartilhando dados com um destinatário usando o fluxo do token de portador do compartilhamento aberto, talvez seja necessário girar o token desse destinatário. Girar um token consiste em definir um token existente para expirar e substituí-lo por um novo token e URL de ativação.

Você deve girar o token de um destinatário e gerar uma nova URL de ativação nas seguintes circunstâncias:

• Quando o token de destinatário existente estiver prestes a expirar.
• Se um destinatário perder a URL de ativação ou se ela estiver comprometida.
• Se a credencial estiver corrompida, for perdida ou estiver comprometida depois que for baixada por um destinatário.
• Quando você modifica o tempo de vida do token do destinatário para um metastore. Consulte Modificar o tempo de vida do token do destinatário.

Considerações de segurança para tokens

A qualquer momento, um destinatário pode ter, no máximo, dois tokens: um token ativo e um token girado. O token girado é aquele que foi definido para expirar e ser substituído pelo token ativo. Até que o token girado expire, tentar girar o token novamente resultará em um erro.

Ao girar o token de um destinatário, opcionalmente, você pode definir --existing-token-expire-in-seconds como o número de segundos antes que o token de destinatário existente, ou seja, aquele a ser girado, expire. Se você definir o valor como 0, o token de destinatário existente vai expirar imediatamente.

O Databricks recomenda que você defina --existing-token-expire-in-seconds como um período relativamente curto que dê à organização do destinatário tempo necessário para acessar a nova URL de ativação, minimizando o tempo durante o qual o destinatário tem dois tokens ativos. Se você suspeitar de que o token de destinatário existente está comprometido, o Databricks recomenda que você force a expiração imediata.

Se a URL de ativação existente de um destinatário nunca tiver sido acessada, girar o token existente invalida essa URL de ativação e a substituirá por uma nova.

Se todos os tokens de destinatário expiraram, rotacionar o token substitui a URL de ativação existente por uma nova. O Databricks recomenda que você gire ou remova imediatamente um destinatário cujo token expirou.

Se uma URL de ativação do destinatário for enviado inadvertidamente para a pessoa errada ou for enviado por um canal não seguro, o Databricks recomendará que você:

1. Revogue o acesso do destinatário ao compartilhamento.
2. Gire o destinatário e defina --existing-token-expire-in-seconds como 0.
3. Compartilhe o novo URL de ativação com o destinatário pretendido em um canal seguro.
4. Depois que a URL de ativação tiver sido acessada, permita novamente o acesso do destinatário ao compartilhamento.

Em situações extremas, em vez de rotacionar o token do destinatário, você pode remover e recriar o destinatário.

Rodar o token de um destinatário

Para rotacionar o token de um destinatário, você pode usar o Catalog Explorer ou o Databricks Unity Catalog CLI.

Permissões necessárias: proprietário do objeto destinatário.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.

3. Na parte superior do painel Catálogo, clique no e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido, clique no botão Compartilhamento Delta >.

4. Na guia Compartilhado por mim, clique em Destinatários e selecione o destinatário.

5. Na guia Detalhes, em Expiração do Token, clique em Girar.

6. Na caixa de diálogo Girar token, defina o token para expirar imediatamente ou por um período de tempo definido. Para obter conselhos sobre quando expirar tokens existentes, consulte Considerações de segurança para tokens.

7. Clique em Girar.

8. Na guia Detalhes, copie o novo link ativação e compartilhe-o com o destinatário em um canal seguro. Consulte Obter o link de ativação.

CLI

1. Execute o comando a seguir usando a CLI do Databricks. Substitua os valores de espaço reservado:

   • <recipient-name>: o nome do destinatário.
   • <expiration-seconds>: o número de segundos até que o token do destinatário existente expire. Durante esse período, o token existente continuará funcionando. Um valor igual a 0 significa que o token existente expira imediatamente. Para obter conselhos sobre quando expirar tokens existentes, consulte Considerações de segurança para tokens.

   databricks recipients rotate-token \
   <recipient-name> \
   <expiration-seconds>
   

2. Obtenha o novo link de ativação do destinatário e compartilhe-o com o destinatário em um canal seguro. Consulte Obter o link de ativação.

Modificar o tempo de vida do token do destinatário

Se você precisar modificar o tempo de vida do token de destinatário padrão para seu metastore do Catálogo do Unity, poderá usar o Explorador de Catálogos ou a CLI do Catálogo do Unity Databricks.

Permissões necessárias: administrador da conta.

Gerenciador de Catálogos

1. Faça logon no console da conta.
2. Na barra lateral, clique no Catálogo.
3. Clique no nome do metastore.
4. Em Tempo de vida do token de destinatário do Compartilhamento Delta, clique em Editar.
5. Habilite Definir validade.
6. Insira um número de segundos, minutos, horas ou dias e selecione a unidade de medida. Os tokens são válidos por um máximo de um ano após a criação.
7. Clique em Salvar.

CLI

Execute o comando a seguir usando a CLI do Databricks. Substitua 12a345b6-7890-1cd2-3456-e789f0a12b34 pela UUID do metastore e substitua 86400 pelo número de segundos antes que o token do destinatário expire. Os tokens são válidos por um máximo de um ano após a criação.

databricks metastores update \
12a345b6-7890-1cd2-3456-e789f0a12b34 \
--delta-sharing-recipient-token-lifetime-in-seconds 86400