Compartilhar via

Configurar uma política de federação

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

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

Federação de identidade de carga de trabalho

A federação de identidade de carga de trabalho permite que suas cargas de trabalho automatizadas em execução fora do Azure Databricks acessem APIs do Azure Databricks sem a necessidade de segredos do Azure Databricks. Os administradores de conta podem configurar a federação de identidade de carga de trabalho usando uma política de federação da entidade de serviço.

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

  • O provedor de identidade (ou emissor) do qual a entidade de serviço pode autenticar-se.
  • A identidade de carga de trabalho (ou sujeito) que tem permissão para se autenticar como o principal de serviço do Azure Databricks.

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

  • Emissor:https://token.actions.githubusercontent.com
  • Público:https://github.com/my-github-org
  • Assunto:repo:my-github-org/my-repo:environment:prod

Você pode usar esse 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 da entidade de serviço usando a CLI do Databricks ou a API do Databricks. Você pode criar no máximo 20 políticas de federação de entidade de serviço por entidade de serviço do Azure Databricks.

Para configurar uma política de federação de entidade de serviço, especifique o seguinte:

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

  • Assunto: O identificador exclusivo da carga de trabalho no ambiente de runtime da carga de trabalho. Se não for especificado, o padrão será sub.

  • Público: O destinatário pretendido do token, especificado na declaração aud . O token será considerado uma correspondência se seu público-alvo corresponder a pelo menos uma audiência na política. Se não for especificado, o padrão é a ID da conta do 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, o Azure Databricks usará sub por padrão. O Databricks recomenda manter a declaração padrão sub para federação de identidade 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 JWKS (Conjuntos de Chaves Web JSON) usados para validar assinaturas de token. JWKS JSON dá suporte a até 5 chaves. Se o provedor de identidade divulgar mais informações, use um URI do JWKS.

    Se não for especificado, o Azure Databricks recuperará as chaves do ponto de extremidade conhecido do emissor, que é a abordagem recomendada. Seu provedor de identidade deve disponibilizar os Metadados do Provedor OpenID em <issuer-url>/.well-known/openid-configuration, que incluem uma jwks_uri especificando o local das chaves públicas usadas para verificar as assinaturas de token.

Interface do usuário do Databricks

  1. Como administrador de conta, entre no console da conta do Azure Databricks em https://accounts.azuredatabricks.net.
  2. Clique no gerenciamento de usuários.
  3. Vá para a guia Entidades de Serviço .
  4. Selecione a entidade de serviço para a qual criar a política.
  5. Vá para a guia Credenciais > segredos .
  6. Na guia Políticas de Federação , clique em Criar política.
  7. Selecione um provedor de credencial federado e configure os campos correspondentes.
  8. Clique em Criar política.

CLI do Databricks

