Crie um objeto destinatário para usuários não-Databricks usando tokens de portador (compartilhamento Databricks-para-Aberto)

Este artigo descreve como criar destinatários de Compartilhamento Aberto que não têm acesso a um workspace Databricks habilitado para Unity Catalog e conceder a esses destinatários acesso a dados compartilhados com segurança usando tokens de portador. Este fluxo de autenticação, juntamente com o fluxo de autenticação de federação de tokens OIDC, é chamado de *compartilhamento aberto*.

Veja como funciona:

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

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

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

3. O destinatário acessa o link de ativação, faz o download do arquivo de credenciais e usa o arquivo de credenciais 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 do OIDC é uma alternativa ao fluxo de token do portador descrito neste artigo. Possui vantagens de segurança e conveniência em relação ao fluxo do token do portador. Para obter detalhes, consulte Ativar a federação do Open ID Connect (OIDC) para destinatários do OpenSharing.

importante

Todos os tokens de destinatários de compartilhamento Databricks-to-Open emitidos antes de 8 de dezembro de 2025, com datas de validade após 8 de dezembro de 2026, ou sem data de validade, expiram automaticamente em 8 de dezembro de 2026. Caso utilize tokens do destinatário com duração longa ou ilimitada, revise as integrações e renove os tokens conforme necessário para evitar alterações interruptivas após esta data.

Criar o destinatário

Para criar um destinatário para o compartilhamento Databricks para Open, você pode usar o Catalog Explorer, a CLI do Unity Catalog do Databricks ou o comando SQL CREATE RECIPIENT em um Notebook do Databricks ou no editor de consultas do Databricks SQL.

Permissões necessárias : Administrador de metastore ou usuário com o privilégio CREATE RECIPIENT para o metastore do Unity Catalog onde os dados que deseja compartilhar estão registrados.

Catalog Explorer

1. No seu Databricks workspace, clique em Catálogo .

2. No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

   Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.

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

4. Insira o Nome do destinatário

5. Para **Tipo de Destinatário**, selecione **Aberto**.

6. Select tokens .

7. (Opcional) Defina o tempo de expiração da Duração do token (em segundos, minutos, horas ou dia a partir do horário de criação do destinatário). Mantenha a opção Definir expiração selecionada para definir um tempo de expiração. Os tokens são válidos por um período máximo de um ano após a criação.

   Se for selecionada a opção Definir expiração e o campo for deixado em branco, a duração do token terá como default o valor da duração do token do destinatário definido na configuração do metastore. Consulte Modificar a duração do token do destinatário. Para obter informações sobre como alterar a duração do token e girar tokens, consulte Gerenciar tokens do destinatário.

8. (Opcional) Insira um comentário.

9. Clique em Criar .

10. Copie o link de ativação.

    Alternativamente, o senhor pode obter o link de ativação mais tarde. Consulte Obter o link de ativação.

11. (Opcional) Crie **Propriedades do destinatário** personalizadas.

    Na guia Visão geral do destinatário, clique no ícone de edição ao lado de 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:

SQL

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

Pode-se também adicionar propriedades personalizadas para o destinatário. Para obter detalhes, consulte Gerenciar propriedades do destinatário.

CLI

Execute o seguinte comando usando a CLI do Databricks.

Bash

databricks recipients create <recipient-name>

Pode-se também 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 de TOKEN.

nota

Ao criar o destinatário, você tem a opção de limitar o acesso do destinatário a um conjunto restrito de endereços IP. Também é possível adicionar uma lista de acesso de IPs a um destinatário existente. Consulte Restringir o acesso do destinatário do OpenSharing usando listas de acesso IP (Databricks para compartilhamento aberto).

Obtenha 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 Databricks Unity Catalog ou o comando SQL DESCRIBE RECIPIENT em um notebook do Databricks ou no editor de consultas do Databricks SQL.

Se o destinatário já baixou o arquivo de credenciais, o link de ativação não é retornado ou exibido.

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

Catalog Explorer

1. No seu Databricks workspace, clique em Catálogo .

2. No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

   Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.

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

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

SQL

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

SQL

DESCRIBE RECIPIENT <recipient-name>;

A saída inclui activation_link.

CLI

Execute o seguinte comando usando a CLI do Databricks.

Bash

databricks recipients get <recipient-name>

A saída inclui activation_url.

Conceda ao destinatário acesso a um compartilhamento

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

Para conceder acesso de compartilhamento a destinatários, você pode usar o Catalog Explorer, a CLI do Databricks Unity Catalog, ou o comando SQL GRANT ON SHARE em um Notebook do Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias : Um dos seguintes:

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

Para obter instruções, consulte Gerenciar acesso aos compartilhamentos de dados do OpenSharing (para provedores).

Envie ao destinatário as 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 de uso.

