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 API de Azure Databricks sin necesidad de 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 política de federación de entidad de servicio está asociada a una entidad de servicio en tu cuenta de Azure Databricks y especifica:

  • Proveedor de identidad (o emisor) desde el que se puede autenticar la entidad de servicio.
  • La identidad de carga de trabajo (o sujeto) que tiene permiso para autenticarse como principal 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 de entidad de servicio por entidad de servicio de Azure Databricks.

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

  • Dirección URL del emisor: Dirección URL HTTPS que identifica el proveedor de identidades de carga de trabajo, especificado en la iss notificación de 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 notificación. El token se considera una coincidencia si su audiencia coincide al menos con una audiencia de la directiva. Si no se especifica, el valor predeterminado es el identificador de cuenta de Azure Databricks.

  • Notificación del firmante: (opcional) Especifica la notificación de token que contiene la identidad de carga de trabajo (también denominada asunto) del token. Si no se establece, Azure Databricks usa sub de forma predeterminada. Databricks recomienda mantener la notificación predeterminada sub para la federación de identidades de carga de trabajo. Elija solo una notificación diferente si sub no es un identificador de sujeto adecuado o estable, lo que es poco frecuente. Para obtener más información, consulte Directivas de federación de entidad de servicio de ejemplo.

  • 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 cuentas, 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 la entidad de servicio para la que va a 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 Azure Databricks en el terminal web del área de trabajo de Azure Databricks para crear una directiva de federación.

  1. Instale o actualice a la versión más reciente de la CLI de Azure 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:

    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 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-4c56a910c7ceNotificación del firmante: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" }

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 desde el que Azure Databricks aceptará tokens.
  • Los criterios para asignar un token al usuario o entidad de servicio de Azure Databricks correspondiente.

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

  • Emisor:https://idp.mycompany.com/oidc
  • Audiencias:databricks
  • Notificación del firmante: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 cuentas en la cuenta de Azure Databricks.

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

  • Dirección URL del emisor: Dirección URL HTTPS que identifica el proveedor de identidades, especificado en la iss notificación de los tokens.

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

  • Notificación del firmante: Notificación de 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

En el caso de la federación en toda la cuenta, registre solo los IdP que sean totalmente administrados y de confianza por su organización, como el propio IdP 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 cuentas, inicie sesión en la consola de la cuenta de Azure Databricks en https://accounts.azuredatabricks.net.
  2. Haga clic en Configuración 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 notificación del firmante y la validación de firma de token opcional.
  5. Haga clic en Crear directiva.

CLI de Databricks

No puede usar la CLI de Azure Databricks en el terminal web del área de trabajo de Azure Databricks 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. 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 de Azure Databricks crea una directiva de federación de cuenta:

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 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-cd0e6f879c1dNotificación del firmante: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 de Azure Databricks en el encabezado de la Bearer: 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