Comparteix via

Autorización del acceso de la entidad de servicio a Azure Databricks con OAuth

En esta página se explica cómo autorizar el acceso a recursos de Azure Databricks desde procesos desatendidos, como comandos automatizados de la CLI o llamadas api REST realizadas desde scripts o aplicaciones.

Azure Databricks usa OAuth 2.0 como protocolo preferido para la autorización y autenticación de la entidad de servicio fuera de la interfaz de usuario. La autenticación de cliente unificada automatiza la generación y actualización de tokens. Cuando una entidad de servicio inicia sesión y se concede su consentimiento, OAuth emite un token de acceso para la CLI, el SDK u otra herramienta que se va a usar en su nombre. Cada token de acceso es válido durante una hora, después del cual se solicita automáticamente un nuevo token.

En esta página, la autorización hace referencia al uso de OAuth para conceder a una entidad de servicio acceso a los recursos de Azure Databricks, mientras que la autenticación hace referencia a la validación de credenciales mediante tokens de acceso.

Para más información de alto nivel, consulte Autorización del acceso a los recursos de Azure Databricks.

Formas de autorizar una entidad de servicio

Azure Databricks admite dos maneras de autorizar una entidad de servicio:

  • Automático (recomendado): Use la autenticación unificada con herramientas y SDK compatibles, como el SDK de Terraform de Azure Databricks. Este enfoque controla automáticamente la generación y actualización de tokens, y es ideal para la automatización u otras cargas de trabajo desatendidas.

  • Manual: Genere un comprobador de código y un desafío y, a continuación, intercambielos para un token de OAuth. Use este método si la herramienta o la API no admiten la autenticación unificada. Es posible que tenga que crear su propio mecanismo de actualización de tokens para la aplicación. Para obtener más información, consulte Generación manual de tokens de acceso de OAuth M2M.

Prerrequisitos

Antes de configurar OAuth, realice los pasos siguientes:

  1. Cree una entidad de servicio de Azure Databricks. Consulte Incorporación de entidades de servicio a su cuenta.
  2. Vaya a la pestaña Configuración de la entidad de servicio y seleccione los derechos que debe tener para esta área de trabajo.
  3. Vaya a la pestaña Permisos y conceda acceso a los usuarios, entidades de servicio y grupos de Azure Databricks que quiera administrar y usar esta entidad de servicio. Consulte ¿Quién puede administrar y usar entidades de servicio?.

Paso 1: Crear un secreto de OAuth

Para autorizar el acceso a los recursos de Azure Databricks con OAuth, debe crear un secreto de OAuth. El secreto se usa para generar tokens de acceso de OAuth para la autenticación. Una entidad de servicio puede tener hasta cinco secretos de OAuth y cada secreto puede ser válido durante hasta dos años.

Los administradores de cuentas y los administradores del área de trabajo pueden crear una clave secreta de OAuth para un service principal.

  1. En la página de detalles de la entidad de servicio, abra la pestaña Secretos .
  2. En Secretos de OAuth, haga clic en Generar secreto.
  3. Establezca la duración del secreto en días (máximo 730 días).
  4. Copie el secreto mostrado y el identificador de cliente y, a continuación, haga clic en Listo. El secreto solo se muestra una vez. El identificador de cliente es el mismo que el identificador de aplicación de la entidad de servicio.

Los administradores de cuentas también pueden crear un secreto de OAuth desde la consola de la cuenta. En la pestaña Administración de usuarios, seleccione la entidad de servicio y, a continuación, vaya a la pestaña Credenciales y secretos .

Nota:

Para permitir que la entidad de servicio use clústeres o almacenes de SQL, debe conceder a la entidad de servicio acceso a ellos. Consulte Permisos de proceso o Administración de un almacenamiento de SQL.

Paso 2: Uso de la autorización de OAuth

