Autenticar o acesso ao Databricks usando a federação de tokens OAuth

Este artigo orienta o senhor na configuração da federação OAuth para acessar Databricks account e workspace recurso usando tokens do seu provedor de identidade.

O que é a federação de tokens OAuth da Databricks?

Databricks OAuth A federação de tokens permite que o senhor acesse com segurança Databricks APIs usando tokens do seu provedor de identidade (IdP). OAuth A federação de tokens elimina a necessidade de gerenciar segredos Databricks, como acesso pessoal tokens e Databricks OAuth segredos de clientes.

Usando a federação de tokens Databricks OAuth , os usuários e a entidade de serviço trocam JWT (JSON Web tokens) tokens do seu provedor de identidade por Databricks OAuth tokens, que pode ser usado para acessar Databricks APIs.

A Databricks oferece suporte a dois tipos de federação de tokens:

  • A federação de tokens em toda a conta permite que todos os usuários e entidades de serviço do seu Databricks account acessem o Databricks APIs usando o tokens do seu provedor de identidade. A federação de tokens em toda a conta permite centralizar o gerenciamento das políticas de emissão de tokens no provedor de identidade e, normalmente, é usada em combinação com SCIM, para que os usuários do provedor de identidade sejam sincronizados com o Databricks account.

  • A federação de identidade de carga de trabalho permite que suas cargas de trabalho automatizadas executadas fora do Databricks acessem as APIs do Databricks sem a necessidade de segredos do Databricks. Com a federação de identidade de carga de trabalho, seu aplicativo (carga de trabalho) se autentica na Databricks como uma entidade de serviço da Databricks usando tokens emitidos pelo tempo de execução da carga de trabalho.

Federação de tokens em toda a conta

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

  • O provedor de identidade ou emissor do qual a Databricks aceitará tokens.

  • Os critérios para mapear um token para o usuário ou entidade de serviço correspondente em Databricks.

Para configurar uma política de federação account, forneça o seguinte:

  • O emissor de tokens necessário, especificado na declaração iss do seu tokens. O emissor é um URL HTTPS que identifica seu provedor de identidade.

  • Os públicos de tokens permitidos, especificados na declaração aud do seu tokens. Esse identificador representa o destinatário dos tokens. Desde que o público nos tokens corresponda a pelo menos um público na política, os tokens são considerados correspondentes. Se não for especificado, o valor default será sua ID Databricks account .

  • A reivindicação em questão. Isso indica qual reivindicação de tokens contém o nome de usuário Databricks do usuário para o qual os tokens foram emitidos. Se não for especificado, o valor de default é sub.

  • Opcionalmente, a chave pública usada para validar a assinatura do seu tokens, no formato JSON Web key Sets (JWKS). Se não for especificado (recomendado), o site Databricks obtém automaticamente a chave pública do conhecido site do emissor endpoint. Databricks recomenda enfaticamente que o senhor confie no conhecido site endpoint do emissor para descobrir a chave pública.

    Observação

    Se você não especificar um JWKS em sua política de federação (recomendado), seu provedor de identidade deverá fornecer metadados do provedor OpenID em {issuer-url}/.well-known/openid-configuration. Os metadados do provedor OpenID devem incluir um jwks_uri que especifique o local da chave pública usada para verificar as assinaturas dos tokens.

A seguir, um exemplo de política de federação account:

issuer: "https://idp.mycompany.com/oidc"
audiences: ["databricks"]
subject_claim: "sub"

O exemplo de corpo JWT a seguir corresponde à política acima e pode ser usado para autenticar a Databricks como usuário username@mycompany.com:

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

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

Os administradores de conta podem configurar uma política de federação account usando o comando Databricks CLI (versão 0.239.0 e acima) ou o Databricks API. O senhor pode especificar até cinco políticas de federação account em seu Databricks account.

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

  2. Como administrador do account, autentique-se em seu Databricks account usando o CLI. Especificar a conta (por exemplo, https://accounts.cloud.databricks.com) e sua conta Databricks:

    databricks auth login --host ${ACCOUNT_CONSOLE_URL} --account-id ${ACCOUNT_ID}
    
  3. Crie a política de federação account. Por exemplo:

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

A seguir, um exemplo de chamada Databricks REST API para criar uma política de federação account:

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"
    }
  }'

Talvez seja necessário configurar seu provedor de identidade para gerar tokens para seus usuários trocarem com a Databricks. Consulte a documentação do seu provedor de identidade para obter instruções.

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

Política da federação

Exemplo de tokens correspondentes

issuer: "https://idp.mycompany.com/oidc"

audiences: ["2ff814a6-3304-4ab8-85cb-cd0e6f879c1d"]

{

  "iss": "https://idp.mycompany.com/oidc",

  "aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d",

  "sub": "username@mycompany.com"

}

issuer: "https://idp.mycompany.com/oidc"

audiences: ["2ff814a6-3304-4ab8-85cb-cd0e6f879c1d"]

subject_claim: "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"

}

issuer: "https://idp.mycompany.com/oidc"

audiences: ["2ff814a6-3304-4ab8-85cb-cd0e6f879c1d"]

jwks_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"

}

(signature verified using public key in policy)

issuer: "https://idp.mycompany.com/oidc"

audiences: ["2ff814a6-3304-4ab8-85cb-cd0e6f879c1d"]

jwks_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"

}

(signature verified using public key in policy)

Federação de identidades de carga de trabalho