É possível fazer o download do arquivo de credencial apenas uma vez. Os destinatários devem tratar a credencial baixada como um segredo e não devem compartilhá-la fora de sua organização. Se houver preocupações de que uma credencial possa ter sido tratada de forma insegura, é possível rotacionar a credencial de um destinatário a qualquer momento. Para obter mais informações sobre como gerenciar credenciais para garantir acesso seguro ao destinatário, consulte Considerações de segurança para tokens.

Gerenciar tokens de destinatário

Se você está compartilhando dados com um destinatário usando o fluxo de tokens de portador de compartilhamento Databricks-to-Open, pode ser necessário girar o token desse destinatário. Rotacionar um token consiste em fazer com que um token existente expire e substituí-lo por um novo token e URL de ativação.

Você deve rotacionar 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 sua URL de ativação ou se ela for comprometida.
• Se a credencial for corrompida, perdida ou comprometida depois que for baixada por um destinatário.
• Ao modificar a duração do token do destinatário para um metastore. Consulte Modificar a duração 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 rotacionado. O token rotacionado é aquele que foi configurado para expirar e ser substituído pelo token ativo. Até que o token rotacionado expire, tentar rotacionar o token novamente resulta em um erro.

Ao rotacionar o token de um destinatário, é possível definir opcionalmente --existing-token-expire-in-seconds para o número de segundos antes que o token do destinatário existente — ou seja, aquele que será rotacionado — expire. Se o valor for definido como 0, o token do destinatário existente expira imediatamente.

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

Se a URL de ativação existente de um destinatário nunca foi acessada, a rotação do token existente invalida essa URL de ativação e a substitui por uma nova.

Se todos os tokens do destinatário expiraram, girar o token substitui a URL de ativação existente por uma nova. A Databricks recomenda que você gire ou descarte prontamente um destinatário cujo token expirou.

Se um URL de ativação de destinatário for enviado inadvertidamente para a pessoa errada ou for enviado por um canal inseguro, a Databricks recomenda que você:

1. Revogar o acesso do destinatário ao compartilhamento.
2. Altere o destinatário e defina --existing-token-expire-in-seconds para 0.
3. Compartilhe a nova URL de ativação com o destinatário pretendido por um canal seguro.
4. Após a URL de ativação ter sido acessada, conceda o acesso ao compartilhamento novamente para o destinatário.

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

Girar o token de um destinatário

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

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

nota

Depois de compartilhar o novo link de ativação, o destinatário deve aplicar a nova credencial. Se o destinatário importou a credencial como um objeto provedor no Unity Catalog, ele deve atualizar o objeto provedor com a API REST do Databricks. Consulte Alternar credenciais para destinatários abertos.

Catalog Explorer

1. No seu Databricks workspace, clique em Catálogo .

2. No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

   Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.

3. No painel esquerdo, expanda o menu OpenSharing e selecione Compartilhados por mim .

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

5. Na coluna mais à direita, sob Gerenciamento de tokens , ao lado de Expiração do token , clique em Girar .

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

7. Clique em Girar .

8. Na **tab** **Detalhes**, copie o novo **Link de ativação** e compartilhe-o com o destinatário por um canal seguro. Consulte Obtenha o link de ativação.

CLI

1. Execute o seguinte comando usando a CLI do Databricks. Substitua os valores temporários:

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

   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.

Atualizar duração do token do destinatário

Para atualizar a duração de um token de destinatário existente, use o Catalog Explorer.

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

1. No seu Databricks workspace, clique em Catálogo .

2. No topo do painel Catálogo , clique no ícone de engrenagem e selecione OpenSharing .

   Alternativamente, no canto superior direito, clique em **Share > OpenSharing**.

3. No painel esquerdo, expanda o menu OpenSharing e selecione Compartilhados por mim .

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

5. Na coluna mais à direita, em Gerenciamento de token , ao lado de Expiração de token , clique em Atualizar .

6. Na caixa de diálogo Editar tempo de vida do token do destinatário , defina o novo tempo de vida do token. Para obter orientações sobre quando expirar tokens existentes, consulte Considerações de segurança para tokens.

7. Clique em Salvar .

Modificar a duração do token do destinatário

Se você precisar modificar o tempo de vida do token de destinatário default para seu metastore do Unity Catalog, você pode usar o Catalog Explorer ou a CLI do Databricks Unity Catalog.

nota

A duração do token do destinatário para destinatários existentes não é atualizada automaticamente quando você altera a duração do token do destinatário default de um metastore. Para aplicar a nova duração do token a um determinado destinatário, você deve girar o token. Consulte Gerenciar tokens do destinatário.

Permissões necessárias : Administrador de conta.

Catalog Explorer

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

CLI

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

Bash

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

Recursos adicionais

• Gerenciar acesso a compartilhamentos de dados do OpenSharing (para provedores)
• Gerenciar destinatários de dados para OpenSharing
• Restringir o acesso de destinatários do OpenSharing usando listas de acesso IP (compartilhamento Databricks-para-Open)