Para usar la autorización de OAuth con la herramienta de autenticación unificada, debe establecer las siguientes variables de entorno asociadas, .databrickscfg campos, campos de Terraform o Config campos:

  • El host de Azure Databricks, especificado como https://accounts.azuredatabricks.net para las operaciones de cuenta o la dirección URL por área de trabajo de destino, por ejemplo https://adb-1234567890123456.7.azuredatabricks.net para las operaciones del área de trabajo.
  • El identificador de cuenta de Azure Databricks para las operaciones de la cuenta de Azure Databricks.
  • El Identificador de cliente de la entidad de servicio.
  • Secreto de la entidad de servicio.

Para realizar la autenticación de la entidad de servicio de OAuth, integre lo siguiente en el código, en función de la herramienta o el SDK participantes:

Entorno

Para usar variables de entorno para un tipo de autenticación de Azure Databricks específico con una herramienta o SDK, consulte Autorización del acceso a recursos de Azure Databricks o la documentación de la herramienta o el SDK. Consulte también Variables y campos de entorno para la autenticación unificada y la prioridad del método de autenticación.

Para las operaciones de nivel de cuenta, establezca las siguientes variables de entorno:

  • DATABRICKS_HOST, se establece en el valor de la dirección URL de la consola de la cuenta de Azure Databricks, https://accounts.azuredatabricks.net.
  • DATABRICKS_ACCOUNT_ID
  • DATABRICKS_CLIENT_ID
  • DATABRICKS_CLIENT_SECRET

Para las operaciones de nivel de área de trabajo, establezca las siguientes variables de entorno:

  • DATABRICKS_HOST, se establece en el valor de la dirección URL por área de trabajo de Azure Databricks, por ejemplo.https://adb-1234567890123456.7.azuredatabricks.net
  • DATABRICKS_CLIENT_ID
  • DATABRICKS_CLIENT_SECRET

Perfil

Cree o identifique un perfil de configuración de Azure Databricks con los campos siguientes en el archivo .databrickscfg. Si crea el perfil, reemplace los marcadores de posición por los valores adecuados. Para usar el perfil con una herramienta o un SDK, consulte Autorización del acceso a los recursos de Azure Databricks o a la documentación del SDK o de la herramienta. Consulte también Variables y campos de entorno para la autenticación unificada y la prioridad del método de autenticación.

Para las operaciones de nivel de cuenta, establezca los siguientes valores en el archivo .databrickscfg. En este caso, la dirección URL de la consola de la cuenta de Azure Databricks es https://accounts.azuredatabricks.net:

[<some-unique-configuration-profile-name>]
host          = <account-console-url>
account_id    = <account-id>
client_id     = <service-principal-client-id>
client_secret = <service-principal-secret>

Para las operaciones de nivel de área de trabajo, establezca los siguientes valores en el archivo .databrickscfg. En este caso, el host es la dirección URL de Azure Databricks por área de trabajo, por ejemplo https://adb-1234567890123456.7.azuredatabricks.net:

[<some-unique-configuration-profile-name>]
host          = <workspace-url>
client_id     = <service-principal-client-id>
client_secret = <service-principal-secret>

Al autorizar con entidades de servicio de Azure AD, las claves de configuración difieren de las entidades de servicio administradas por Azure Databricks:

host = https://<workspace-url>
azure_client_id = <azure-service-principal-client-id>
azure_client_secret = <azure-service-principal-secret>
azure_tenant_id = <azure-tenant-id>

Interfaz de línea de comandos (CLI)

Para la CLI de Databricks, realice una de las siguientes acciones:

  • Establezca las variables de entorno como se especifica en la pestaña Entorno .
  • Establezca los valores del .databrickscfg archivo como se especifica en la pestaña Perfil .

Las variables de entorno siempre tienen prioridad sobre los valores del archivo .databrickscfg.

Consulte también Autenticación de máquina a máquina (M2M) de OAuth.

Conexión

Nota:

La autenticación de la entidad de servicio de OAuth se admite en las siguientes versiones de Databricks Connect:

  • Para Python, Databricks Connect para Databricks Runtime 14.0 y versiones posteriores.
  • Para Scala, Databricks Connect para Databricks Runtime 13.3 LTS y versiones posteriores. El SDK de Databricks para Java que se incluye con Databricks Connect para Databricks Runtime 13.3 LTS y versiones posteriores debe actualizarse al SDK de Databricks para Java 0.17.0 o superior.

Para Databricks Connect, puede optar por:

  • Use un perfil de configuración: Establezca los valores a nivel de área de trabajo en el .databrickscfg archivo según lo descrito en la pestaña Perfil. También configure la cluster_id dirección URL de la instancia de su área de trabajo.
  • Usar variables de entorno: Establezca los mismos valores que se muestran en la pestaña Entorno. Además, establezca la dirección URL de la instancia del área de trabajo en DATABRICKS_CLUSTER_ID.

Los valores de .databrickscfg tienen prioridad sobre las variables de entorno.

Para inicializar Databricks Connect con estas opciones, consulte Configuración de proceso para Databricks Connect.

Código de VS

Para la extensión de Databricks para Visual Studio Code, haga lo siguiente:

  1. Establezca los valores del .databrickscfg archivo para las operaciones de nivel de área de trabajo de Azure Databricks tal como se especifica en la pestaña Perfil .
  2. En el panel Configuración de la extensión de Databricks para Visual Studio Code, haga clic en Configurar Databricks.
  3. En la Paleta de comandos, para Host de Databricks, escriba su URL por área de trabajo, como, por ejemplo, https://adb-1234567890123456.7.azuredatabricks.net, y presione Enter.
  4. En la paleta de comandos, seleccione el nombre del perfil de destino en la lista de la dirección URL.

Para obtener más información, consulte Configurar la autorización para la extensión de Databricks para Visual Studio Code.

Terraformación

Operaciones de nivel de cuenta

Para la autenticación predeterminada:

provider "databricks" {
  alias = "accounts"
}

Para la configuración directa:

provider "databricks" {
  alias         = "accounts"
  host          = <retrieve-account-console-url>
  account_id    = <retrieve-account-id>
  client_id     = <retrieve-client-id>
  client_secret = <retrieve-client-secret>
}

Reemplace los retrieve marcadores de posición por su propia implementación para recuperar los valores de la consola o de algún otro almacén de configuración, como HashiCorp Vault. Consulte también Proveedor de almacén. En este caso, la dirección URL de la consola de la cuenta de Azure Databricks es https://accounts.azuredatabricks.net.

Operaciones de nivel de área de trabajo

Para la configuración predeterminada:

provider "databricks" {
  alias = "workspace"
}

Para la configuración directa:

provider "databricks" {
  alias         = "workspace"
  host          = <retrieve-workspace-url>
  client_id     = <retrieve-client-id>
  client_secret = <retrieve-client-secret>
}

Reemplace los retrieve marcadores de posición por su propia implementación para recuperar los valores de la consola o de algún otro almacén de configuración, como HashiCorp Vault. Consulte también Proveedor de almacén. En este caso, el host es la dirección URL por área de trabajo de Azure Databricks, por ejemplo https://adb-1234567890123456.7.azuredatabricks.net.

Para obtener más información sobre la autenticación con el proveedor Databricks Terraform, consulte Authentication.

Pitón

Operaciones de nivel de cuenta

Para la configuración predeterminada:

from databricks.sdk import AccountClient

a = AccountClient()
# ...

Para la configuración directa:

from databricks.sdk import AccountClient

a = AccountClient(
  host          = retrieve_account_console_url(),
  account_id    = retrieve_account_id(),
  client_id     = retrieve_client_id(),
  client_secret = retrieve_client_secret()
)
# ...

Reemplace los retrieve marcadores de posición por su propia implementación para recuperar los valores de la consola u otro almacén de configuración, como Azure KeyVault. En este caso, la dirección URL de la consola de la cuenta de Azure Databricks es https://accounts.azuredatabricks.net.

