Configurar uma política de federação

A federação de tokens OAuth do Databricks permite que você acesse APIs do Databricks com segurança usando tokens do seu provedor de identidade (IdP). Para habilitar a federação de tokens OAuth, você deve configurar uma política de federação, seja como Databricks em toda a conta ou para cargas de trabalho.

Esta página descreve como criar e configurar uma política de federação de token OAuth.

Federação de identidades de carga de trabalho

A federação de identidades de carga de trabalho permite que as tuas cargas de trabalho automatizadas, a correr fora do Azure Databricks, acedam às APIs do Azure Databricks sem necessidade de segredos do Azure Databricks. Os administradores de conta podem configurar a federação de identidades de carga de trabalho usando uma política de federação de entidade de serviço.

Uma política de federação de principal de serviço está associada a um principal de serviço na sua conta Azure Databricks e especifica:

• O provedor de identidade (ou emissor) a partir do qual a entidade de serviço pode autenticar.
• A identidade da carga de trabalho (ou assunto) que é autorizada a autenticar como principal do serviço do Azure Databricks.

Por exemplo, dada a seguinte política de federação de entidade de serviço para uma carga de trabalho de Ações do Github:

• Emitente:https://token.actions.githubusercontent.com
• Audiências:https://github.com/my-github-org
• Assunto:repo:my-github-org/my-repo:environment:prod

Pode usar este corpo JWT para autenticar no Azure Databricks:

{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://github.com/my-github-org",
  "sub": "repo:my-github-org/my-repo:environment:prod"
}

Configurar uma política de federação da entidade de serviço

Os administradores de conta podem configurar uma política de federação do principal de serviço usando a CLI do Databricks ou a API do Databricks. Pode criar um máximo de 20 políticas de federação de Service Principal por cada Azure Databricks Service Principal.

Para configurar uma política de federação da entidade de serviço, você deve especificar o seguinte:

• URL do emissor: Uma URL HTTPS que identifica o provedor de identidade de carga de trabalho, especificado na iss declaração de tokens de identidade de carga de trabalho.

• Assunto: O identificador exclusivo para a carga de trabalho no ambiente de execução. Se não for especificado, o padrão será sub.

• Audiências: O destinatário pretendido do token, especificado na aud declaração. O token é considerado uma correspondência se seu público corresponder a pelo menos um público na política. Se não especificado, o predeterminado é o ID da sua conta Azure Databricks.

• Declaração de assunto: (Opcional) Especifica a declaração de token que contém a identidade da carga de trabalho (também chamada de assunto) do token. Se não estiver definido, Azure Databricks usa sub por defeito. O Databricks recomenda manter a declaração padrão sub para a federação de identidades de carga de trabalho. Escolha apenas uma declaração diferente se sub não for um identificador de assunto adequado ou estável, o que é raro. Para obter detalhes, consulte Exemplo de políticas de federação da entidade de serviço.

• Validação de assinatura de token: (Opcional) As chaves públicas, ou sua URL, no formato JSON Web Key Sets (JWKS) usado para validar assinaturas de token. JWKS JSON suporta até 5 chaves. Se o seu provedor de identidade publicar mais informações, use um URI JWKS.

  Se não for especificado, Azure Databricks recupera as chaves do endpoint bem conhecido do emissor, que é a abordagem recomendada. Seu provedor de identidade deve fornecer Metadados de Provedor OpenID em <issuer-url>/.well-known/openid-configuration que incluam um jwks_uri especificando a localização das chaves públicas usadas para verificar assinaturas de token.

Interface do usuário do Databricks

1. Como administrador de conta, inicia sessão na consola da conta Azure Databricks em https://accounts.azuredatabricks.net.
2. Clique em Gerenciamento de usuários.
3. Vá para o separador Entidades de serviço.
4. Selecione a entidade de serviço para a qual criar a política.
5. Vá para a aba Credenciais & segredos.
6. Na guia Políticas de federação , clique em Criar política.
7. Selecione um provedor de credenciais federadas e configure os campos correspondentes.
8. Clique em Criar política.

CLI do Databricks

Não podes usar a CLI Databricks no espaço de trabalho Azure Databricks terminal web para criar uma política de federação.

1. Instale ou atualize para a versão mais recente da linha de comando do Databricks.

2. Como administrador de contas, autentique a sua conta Azure Databricks usando a linha de código. Especifique o ACCOUNT_CONSOLE_URL e o seu Azure Databricks ACCOUNT_ID:

   databricks auth login --host ${ACCOUNT_CONSOLE_URL} --account-id ${ACCOUNT_ID}
   

