Partilhar via

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 suas cargas de trabalho automatizadas executadas 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 identidades de carga de trabalho usando uma política de federação de entidade de serviço.

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

  • O provedor de identidade (ou emissor) a partir do qual a entidade de serviço pode autenticar.
  • A identidade (ou sujeito) da carga de trabalho que tem permissão para se autenticar como a entidade de 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

Você 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 da entidade de serviço usando a CLI do Databricks ou a API do Databricks. Você pode criar um máximo de 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 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 da carga de trabalho no ambiente de tempo de execução da carga de trabalho. 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 for especificado, o padrão será sua ID de 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 usa sub por padrão. 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, o Azure Databricks obtém as chaves a partir 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, entre no console de conta do Azure Databricks em https://accounts.azuredatabricks.net.
  2. Clique em 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 credenciais federadas e configure os campos correspondentes.
  8. Clique em Criar política.

CLI do Databricks

Não é possível usar a CLI do Azure Databricks no terminal Web do espaço de trabalho 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 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:

    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 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.

Tool Política de federação Exemplo de token correspondente
Ações do GitHub Emitente:https://token.actions.githubusercontent.comPúblico-alvo: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 Emitente:https://kubernetes.default.svcPúblico-alvo: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 Emitente:https://vstoken.dev.azure.com/<org_id>Público-alvo: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 Emitente:https://gitlab.example.comPúblico-alvo: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 Emitente:https://oidc.circleci.com/org/<org_id>Público-alvo:<org_id>Assunto:7cc1d11b-46c8-4eb2-9482-4c56a910c7ceReivindicação do 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 em toda a conta

Os administradores de conta podem configurar a federação de tokens 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 seu provedor de identidade. Uma política de federação de conta especifica:

  • O provedor ou emissor de identidade a partir do qual o Azure Databricks aceitará tokens.
  • Os critérios para mapear um token para o utilizador ou principal de serviço correspondente no 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 do 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, 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 for especificado, o padrão será sua ID de conta do Azure Databricks.

  • Reivindicação do 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 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, o Azure Databricks obtém as chaves a partir 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.

Important

Para federação em toda a conta, registre apenas IdPs que sejam totalmente gerenciados e confiáveis pela sua organização, como o IdP da sua própria empresa. Não configure a federação de 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 de conta do Azure Databricks em https://accounts.azuredatabricks.net.
  2. Clique em Configurações e vá para a guia Autenticação .
  3. Em Políticas de federação, clique em Criar política.
  4. Insira o URL do emissor, as audiências, a declaração de assunto e a validação opcional da assinatura de token.
  5. Clique em Criar política.

CLI do Databricks

Não é possível usar a CLI do Azure Databricks no terminal Web do espaço de trabalho 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 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 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.

Política de federação Exemplo de token correspondente
Emitente:https://idp.mycompany.com/oidcPúblico-alvo:2ff814a6-3304-4ab8-85cb-cd0e6f879c1d { "iss": "https://idp.mycompany.com/oidc", "aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "sub": "username@mycompany.com" }
Emitente:https://idp.mycompany.com/oidcPúblico-alvo:2ff814a6-3304-4ab8-85cb-cd0e6f879c1dReivindicação do 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" }
Emitente:https://idp.mycompany.com/oidcPúblico-alvo: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)
Emitente:https://idp.mycompany.com/oidcPúblico-alvo:2ff814a6-3304-4ab8-85cb-cd0e6f879c1dJWKS URI: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 chave pública obtida de jwks_uri)

Próximos passos

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

  • Configure seu provedor de identidade (IdP) para gerar tokens que seus usuários podem 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 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 de 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