Operaciones de nivel de área de trabajo

Para la configuración predeterminada:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

Para la configuración directa:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
  host          = retrieve_workspace_url(),
  client_id     = retrieve_client_id(),
  client_secret = retrieve_client_secret()
)
# ...

Reemplace los retrieve marcadores de posición por su propia implementación para recuperar los valores de la consola u otro almacén de configuración, como Azure KeyVault. En este caso, el host es la dirección URL por área de trabajo de Azure Databricks, por ejemplo https://adb-1234567890123456.7.azuredatabricks.net.

Para obtener más información sobre la autenticación con herramientas y SDK de Databricks que usan Python e implementan la autenticación unificada, consulte:

Nota:

La extensión de Databricks para Visual Studio Code usa Python, pero aún no ha implementado la autenticación de entidad de servicio de OAuth.

Java

Operaciones de nivel de área de trabajo

Para la configuración predeterminada:

import com.databricks.sdk.WorkspaceClient;
// ...
WorkspaceClient w = new WorkspaceClient();
// ...

Para la configuración directa:

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
// ...
DatabricksConfig cfg = new DatabricksConfig()
  .setHost(retrieveWorkspaceUrl())
  .setClientId(retrieveClientId())
  .setClientSecret(retrieveClientSecret());
WorkspaceClient w = new WorkspaceClient(cfg);
// ...

Reemplace los retrieve marcadores de posición por su propia implementación para recuperar los valores de la consola u otro almacén de configuración, como Azure KeyVault. En este caso, el host es la dirección URL por área de trabajo de Azure Databricks, por ejemplo https://adb-1234567890123456.7.azuredatabricks.net.

Para obtener más información sobre la autenticación con herramientas y SDK de Databricks que usan Java e implementan la autenticación unificada, consulte:

Go

Operaciones de nivel de cuenta

Configuración predeterminada:

import "github.com/databricks/databricks-sdk-go"

// Uses environment configuration automatically
a := databricks.Must(databricks.NewAccountClient())

Para la configuración directa:

import (
  "github.com/databricks/databricks-sdk-go"
)
// ...
a := databricks.Must(databricks.NewAccountClient(&databricks.Config{
  Host:         retrieveWorkspaceUrl(),
  ClientId:     retrieveClientId(),
  ClientSecret: retrieveClientSecret(),
}))
// ...

Reemplace los retrieve marcadores de posición por su propia implementación para recuperar los valores de la consola u otro almacén de configuración, como Azure KeyVault. En este caso, la dirección URL de la consola de la cuenta de Azure Databricks es https://accounts.azuredatabricks.net.

Operaciones de nivel de área de trabajo

Para la configuración predeterminada:

import "github.com/databricks/databricks-sdk-go"

// Uses environment configuration automatically
w := databricks.Must(databricks.NewWorkspaceClient())

Para la configuración directa:

import "github.com/databricks/databricks-sdk-go"
// ...
w := databricks.Must(databricks.NewWorkspaceClient(&databricks.Config{
    Host:         retrieveAccountConsoleUrl(),
    ClientId:     retrieveClientId(),
    ClientSecret: retrieveClientSecret(),
}))
// ...

Reemplace los retrieve marcadores de posición por su propia implementación para recuperar los valores de la consola u otro almacén de configuración, como Azure KeyVault. En este caso, el host es la dirección URL por área de trabajo de Azure Databricks, por ejemplo https://adb-1234567890123456.7.azuredatabricks.net.

Para obtener más información sobre la autenticación con herramientas y SDK de Databricks que usan Go y que implementan la autenticación unificada de cliente de Databricks, consulte Autenticación del SDK de Databricks para Go con su cuenta de Azure Databricks o su área de trabajo.

Generación manual de tokens de acceso de OAuth M2M

Esta sección es para herramientas o servicios que no admiten la autenticación unificada de Databricks. Si necesita generar, actualizar o usar manualmente tokens de OAuth de Azure Databricks para la autenticación M2M, siga estos pasos.