3. Obtenha a ID numérica da entidade de serviço a que será aplicada a política de federação. (Por exemplo, 3659993829438643.)

   Se você souber a ID do aplicativo da entidade de serviço (normalmente um valor GUID, como bc3cfe6c-469e-4130-b425-5384c4aa30bb) com antecedência, poderá determinar a ID numérica da entidade de serviço usando a CLI do Databricks:

   databricks account service-principals list --filter 'applicationId eq "<service-principal-application-id>"'
   

4. Crie a política de federação da entidade de serviço. Aqui está um exemplo de criação de uma política de federação para uma Ação do GitHub:

   databricks account service-principal-federation-policy create ${SERVICE_PRINCIPAL_NUMERIC_ID} --json \
   '{
     "oidc_policy": {
       "issuer": "https://token.actions.githubusercontent.com",
       "audiences": [
         "https://github.com/my-github-org"
       ],
       "subject": "repo:my-github-org/my-repo:environment:prod"
     }
   }'
   

API de conta Databricks

1. Obtenha a ID numérica da entidade de serviço (por exemplo, 3659993829438643) no console da conta ou usando a API de Entidades de Serviço.

2. Crie a política de federação da entidade de serviço. Especifique o ACCOUNT_CONSOLE_URL, o seu Azure Databricks ACCOUNT_ID, o SERVICE_PRINCIPAL_NUMERIC_ID e um portador TOKEN para autenticação:

   curl --request POST \
     --header "Authorization: Bearer $TOKEN" \
     "${ACCOUNT_CONSOLE_URL}/api/2.0/accounts/${ACCOUNT_ID}/servicePrincipals/${SERVICE_PRINCIPAL_NUMERIC_ID}/federationPolicies" \
     --data '{
       "oidc_policy": {
         "issuer": "https://token.actions.githubusercontent.com",
         "audiences": [
           "https://github.com/my-github-org"
         ],
         "subject": "repo:my-github-org/my-repo:environment:prod"
       }
     }'
   

   Para obter a documentação completa de referência da API, consulte a API de política de federação de conta.

Exemplo de políticas de federação da entidade de serviço Databricks

A tabela a seguir fornece exemplos de políticas de federação da entidade de serviço e o corpo JWT correspondente.

Para obter as etapas de configuração completas para habilitar a federação de identidades de carga de trabalho para alguns desses provedores de identidade comuns, consulte Habilitar federação de identidades de carga de trabalho em CI/CD.

Melhores práticas para políticas de federação de entidades de serviço

Cada principal de serviço apoia um máximo de 20 políticas de federação. Siga estas orientações para evitar atingir esse limite.

Mapear uma identidade externa por principal de serviço

Crie um principal de serviço dedicado para cada identidade distinta de carga de trabalho externa. Múltiplas políticas de federação num único principal de serviço são apropriadas apenas quando a mesma identidade lógica é autenticada através de diferentes fornecedores de identidade. Por exemplo, uma carga de trabalho que corre tanto no GitHub Actions como no Azure DevOps precisa de duas políticas, uma por fornecedor, no mesmo principal de serviço.

Não use múltiplas políticas para mapear diferentes cargas de trabalho (como pods Kubernetes separados por região) para um único principal de serviço. Em vez disso, crie um principal de serviço separado para cada carga de trabalho. Isto preserva a atribuição de registos de auditoria e permite-lhe revogar o acesso para uma carga de trabalho sem afetar outras.

Simplifique permissões com grupos

Quando vários principais de serviço precisarem das mesmas permissões, adicione-os como membros de um grupo Azure Databricks e atribua permissões ao grupo. Consulte as melhores práticas de Identidade.

Utilize-se a propriedade subject_claim para claims alternativos

Por padrão, o Azure Databricks usa a reivindicação sub do token de identidade para identificar a carga de trabalho. Se o seu fornecedor de identidade não usar o sub atributo como identificador estável de carga de trabalho, configure a propriedade subject_claim para o nome do atributo que o seu fornecedor utiliza. Para um exemplo, veja a configuração do CircleCI em Exemplo de políticas de federação do principal de serviço Databricks. .

Federação de tokens em toda a conta

Os administradores de conta podem configurar a federação de tokens OAuth na conta Azure Databricks usando uma política de federação de contas. Uma política de federação de contas permite que todos os utilizadores e principais de serviço na sua conta Azure Databricks acedam às APIs Databricks usando tokens do seu fornecedor de identidade. Uma política de federação de conta especifica:

• O fornecedor de identidade ou emissor do qual o Azure Databricks aceitará os tokens.
• Os critérios para mapear um token para o correspondente utilizador ou principal de serviço do Azure Databricks.

Por exemplo, dada uma política de federação com os seguintes campos:

• Emitente:https://idp.mycompany.com/oidc
• Audiências:databricks
• Reivindicação de assunto:sub

