Compartir a través de

Configure una directiva de federación

La federación de tokens de OAuth de Databricks permite acceder de forma segura a las API de Databricks mediante tokens del proveedor de identidades (IdP). Para habilitar la federación de tokens de OAuth, debe configurar una directiva de federación, ya sea para toda la cuenta de Databricks o para procesos.

En esta página se describe cómo crear y configurar una directiva de federación de tokens de OAuth.

Federación de identidades de carga de trabajo

La federación de identidades de carga de trabajo permite que las cargas de trabajo automatizadas que se ejecutan fuera de Azure Databricks accedan a las APIs de Azure Databricks sin necesidad de los secretos de Azure Databricks. Los administradores de cuentas pueden configurar la federación de identidades de carga de trabajo mediante una directiva de federación de entidad de servicio.

Una directiva de federación de un service principal está asociada a un service principal en la cuenta de Azure Databricks y especifica:

  • Proveedor de identidad (o emisor) desde el que se puede autenticar la entidad de servicio.
  • Identidad de carga de trabajo (o sujeto) que tiene permiso para autenticarse como la entidad de servicio de Azure Databricks.

Por ejemplo, dada la siguiente directiva de federación de entidad de servicio para una carga de trabajo de Acciones de Github:

  • Emisor:https://token.actions.githubusercontent.com
  • Audiencias:https://github.com/my-github-org
  • Asunto:repo:my-github-org/my-repo:environment:prod

Puede usar este cuerpo JWT para autenticarse en Azure Databricks:

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

Configuración de una directiva de federación de entidad de servicio

Los administradores de cuentas pueden configurar una directiva de federación de entidad de servicio mediante la CLI de Databricks o la API de Databricks. Puede crear un máximo de 20 directivas de federación del principal de servicio por cada principal de servicio de Azure Databricks.

Para configurar una política de federación de un principal de servicio, debe especificar lo siguiente:

  • Dirección URL del emisor: Una dirección URL HTTPS que identifica al proveedor de identidades de carga de trabajo, especificada en la iss declaración de los tokens de identidad de carga de trabajo.

  • Asunto: Identificador único de la carga de trabajo en el entorno de tiempo de ejecución de la carga de trabajo. Si no se especifica, el valor predeterminado es sub.

  • Audiencias: Destinatario previsto del token, especificado en la aud declaración. El token se considera una coincidencia si su audiencia coincide con al menos una audiencia de la política. Si no se especifica, el valor predeterminado es el identificador de cuenta de Azure Databricks.

  • Reclamación del sujeto: (Opcional) Especifica la reclamación de token que contiene la identidad de la carga de trabajo (también denominada sujeto) del token. Si no se establece, Azure Databricks usa sub de forma predeterminada. Databricks recomienda mantener la declaración predeterminada sub para la federación de identidad de carga de trabajo. Solo elija una afirmación diferente si sub no es un identificador de sujeto adecuado o estable, lo cual es raro. Para obtener más información, consulte Ejemplo de directivas de federación de principales de servicio.

  • Validación de firma de token: (opcional) Las claves públicas, o su dirección URL, en formato JSON Web Key Sets (JWKS) usado para validar firmas de token. JWKS JSON admite hasta 5 claves. Si el proveedor de identidades publica más, use un URI de JWKS en su lugar.

    Si no se especifica, Azure Databricks recupera las claves del punto de conexión conocido del emisor, que es el enfoque recomendado. El proveedor de identidad debe servir los metadatos del proveedor OpenID en <issuer-url>/.well-known/openid-configuration que incluya un jwks_uri que especifique la ubicación de las claves públicas usadas para comprobar las firmas de los tokens.

Interfaz de usuario de Databricks

  1. Como administrador de la cuenta, inicie sesión en la consola de la cuenta de Azure Databricks en https://accounts.azuredatabricks.net.
  2. Haga clic en Administración de usuarios.
  3. Vaya a la pestaña Entidades de servicio.
  4. Seleccione el principal de servicio para el que desea crear la directiva.
  5. Vaya a la pestaña Credenciales y secretos .
  6. En la pestaña Directivas de federación , haga clic en Crear directiva.
  7. Seleccione un proveedor de credenciales federada y configure los campos correspondientes.
  8. Haga clic en Crear directiva.

CLI de Databricks