A federação de identidade de carga de trabalho permite que suas cargas de trabalho automatizadas executadas fora do Databricks acessem as APIs do Databricks sem a necessidade de segredos do Databricks. Os administradores de conta podem configurar a federação de identidade 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 em seu site Databricks account e especifica:

  • O provedor de identidade (ou emissor) do qual a entidade de serviço pode se autenticar.

  • A identidade (ou assunto) da carga de trabalho que tem permissão para se autenticar como a entidade de serviço Databricks.

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

  • O emissor dos tokens necessários, especificado na reivindicação iss da identidade da carga de trabalho tokens. O emissor é um URL HTTPS que identifica o provedor de identidade da carga de trabalho.

  • Os tokens necessários, especificados na reivindicação da sub identidade da carga de tokens trabalho. O assunto identifica de forma exclusiva a carga de trabalho no ambiente de execução da carga de trabalho.

  • Os públicos de tokens permitidos, especificados na reivindicação aud da identidade da carga de trabalho tokens. O público representa o destinatário dos tokens. Desde que o público nos tokens corresponda a pelo menos um público na política, os tokens são considerados correspondentes. Se não for especificado, o valor default será sua ID Databricks account .

  • Opcionalmente, a chave pública usada para validar a assinatura da identidade da carga de trabalho tokens, no formato JSON Web key Sets (JWKS). Se não for especificado (recomendado), o site Databricks obtém automaticamente a chave pública do conhecido site do emissor endpoint. Databricks recomenda fortemente que o senhor confie no conhecido site endpoint do emissor para descobrir a chave pública.

  • Opcionalmente, a reivindicação em questão. Isso indica qual reivindicação de tokens contém a identidade da carga de trabalho (ou assunto) dos tokens. Se não for especificado, o valor de default é sub. Databricks recomenda enfaticamente o uso da declaração default sub para federação de identidade de carga de trabalho. Uma afirmação diferente de sub só deve ser usada nos casos em que a afirmação sub não é um identificador de assunto apropriado ou estável, o que é incomum. Para obter detalhes, consulte o exemplo de políticas de federação de entidades de serviço abaixo.

    Observação

    Se você não especificar um JWKS em sua política de federação (recomendado), seu provedor de identidade deverá fornecer metadados do provedor OpenID em {issuer-url}/.well-known/openid-configuration. Os metadados do provedor OpenID devem incluir um jwks_uri que especifique o local da chave pública usada para verificar as assinaturas dos tokens.

A seguir, um exemplo de política de federação de entidades de serviço para uma carga de trabalho GitHub Actions:

issuer: "https://token.actions.githubusercontent.com"
audiences: ["https://github.com/my-github-org"]
subject: "repo:my-github-org/my-repo:environment:prod"

O exemplo de corpo JWT a seguir corresponde à política acima e pode ser usado para autenticar a 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 de entidade de serviço

Os administradores de conta podem configurar uma política de federação de entidade de serviço usando o Databricks CLI (versão 0.239.0 e acima) ou o site Databricks API. O senhor pode criar até cinco políticas de federação de entidade de serviço por entidade de serviço da Databricks.

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

  2. Como administrador do account, autentique-se em seu Databricks account usando o CLI. Especificar a conta (por exemplo, https://accounts.cloud.databricks.com) e sua conta Databricks:

    databricks auth login --host ${ACCOUNT_CONSOLE_URL} --account-id ${ACCOUNT_ID}
    
  3. Crie a política de federação da entidade de serviço, especificando o ID do aplicativo da entidade de serviço (por exemplo, 3659993829438643). A seguir, um exemplo de uma carga de trabalho GitHub Actions:

    databricks account service-principal-federation-policy create ${SERVICE_PRINCIPAL_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"
      }
    }'
    

A seguir, um exemplo de chamada Databricks REST API para criar uma política para uma carga de trabalho GitHub Actions:

curl --request POST \
  --header "Authorization: Bearer $TOKEN" \
  "https://accounts.cloud.databricks.com/api/2.0/accounts/${ACCOUNT_ID}/servicePrincipals/${SERVICE_PRINCIPAL_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"
    }
  }'

Exemplo Databricks account e políticas de federação de entidades de serviço

Ferramenta

Política da federação

Exemplo de tokens correspondentes

GitHub Actions

issuer: "https://token.actions.githubusercontent.com"

audiences: ["https://github.com/<github-org>"]

subject: "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

issuer: "https://kubernetes.default.svc"

audiences: ["https://kubernetes.default.svc"]

subject: "system:serviceaccount:namespace:podname"

jwks 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

issuer: "https://vstoken.dev.azure.com/<org_id>"

audiences: ["api://AzureADTokenExchange"]

subject: "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

issuer: "https://gitlab.example.com"

audiences: ["https://gitlab.example.com"]

subject: "project_path:my-group/my-project:..."

{

  "iss": "https://gitlab.example.com",

  "aud": "https://gitlab.example.com",

  "sub": "project_path:my-group/my-project:..."

}

Círculo CI

issuer: "https://oidc.circleci.com/org/<org_id>"

audiences: ["<org_id>"]

subject: "7cc1d11b-46c8-4eb2-9482-4c56a910c7ce"

subject_claim: "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"

}

Depois de configurar uma política de federação para o seu account, o senhor pode usar um JWT do seu provedor de identidade para acessar o Databricks API. Para isso, primeiro troque os tokens JWT do seu provedor de identidade por tokens Databricks OAuth e, em seguida, use os tokens Databricks OAuth no campo Bearer: da chamada API para obter acesso e concluir a chamada. Os tokens devem ser JWTs válidos e assinados usando os algoritmos RS256 ou ES256.

Para obter orientação sobre esse processo, consulte Usar tokens de um provedor de identidade para autenticar em Databricks.