Você não pode usar a CLI do Azure Databricks no terminal Web do workspace do Azure Databricks para criar uma política de federação.

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

  2. Como administrador de conta, autentique-se em sua conta do Azure Databricks usando a CLI. Especifique o ACCOUNT_CONSOLE_URL e o seu ACCOUNT_ID do Azure Databricks:

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

  3. Obtenha a ID numérica do principal de serviço que terá a política de federação aplicada. (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 do 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:

    curl --request POST \
  --header "Authorization: Bearer $TOKEN" \
  "https://accounts.cloud.databricks.com/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 de referência completa da API, consulte a API de Política de Federação de Contas.

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

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

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

Tool Política de federação Exemplo de token correspondente
Ações do GitHub Emissor:https://token.actions.githubusercontent.comPúblico:https://github.com/<github-org>Assunto:repo:<github-org>/<repo>:environment:prod { "iss": "https://token.actions.githubusercontent.com", "aud": "https://github.com/<github-org>", "sub": "repo:<github-org>/<repo>:environment:prod" }
Kubernetes Emissor:https://kubernetes.default.svcPúblico:https://kubernetes.default.svcAssunto:system:serviceaccount:namespace:podnameJWKS JSON:{"keys":[{"kty":"rsa","e":"AQAB","use":"sig","kid":"<key-id>","alg":"RS256","n":"uPUViFv..."}]} { "iss": "https://kubernetes.default.svc", "aud": ["https://kubernetes.default.svc"], "sub": "system:serviceaccount:namespace:podname" }
Azure DevOps Emissor:https://vstoken.dev.azure.com/<org_id>Público:api://AzureADTokenExchangeAssunto:sc://my-org/my-project/my-connection { "iss": "https://vstoken.dev.azure.com/<org_id>", "aud": "api://AzureADTokenExchange", "sub": "sc://my-org/my-project/my-connection" }
GitLab Emissor:https://gitlab.example.comPúblico:https://gitlab.example.comAssunto:project_path:my-group/my-project:... { "iss": "https://gitlab.example.com", "aud": "https://gitlab.example.com", "sub": "project_path:my-group/my-project:..." }
CircleCI Emissor:https://oidc.circleci.com/org/<org_id>Público:<org_id>Assunto:7cc1d11b-46c8-4eb2-9482-4c56a910c7ceDeclaração de assunto:oidc.circleci.com/project-id { "iss": "https://oidc.circleci.com/org/<org_id>", "aud": "<org_id>", "oidc.circleci.com/project-id": "7cc1d11b-46c8-4eb2-9482-4c56a910c7ce" }

Federação de tokens abrangendo toda a conta

Os administradores de conta podem configurar a federação de token OAuth na conta do Azure Databricks usando uma política de federação de conta. Uma política de federação de conta permite que todos os usuários e entidades de serviço em sua conta do Azure Databricks acessem APIs do Databricks usando tokens do provedor de identidade. Uma política de federação de conta especifica:

  • O provedor de identidade ou emissor do qual o Azure Databricks aceitará tokens.
  • Os critérios para mapear um token ao usuário ou principal de serviço correspondente do Azure Databricks.

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

  • Emissor:https://idp.mycompany.com/oidc
  • Público:databricks
  • Declaração de assunto:sub

Use este corpo JWT para autenticar no 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 conta podem configurar uma política de federação de conta usando a interface do usuário do Azure Databricks, a CLI do Databricks ou a API REST do Databricks. Você pode especificar um máximo de 20 políticas de federação de conta em sua conta do Azure Databricks.

Para configurar uma política de federação de conta, especifique o seguinte:

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

  • Público: O destinatário pretendido do token, especificado na declaração aud . O token será considerado uma correspondência se seu público-alvo corresponder a pelo menos uma audiência na política. Se não for especificado, o padrão é a ID da conta do Azure Databricks.

  • Declaração de assunto: A declaração de token que contém o nome de usuário do Azure Databricks do usuário 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 JWKS (Conjuntos de Chaves Web JSON) usados para validar assinaturas de token. JWKS JSON dá suporte a até 5 chaves. Se o provedor de identidade divulgar mais informações, use um URI do JWKS.

    Se não for especificado, o Azure Databricks recuperará as chaves do ponto de extremidade conhecido do emissor, que é a abordagem recomendada. Seu provedor de identidade deve disponibilizar os Metadados do Provedor OpenID em <issuer-url>/.well-known/openid-configuration, que incluem uma jwks_uri especificando o local das chaves públicas usadas para verificar as assinaturas de token.

Important

Para federação em toda a conta, registre apenas IdPs totalmente gerenciados e confiáveis pela sua organização, como o próprio IdP da sua empresa. Não configure a federação em toda a conta com IdPs externos que você não controla, como aqueles gerenciados por clientes ou parceiros.

Interface do usuário do Databricks

  1. Como administrador de conta, entre no console da conta do Azure Databricks em https://accounts.azuredatabricks.net.
  2. Clique em Configurações e vá para a guia Autenticação .
  3. Nas políticas de Federação, clique em Criar política.
  4. Insira a URL do emissor, o público-alvo, a declaração do assunto e a validação de assinatura de token opcional.
  5. Clique em Criar política.

CLI do Databricks

Você não pode usar a CLI do Azure Databricks no terminal Web do workspace do Azure Databricks 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 conta, autentique-se em sua conta do Azure Databricks usando a CLI. 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 do Databricks

A seguinte chamada à API REST do Azure Databricks cria uma política de federação de conta:

curl --request POST \
  --header "Authorization: Bearer $TOKEN" \
  "https://accounts.cloud.databricks.com/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 de referência completa da API, consulte a API de Política de Federação de Contas.

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

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

Política de federação Exemplo de token correspondente
Emissor:https://idp.mycompany.com/oidcPúblico:2ff814a6-3304-4ab8-85cb-cd0e6f879c1d { "iss": "https://idp.mycompany.com/oidc", "aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "sub": "username@mycompany.com" }
Emissor:https://idp.mycompany.com/oidcPúblico:2ff814a6-3304-4ab8-85cb-cd0e6f879c1dDeclaração de assunto:preferred_username { "iss": "https://idp.mycompany.com/oidc", "aud": ["2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "other-audience"], "preferred_username": "username@mycompany.com", "sub": "some-other-ignored-value" }
Emissor:https://idp.mycompany.com/oidcPúblico:2ff814a6-3304-4ab8-85cb-cd0e6f879c1dJWKS JSON:{"keys":[{"kty":"RSA","e":"AQAB","use":"sig","kid":"<key-id>","alg":"RS256","n":"uPUViFv..."}]} { "iss": "https://idp.mycompany.com/oidc", "aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "sub": "username@mycompany.com" } (assinatura verificada usando chave pública na política)
Emissor:https://idp.mycompany.com/oidcPúblico:2ff814a6-3304-4ab8-85cb-cd0e6f879c1dURI JWKS:https://idp.mycompany.com/jwks.json { "iss": "https://idp.mycompany.com/oidc", "aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "sub": "username@mycompany.com" } (assinatura verificada usando a chave pública buscada de jwks_uri)

Próximas etapas

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

  • Configure seu IdP (provedor de identidade) para gerar tokens que seus usuários podem trocar com o Azure Databricks. Consulte a documentação do IdP para obter detalhes da instalação. Para obter instruções para habilitar a federação de identidade de carga de trabalho com IdPs comuns, consulte Habilitar a federação de identidade de carga de trabalho em CI/CD.
  • Use um JWT do seu IdP para acessar a API do Azure Databricks trocando-a primeiro por um token OAuth do Azure Databricks. Inclua o token OAuth do Azure Databricks no Bearer: cabeçalho da sua chamada à API para concluir a solicitação. 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.
  • Last updated on