No puede usar la CLI de Databricks en el área de trabajo de Azure Databricks terminalweb para crear una directiva de federación.

  1. Instale o actualice a la versión más reciente de la CLI de Databricks.

  2. Como administrador de la cuenta, autentíquese en la cuenta de Azure Databricks mediante la CLI. Especifique el ACCOUNT_CONSOLE_URL y su Azure Databricks ACCOUNT_ID:

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

  3. Obtenga el identificador numérico del principal de servicio al que se aplicará la política de federación. (Por ejemplo, 3659993829438643.)

    Si conoce el identificador de aplicación de la entidad de servicio (normalmente un valor GUID, como bc3cfe6c-469e-4130-b425-5384c4aa30bb) de antemano, puede determinar el identificador numérico de la entidad de servicio mediante la CLI de Databricks:

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

  4. Cree la directiva de federación de la entidad de servicio. Este es un ejemplo de creación de una directiva de federación para una acción de 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 cuenta de Databricks

  1. Obtenga el identificador numérico del principal de servicio (por ejemplo, 3659993829438643) desde la consola de la cuenta o mediante la API de Principales de Servicio.

  2. Cree la directiva de federación de la entidad de servicio. Especifique el ACCOUNT_CONSOLE_URL, el Azure Databricks ACCOUNT_ID, el SERVICE_PRINCIPAL_NUMERIC_ID y un portador TOKEN para la autenticación:

    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 obtener la documentación completa de referencia de la API, consulte la API de la Política de Federación de Cuentas.

Ejemplo de políticas de federación de principal de servicio de Databricks

En la tabla siguiente se proporcionan directivas de federación de principal del servicio a modo de ejemplo y el cuerpo de JWT correspondiente.

Para ver los pasos de configuración completos para habilitar la federación de identidades de carga de trabajo para algunos de estos proveedores de identidades comunes, consulte Habilitación de la federación de identidades de carga de trabajo en CI/CD.

Tool Directiva de federación Ejemplo de token coincidente
Acciones de GitHub Emisor:https://token.actions.githubusercontent.comAudiencia:https://github.com/<github-org>Asunto: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 Emisor:https://kubernetes.default.svcAudiencia:https://kubernetes.default.svcAsunto: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 Emisor:https://vstoken.dev.azure.com/<org_id>Audiencia:api://AzureADTokenExchangeAsunto: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 Emisor:https://gitlab.example.comAudiencia:https://gitlab.example.comAsunto:project_path:my-group/my-project:... { "iss": "https://gitlab.example.com", "aud": "https://gitlab.example.com", "sub": "project_path:my-group/my-project:..." }
CircleCI Emisor:https://oidc.circleci.com/org/<org_id>Audiencia:<org_id>Asunto:7cc1d11b-46c8-4eb2-9482-4c56a910c7ceReclamación del asunto: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" }

Procedimientos recomendados para las directivas de federación de entidades de servicio

Cada principal de servicio admite un máximo de 20 directivas de federación. Siga estas instrucciones para evitar alcanzar ese límite.

Mapear una identidad externa por cada entidad de servicio

Cree una entidad de servicio dedicada para cada identidad de carga de trabajo externa distinta. Varias directivas de federación en un solo principal de servicio solo son adecuadas cuando la misma identidad lógica se autentica a través de diferentes proveedores de identidades. Por ejemplo, una carga de trabajo que se ejecuta en Acciones de GitHub y Azure DevOps necesita dos directivas, una por proveedor, en la misma entidad de servicio.

No utilice varias directivas para asignar diferentes cargas de trabajo (como pods de Kubernetes por separado por región) a un solo servicio principal. En su lugar, cree un servicio principal independiente para cada carga de trabajo. Esto conserva la atribución del registro de auditoría y le permite revocar el acceso para una carga de trabajo sin afectar a otros usuarios.

Simplificación de los permisos con grupos

Cuando varias entidades de servicio necesitan los mismos permisos, agréguelos como miembros de un grupo de Azure Databricks y asigne permisos al grupo. Consulte Procedimientos recomendados de identidad.

Utilice la subject_claim propiedad para reclamaciones alternativas

De forma predeterminada, Azure Databricks usa la afirmación del token de identidad sub para identificar la carga de trabajo. Si el proveedor de identidades no utiliza la sub declaración como identificador de carga de trabajo estable, configure la propiedad subject_claim al nombre de declaración que utiliza el proveedor. Para obtener un ejemplo, consulte la configuración de CircleCI en Las directivas de federación de entidad de servicio de Databricks de ejemplo. .

Federación de tokens para toda la cuenta

Los administradores de cuentas pueden configurar la federación de tokens de OAuth en la cuenta de Azure Databricks mediante una directiva de federación de cuentas. Una directiva de federación de cuenta permite que todos los usuarios y entidades de servicio de la cuenta de Azure Databricks accedan a las API de Databricks mediante tokens del proveedor de identidades. Una política de federación de cuentas especifica:

  • Proveedor de identidades o emisor del que Azure Databricks aceptará tokens.
  • Criterios para asignar un token al usuario o entidad de servicio correspondiente de Azure Databricks.

Por ejemplo, dada una directiva de federación con los campos siguientes:

  • Emisor:https://idp.mycompany.com/oidc
  • Audiencias:databricks
  • Reclamación del asunto:sub

Use este cuerpo de JWT para autenticarse en Azure Databricks como username@mycompany.com:

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

Configurar una directiva de federación de cuenta

Los administradores de cuentas pueden configurar una directiva de federación de cuentas mediante la interfaz de usuario de Azure Databricks, la CLI de Databricks o la API rest de Databricks. Puede especificar un máximo de 20 directivas de federación de cuenta en la cuenta de Azure Databricks.