Para generar un token de acceso de OAuth M2M, use el identificador de cliente de la entidad de servicio y el secreto de OAuth. Cada token de acceso es válido durante una hora. Una vez expirado, solicite un nuevo token. Puede generar tokens en el nivel de cuenta o área de trabajo:

Generación de un token de acceso de nivel de cuenta

Use un token de nivel de cuenta para llamar a las API REST de la cuenta y a las áreas de trabajo a las que pueda acceder la entidad de servicio.

  1. Busque el identificador de la cuenta.

  2. Construya la dirección URL del punto de conexión del token reemplazando <account-id> en la siguiente dirección URL por el identificador de cuenta.

    https://accounts.azuredatabricks.net/oidc/accounts/<my-account-id>/v1/token

  3. Use curl para solicitar un token de acceso de OAuth. Reemplazar:

    • <token-endpoint-URL> con la dirección URL anterior.
    • <client-id> con el identificador de cliente (id. de aplicación) de la entidad de servicio.
    • <client-secret> con el secreto de OAuth de la entidad de servicio.
    export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>

  curl --request POST \
  --url <token-endpoint-URL> \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --data 'grant_type=client_credentials&scope=all-apis'

    Esto genera una respuesta similar a la siguiente:

    {
  "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
  "token_type": "Bearer",
  "expires_in": 3600
}

    El all-apis ámbito solicita un token de acceso de OAuth que permite a la entidad de servicio llamar a cualquier API rest de Databricks a la que tenga permiso para acceder.

  4. Copie el access_token valor de la respuesta.

Generación de un token de acceso de nivel de área de trabajo

Use un token de nivel de área de trabajo solo con las API REST de esa área de trabajo.

  1. Construya la dirección URL del punto de conexión del token reemplazando <databricks-instance> por <databricks-instance> por el nombre de la instancia del área de trabajo de Azure Databricks, por ejemplo:adb-1234567890123456.7.azuredatabricks.net

    https://<databricks-instance>/oidc/v1/token

  2. Use curl para solicitar un token de acceso de OAuth. Reemplazar:

    • <token-endpoint-URL> con la dirección URL anterior.
    • <client-id> con el identificador de cliente (id. de aplicación) de la entidad de servicio.
    • <client-secret> con el secreto de OAuth de la entidad de servicio.
    export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>

curl --request POST \
--url <token-endpoint-URL> \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--data 'grant_type=client_credentials&scope=all-apis'

    Esto genera una respuesta similar a la siguiente:

    {
  "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
  "token_type": "Bearer",
  "expires_in": 3600
}

  3. Copie el access_token valor de la respuesta.

Nota:

Para generar un token para un punto de conexión de servicio, incluya el identificador y la acción del punto de conexión en la solicitud. Consulte Captura manual de un token de OAuth.

Llamada a una API REST de Azure Databricks

Use el token de acceso de OAuth para llamar a las API REST de nivel de cuenta o de área de trabajo . Para llamar a las API de nivel de cuenta, la entidad de servicio debe ser un administrador de cuentas.

Incluya el token en el encabezado de autorización con Bearer autenticación.

Solicitud de API de REST de nivel de cuenta de ejemplo

En este ejemplo se enumeran todas las áreas de trabajo de una cuenta. Reemplazar:

  • <oauth-access-token> con el token de acceso de OAuth de la entidad de servicio.
  • <account-id> con el identificador de la cuenta.
export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://accounts.azuredatabricks.net/api/2.0/accounts/<account-id>/workspaces'

Ejemplo de solicitud de API REST a nivel de espacio de trabajo

En este ejemplo se enumeran todos los clústeres disponibles de un área de trabajo. Reemplazar:

  • <oauth-access-token> con el token de acceso de OAuth de la entidad de servicio.
  • <databricks-instance>con el nombre de la instancia del área de trabajo de Azure Databricks, por ejemplo.adb-1234567890123456.7.azuredatabricks.net