Use este corpo JWT para autenticar a Azure Databricks como username@mycompany.com:

{
  "iss": "https://idp.mycompany.com/oidc",
  "aud": "databricks",
  "sub": "username@mycompany.com"
}

Configurar uma política de federação de conta

Os administradores de contas podem configurar uma política de federação de contas usando a interface Azure Databricks, a CLI Databricks ou a API REST Databricks. Pode especificar um máximo de 20 políticas de federação de contas na sua conta Azure Databricks.

Para configurar uma política de federação de conta, você deve especificar o seguinte:

• URL do emissor: Um URL HTTPS que identifica seu provedor de identidade, especificado na iss declaração de seus tokens.

• Audiências: O destinatário pretendido do token, especificado na aud declaração. O token é considerado uma correspondência se seu público corresponder a pelo menos um público na política. Se não especificado, o predeterminado é o ID da sua conta Azure Databricks.

• Reivindicação de Sujeito: A reivindicação do token que contém o nome de utilizador do Azure Databricks do utilizador para o qual o token foi emitido. Se não for especificado, o padrão será sub.

• Validação de assinatura de token: (Opcional) As chaves públicas, ou sua URL, no formato JSON Web Key Sets (JWKS) usado para validar assinaturas de token. JWKS JSON suporta até 5 chaves. Se o seu provedor de identidade publicar mais informações, use um URI JWKS.

  Se não for especificado, Azure Databricks recupera as chaves do endpoint bem conhecido do emissor, que é a abordagem recomendada. Seu provedor de identidade deve fornecer Metadados de Provedor OpenID em <issuer-url>/.well-known/openid-configuration que incluam um jwks_uri especificando a localização das chaves públicas usadas para verificar assinaturas de token.

Interface do usuário do Databricks

1. Como administrador de conta, inicia sessão na consola da conta Azure Databricks em https://accounts.azuredatabricks.net.
2. Clique em Segurança e vá à aba Autenticação.
3. Em Políticas de federação, clique em Criar política.
4. Insira o URL do emissor, os públicos, a reivindicação de assunto e a validação opcional da assinatura do token.
5. Clique em Criar política.

CLI do Databricks

Não podes usar a CLI Databricks no espaço de trabalho Azure Databricks terminal web para criar uma política de federação.

1. Instale ou atualize para a versão mais recente da CLI do Databricks.

2. Como administrador de contas, autentique a sua conta Azure Databricks usando a linha de código. Especifique o ACCOUNT_CONSOLE_URL e o seu Azure Databricks ACCOUNT_ID.

   databricks auth login --host ${ACCOUNT_CONSOLE_URL} --account-id ${ACCOUNT_ID}
   

3. Crie a política de federação de contas. Por exemplo:

   databricks account federation-policy create --json \
   '{
     "oidc_policy": {
       "issuer": "https://idp.mycompany.com/oidc",
       "audiences": [
         "databricks"
       ],
       "subject_claim": "sub"
     }
   }'
   

API de conta Databricks

A seguinte chamada à API REST cria uma política de federação de contas. Especifique o ACCOUNT_CONSOLE_URL, o seu Azure Databricks ACCOUNT_ID e um portador TOKEN para autenticação.

curl --request POST \
  --header "Authorization: Bearer $TOKEN" \
  "${ACCOUNT_CONSOLE_URL}/api/2.0/accounts/${ACCOUNT_ID}/federationPolicies" \
  --data '{
    "oidc_policy": {
      "issuer": "https://idp.mycompany.com/oidc",
      "audiences": [
        "databricks"
      ],
      "subject_claim": "sub"
    }
  }'

Para obter a documentação completa de referência da API, consulte a API de política de federação de conta.

Exemplo de políticas de federação de conta

A tabela a seguir fornece exemplos de políticas de federação de conta e o corpo JWT correspondente.

Próximos passos

Depois de configurar uma política de federação para a sua conta:

• Configure o seu fornecedor de identidade (IdP) para gerar tokens que os seus utilizadores possam trocar com o Azure Databricks. Consulte a documentação do seu IdP para obter detalhes de configuração. Para obter instruções sobre como habilitar a federação de identidades de carga de trabalho com IdPs comuns, consulte Habilitar federação de identidades de carga de trabalho em CI/CD.
• Use um JWT do seu IdP para aceder à API do Azure Databricks, trocando primeiro por um token Azure Databricks OAuth. Inclua o token OAuth Azure Databricks no cabeçalho Bearer: da sua chamada API para completar o pedido. O JWT deve ser válido e assinado usando os algoritmos RS256 ou ES256. Para obter detalhes de implementação, consulte Autenticar com um token de provedor de identidade.