Para configurar una directiva de federación de cuenta, debe especificar lo siguiente:

  • Dirección URL del emisor: Una URL HTTPS que identifica a tu proveedor de identidad, especificada en el issclam de tus tokens.

  • Audiencias: Destinatario previsto del token, especificado en la aud declaración. El token se considera una coincidencia si su audiencia coincide con al menos una audiencia de la política. Si no se especifica, el valor predeterminado es el identificador de cuenta de Azure Databricks.

  • Subject claim: La reclamación del token que contiene el nombre de usuario de Azure Databricks del usuario para el que se emitió el token. Si no se especifica, el valor predeterminado es sub.

  • Validación de firma de token: (opcional) Las claves públicas, o su dirección URL, en formato JSON Web Key Sets (JWKS) usado para validar firmas de token. JWKS JSON admite hasta 5 claves. Si el proveedor de identidades publica más, use un URI de JWKS en su lugar.

    Si no se especifica, Azure Databricks recupera las claves del punto de conexión conocido del emisor, que es el enfoque recomendado. El proveedor de identidad debe servir los metadatos del proveedor OpenID en <issuer-url>/.well-known/openid-configuration que incluya un jwks_uri que especifique la ubicación de las claves públicas usadas para comprobar las firmas de los tokens.

Important

Para la federación a nivel de cuenta, registre únicamente los IdP que estén completamente administrados y en los que su organización confíe, como el IdP propio de su empresa. No configure la federación de toda la cuenta con idP externos que no controle, como los administrados por clientes o asociados.

Interfaz de usuario de Databricks

  1. Como administrador de la cuenta, inicie sesión en la consola de la cuenta de Azure Databricks en https://accounts.azuredatabricks.net.
  2. Haga clic en Seguridad y vaya a la pestaña Autenticación .
  3. En Directivas de federación, haga clic en Crear directiva.
  4. Escriba la dirección URL del emisor, las audiencias, la reclamación del sujeto y la validación opcional de la firma del token.
  5. Haga clic en Crear directiva.

CLI de Databricks

No puede usar la CLI de Databricks en el área de trabajo de Azure Databricks terminalweb para crear una directiva de federación.

  1. Instale o actualice a la versión más reciente de la CLI de Databricks.

  2. Como administrador de la cuenta, autentíquese en la cuenta de Azure Databricks mediante la CLI. Especifique el ACCOUNT_CONSOLE_URL y el Azure Databricks ACCOUNT_ID.

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

  3. Cree la directiva de federación de cuentas. Por ejemplo:

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

API de cuenta de Databricks

La siguiente llamada a la API REST crea una directiva de federación de cuenta. Especifique el ACCOUNT_CONSOLE_URL, el Azure Databricks ACCOUNT_ID y un portador TOKEN para la autenticación.

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 obtener la documentación completa de referencia de la API, consulte la API de la Política de Federación de Cuentas.

Políticas de federación de cuentas de ejemplo

La siguiente tabla proporciona ejemplos de directivas de federación de cuentas y el cuerpo de JWT correspondiente.

Directiva de federación Ejemplo de token coincidente
Emisor:https://idp.mycompany.com/oidcAudiencia:2ff814a6-3304-4ab8-85cb-cd0e6f879c1d { "iss": "https://idp.mycompany.com/oidc", "aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "sub": "username@mycompany.com" }
Emisor:https://idp.mycompany.com/oidcAudiencia:2ff814a6-3304-4ab8-85cb-cd0e6f879c1dDeclaración del sujeto: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" }
Emisor:https://idp.mycompany.com/oidcAudiencia: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" } (firma comprobada mediante la clave pública en la directiva)
Emisor:https://idp.mycompany.com/oidcAudiencia:2ff814a6-3304-4ab8-85cb-cd0e6f879c1dURI de JWKS:https://idp.mycompany.com/jwks.json { "iss": "https://idp.mycompany.com/oidc", "aud": "2ff814a6-3304-4ab8-85cb-cd0e6f879c1d", "sub": "username@mycompany.com" } (firma comprobada mediante la clave pública capturada de jwks_uri)

Pasos siguientes

Después de configurar una directiva de federación para la cuenta:

  • Configure el proveedor de identidades (IdP) para generar tokens que los usuarios puedan intercambiar con Azure Databricks. Consulte la documentación del IdP para obtener más información sobre la configuración. Para obtener instrucciones para habilitar la federación de identidades de carga de trabajo con idP comunes, consulte Habilitación de la federación de identidades de carga de trabajo en CI/CD.
  • Use un JWT desde el IdP para acceder a la API de Azure Databricks intercambiando primero por un token de OAuth de Azure Databricks. Incluya el token de OAuth Azure Databricks en el encabezado Bearer: de la llamada API para completar la solicitud. El JWT debe ser válido y firmado mediante los algoritmos RS256 o ES256. Para más información sobre la implementación, consulte Autenticación con un token de proveedor de identidades.
  • Last updated on