export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://<workspace-URL>/api/2.0/clusters/list'

Solución de problemas de autenticación de OAuth M2M

Siga estos pasos para corregir los problemas más comunes con la autenticación de OAuth M2M de Databricks para las entidades de servicio.

Comprobaciones rápidas

Comience comprobando estos problemas comunes de configuración que provocan errores de autenticación de OAuth M2M:

  • Credenciales:DATABRICKS_CLIENT_ID se establece en el identificador de aplicación (id. de cliente) de la entidad de servicio y DATABRICKS_CLIENT_SECRET se establece en el valor del secreto de OAuth, ambos sin espacios adicionales.
  • Anfitrión:DATABRICKS_HOST apunta a https://accounts.azuredatabricks.net para las operaciones de cuenta o a la URL de destino para cada espacio de trabajo, por ejemplo https://adb-1234567890123456.7.azuredatabricks.net, para las operaciones del espacio de trabajo. No incluya /api.
  • Asignación: El principal de servicio se asigna al área de trabajo de destino.
  • Permisos: La entidad de servicio tiene los permisos necesarios en el recurso de destino.
  • Conflictos: No hay variables en conflicto establecidas como DATABRICKS_TOKEN, DATABRICKS_USERNAME. Ejecute env | grep DATABRICKS y anule los conflictos.
  • Herramientas: Usar la autenticación unificada y las versiones actuales del CLI o el SDK.

401 No autorizado

Causas y correcciones probables:

  • Identificador de cliente incorrecto o secreto: Vuelva a copiar DATABRICKS_CLIENT_ID y DATABRICKS_CLIENT_SECRET. Regenera el secreto si no estás seguro.
  • Secreto expirado: Cree un nuevo secreto si el actual ha expirado.
  • Emisor de token incorrecto: Para M2M, use el punto de conexión del token de OAuth de Databricks, no el punto de conexión de token de IdP o de la nube.
  • Error de coincidencia de host: Si se autentica para las APIs del espacio de trabajo, DATABRICKS_HOST debe ser la URL del espacio de trabajo que está llamando.

403 Prohibido

Causas y correcciones probables:

  • Faltan permisos de recursos: Conceda a la entidad de servicio permisos de CAN USE o CAN MANAGE en clústeres o almacenes SQL, y los permisos de nivel de objeto necesarios para cuadernos, trabajos u objetos de datos.
  • Sin asignación de espacio de trabajo: Asigne el principal de servicio al espacio de trabajo en la consola de cuentas.
  • Acceso a la API de administración: Para las API de solo administrador, asigne el principal de servicio al grupo de administración del espacio de trabajo o conceda permisos de administrador de cuenta.

Problemas de configuración

Los síntomas incluyen tiempos de espera, "no se encontró el host", "no se encontró la cuenta" o "no se encontró el área de trabajo".

Fixes:

  • Reglas de host: Use la dirección URL de la consola de la cuenta para las APIs de cuenta. Use la dirección URL del área de trabajo para las API del área de trabajo. No incluya el /api sufijo.
  • Id. de cuenta: Proporcione DATABRICKS_ACCOUNT_ID solo para las operaciones de nivel de cuenta. Utilice el UUID de la consola de la cuenta.
  • Selección de perfil: Si usa varios perfiles, pase --profile <name> o establezca DATABRICKS_CONFIG_PROFILE.

Connectivity

Si se produce un error en la autenticación de OAuth M2M debido a problemas de red, use estas pruebas para comprobar que el entorno puede llegar a los puntos de conexión de Databricks:

  • DNS:nslookup <your-host> (debe devolver direcciones IP para el nombre de host)
  • TLS y capacidad de acceso:curl -I https://<your-host> (debe devolver el estado HTTP 200, 401 o 403)
  • Red corporativa: Confirmación de que las reglas de proxy o firewall permiten HTTPS a los puntos de conexión de Databricks

Recursos adicionales

  • Last updated on