Compartir vía

Autorizar el acceso desatendido a los recursos de Azure Databricks con una entidad de servicio mediante OAuth

  • Artículo

En este tema se proporcionan pasos y detalles para autorizar el acceso a los recursos de Azure Databricks al automatizar los comandos de la CLI de Azure Databricks o llamar a las API REST de Azure Databricks mediante código que se ejecutará en un proceso desatendido.

Azure Databricks usa OAuth como protocolo preferido para la autorización y autenticación de usuarios al interactuar con los recursos de Azure Databricks fuera de la interfaz de usuario. Azure Databricks también proporciona la herramienta de autenticación de cliente unificada para automatizar la actualización de los tokens de acceso generados como parte del método de autenticación de OAuth. Esto se aplica a las entidades de servicio, así como a las cuentas de usuario, pero debe configurar una entidad de servicio con los permisos y privilegios adecuados para los recursos de Azure Databricks a los que debe acceder como parte de sus operaciones.

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

¿Cuáles son mis opciones de autorización y autenticación cuando utilizo un principal de servicio de Azure Databricks?

En este tema, la autorización se refiere al protocolo (OAuth) utilizado para negociar el acceso a recursos específicos de Azure Databricks a través de la delegación. Autenticación hace referencia al mecanismo por el que se representan, transmiten y comprueban—las credenciales que, en este caso, se tokens de acceso.

Azure Databricks usa autorización basada en OAuth 2.0para habilitar el acceso a los recursos de área de trabajo y cuenta de Azure Databricks desde la línea de comandos o el código en nombre de una entidad de servicio con los permisos para acceder a esos recursos. Una vez configurada una entidad de servicio de Azure Databricks y sus credenciales se comprueban cuando ejecuta un comando de la CLI o llama a una API REST, se proporciona un token de OAuth a la herramienta o el SDK participantes para realizar la autenticación basada en tokens en nombre de la entidad de servicio desde ese momento. El token de acceso de OAuth tiene una duración de una hora, después de la cual la herramienta o el SDK implicados realizarán un intento automático de obtener un nuevo token que también es válido durante una hora.

Azure Databricks admite dos formas de autorizar el acceso a un principal del servicio con OAuth:

  • Principalmente automáticamente, mediante la compatibilidad con la autenticación de cliente unificada de Databricks. Usa este enfoque simplificado si utilizas SDKs específicos de Azure Databricks (como el SDK de Terraform de Databricks) y herramientas. Las herramientas y los SDK admitidos se enumeran en autenticación unificada de cliente de Databricks. Este enfoque es adecuado para la automatización u otros escenarios de procesos desatendidos.
  • Manualmente, generando directamente un par verificador/desafío de código OAuth y un código de autorización, y utilizándolos para crear un token OAuth inicial que proporciones en la configuración. Use este enfoque cuando no use una API compatible con la autenticación unificada de cliente de Databricks. En este caso, puede que tenga que desarrollar su propio mecanismo para controlar la actualización de tokens de acceso específicos de la herramienta o API de terceros que está usando. Para obtener más información, consulte: Generación manual y uso de tokens de acceso para la autenticación de la entidad de servicio de OAuth.

Antes de empezar, necesita configurar un principal de servicio de Azure Databricks y asignarle los permisos adecuados para acceder a los recursos que necesita usar cuando su código de automatización o comandos los soliciten.

Requisito previo: Crear un principal de servicio

Los administradores de cuentas y los administradores del área de trabajo pueden crear entidades de servicio. En este paso se describe cómo crear una entidad de servicio en un área de trabajo de Azure Databricks. Para más información sobre la propia consola de la cuenta de Azure Databricks, consulte Administración de entidades de servicio en la cuenta.

También puede crear una entidad de servicio administrada de Microsoft Entra ID y agregarla a Azure Databricks. Para obtener más información, consulte Databricks y entidades de servicio de Id. de Microsoft Entra.

  1. Como administrador del área de trabajo, inicia sesión en el área de trabajo de Azure Databricks.
  2. Haga clic en su nombre de usuario en la barra superior del área de trabajo de Azure Databricks y seleccione Configuración.
  3. Haga clic en la pestaña Identidad y acceso.
  4. Junto a Entidades de servicio, haga clic en Administrar.
  5. Haga clic en Agregar entidad de servicio.
  6. Haga clic en la flecha desplegable en el cuadro de búsqueda y, a continuación, haga clic en Agregar nuevo.
  7. En Administración, elija Databricks managed (Administrado por Databricks).
  8. Proporcione un nombre para la entidad de servicio.
  9. Haga clic en Agregar.

La entidad de servicio se agrega tanto al área de trabajo como a la cuenta de Azure Databricks.

Paso 1: Asignar permisos a tu principal de servicio

  1. Haga clic en el nombre de la entidad de servicio para abrir su página de detalles.
  2. En la pestaña Configuraciones, active la casilla situada junto a cada derecho que quiera que tenga la entidad de servicio de Azure AD para esta área de trabajo y a continuación, haga clic en Actualizar.
  3. En la pestaña Permisos, conceda acceso a los usuarios, entidades de servicio y grupos de Azure Databricks que quiera administrar y usar esta entidad de servicio. Consulte Administración de roles en una entidad de servicio.

Paso 2: Crear un secreto de OAuth para un principal de servicio

Para poder usar OAuth para autorizar el acceso a los recursos de Azure Databricks, primero debe crear un secreto de OAuth, que se puede usar para generar tokens de acceso de OAuth para la autenticación. Una entidad de servicio puede tener hasta cinco secretos de OAuth. Los administradores de cuentas y los administradores del área de trabajo pueden crear un secreto de OAuth para una entidad de servicio.

  1. En la página de detalles de la entidad de servicio, haga clic en la pestaña Secretos .

  2. En Secretos de OAuth, haga clic en Generar secreto.

    Generación de un secreto de OAuth desde el área de trabajo

  3. Copie el secreto y el identificador de cliente mostrados y, a continuación, haga clic en Listo.

El secreto solo se revelará una vez durante la creación. El id. de cliente es el mismo que el identificador de aplicación de la entidad de servicio.

Los administradores de cuentas también pueden generar un secreto de OAuth desde la página de detalles de la entidad de servicio en la consola de la cuenta.

  1. Como administrador de la cuenta, inicie sesión en la consola de la cuenta.

  2. Haga clic en icono de Administración de usuarios de la consola de la cuentaAdministración de usuarios.

  3. En la pestaña Entidades de servicio, seleccione la entidad de servicio.

  4. En Secretos de OAuth, haga clic en Generar secreto.

    Generación de un secreto de OAuth desde el área de trabajo

  5. Copie el secreto y el identificador de cliente mostrados y, a continuación, haga clic en Listo.

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 3: Uso de la autorización de OAuth

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

  • 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.
  • 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 específico de Azure Databricks con una herramienta o un SDK, consulte Autorización para el acceso a los recursos de Azure Databricks o la documentación de la herramienta o del SDK. Consulte también Variables de entorno y campos para la autenticación unificada del cliente y Métodos predeterminados para la autenticación unificada del cliente.

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

  • DATABRICKS_HOST, establecido en 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, establecido en la URL por espacio 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 Autorizando el acceso a los recursos de Azure Databricks o en la documentación de la herramienta o del SDK. Consulte también Variables de entorno y campos para la autenticación unificada del cliente y Métodos predeterminados para la autenticación unificada del cliente.

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>

CLI

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

  • Establezca las variables de entorno como se especifica en la sección “Entorno” de este artículo.
  • Establezca los valores del archivo .databrickscfg tal y como se especifica en la sección “Perfil” de este artículo.

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 realizar una de las siguientes acciones:

Los valores del archivo .databrickscfg siempre tienen prioridad sobre las variables de entorno.

Para inicializar el cliente de Databricks Connect con estas variables de entorno o valores en el .databrickscfg archivo, 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 archivo .databrickscfg para las operaciones de nivel de área de trabajo de Azure Databricks tal como se especifica en esta sección “Perfil” de este artículo.
  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, en Host de Databricks, escriba la dirección URL del á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.

Terraform

Para las operaciones de nivel de cuenta, para la autenticación predeterminada:

provider "databricks" {
  alias = "accounts"
}

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

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

Para las operaciones de nivel de área de trabajo, para la autenticación predeterminada:

provider "databricks" {
  alias = "workspace"
}

Para la configuración directa (reemplace los marcadores de posición retrieve por su propia implementación para recuperar los valores de la consola o de otro almacén de configuración, como HashiCorp Vault. Consulte también Proveedor de Vault). 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:

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

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

Python

Para operaciones de nivel de cuenta, use lo siguiente para la autenticación predeterminada:

from databricks.sdk import AccountClient

a = AccountClient()
# ...

Para la configuración directa, use lo siguiente, pero reemplace los marcadores de posición retrieve por su propia implementación, con el fin de recuperar los valores de la consola o de 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:

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()
)
# ...

En el caso de las operaciones de nivel de área de trabajo, en concreto de autenticación predeterminada:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

Para la configuración directa, reemplace los marcadores de posición retrieve por su propia implementación, con el fin de recuperar los valores de la consola, o de otro almacén de configuración, como Azure KeyVault. 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:

from databricks.sdk import WorkspaceClient

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

Para obtener más información acerca de la autenticación con herramientas y SDK de Databricks que usan Python y que implementan la Autenticación unificada de cliente de Databricks, 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

Para operaciones de nivel de área de trabajo mediante autenticación predeterminada:

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

Para la configuración directa (reemplace los marcadores de posición retrieve por su propia implementación para recuperar los valores de la consola o de otro almacén de configuración, como Azure KeyVault). 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:

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);
// ...

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

Go

Para operaciones de nivel de cuenta mediante autenticación predeterminada:

import (
"github.com/databricks/databricks-sdk-go"
)
// ...
w := databricks.Must(databricks.NewWorkspaceClient())
// ...

Para la configuración directa (reemplace los marcadores de posición retrieve por su propia implementación para recuperar los valores de la consola o de 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:

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

Para operaciones de nivel de área de trabajo mediante autenticación predeterminada:

import (
  "github.com/databricks/databricks-sdk-go"
)
// ...
a := databricks.Must(databricks.NewAccountClient())
// ...

Para la configuración directa (reemplace los marcadores de posición retrieve por su propia implementación para recuperar los valores de la consola o de otro almacén de configuración, como Azure KeyVault). 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:

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

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.

Generar y usar tokens de acceso manualmente para la autenticación de la entidad de servicio de OAuth

Las herramientas y LOS SDK de Azure Databricks que implementan los Autenticación unificada del cliente de Databricks estándar generarán, actualizarán y usarán automáticamente tokens de acceso de OAuth de Azure Databricks en su nombre según sea necesario para la autenticación de la entidad de servicio de OAuth.

Databricks recomienda usar la autenticación unificada de cliente; sin embargo, si debe generar, actualizar o usar manualmente tokens de acceso de OAuth de Azure Databricks, siga las instrucciones de esta sección.

Use el identificador de cliente y el secreto de OAuth de la entidad de servicio para solicitar un token de acceso de OAuth para autenticarse en las API REST de nivel de cuenta y en las API REST de nivel de área de trabajo. El token de acceso expirará en una hora. Debe solicitar un nuevo token de acceso de OAuth después de la expiración. El ámbito del token de acceso de OAuth depende del nivel desde el que se crea el token. Puede crear un token en el nivel de cuenta o en el nivel de área de trabajo, como se indica a continuación:

Generar manualmente un token de acceso de nivel de cuenta

Un token de acceso de OAuth creado a partir del nivel de cuenta se puede usar en las API rest de Databricks de la cuenta y en cualquier área de trabajo a la que tenga acceso la entidad de servicio.

  1. Como administrador de la cuenta, inicie sesión en la consola de la cuenta.

  2. Haga clic en la flecha hacia abajo situada junto a su nombre de usuario en la esquina superior derecha.

  3. Copie su Id. de cuenta.

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

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

  5. Use un cliente como curl para solicitar un token de acceso de OAuth con la dirección URL del punto de conexión del token, el identificador de cliente de la entidad de servicio (también conocido como identificador de aplicación) y el secreto de OAuth de la entidad de servicio que creó. El all-apis ámbito solicita un token de acceso de OAuth que se puede usar para acceder a todas las API rest de Databricks a las que se ha concedido acceso la entidad de servicio.

    • Reemplace <token-endpoint-URL> por la dirección URL del punto de conexión del token anterior.
    • Reemplace <client-id> por el identificador de cliente de la entidad de servicio’, que también se conoce como identificador de aplicación.
    • Reemplace <client-secret> por el secreto de OAuth de la entidad de servicio que creó.
    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
  }

    Copie el objeto access_token de la respuesta.

Generar manualmente un token de acceso de nivel de área de trabajo

Un token de acceso de OAuth creado a partir del nivel de área de trabajo solo puede acceder a las API REST de esa área de trabajo, incluso si la entidad de servicio es un administrador de cuenta o es miembro de otras áreas de trabajo.

  1. Construya la URL del punto de conexión de los tokens reemplazando https://<databricks-instance> por la URL del área de trabajo de su implementación de Azure Databricks:

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

  2. Use un cliente como curl para solicitar un token de acceso de OAuth con la dirección URL del punto de conexión del token, el identificador de cliente de la entidad de servicio (también conocido como identificador de aplicación) y el secreto de OAuth de la entidad de servicio que creó. El all-apis ámbito solicita un token de acceso de OAuth que se puede usar para acceder a todas las API rest de Databricks a las que se le ha concedido acceso a la entidad de servicio dentro del área de trabajo desde la que solicita el token.

    • Reemplace <token-endpoint-URL> por la dirección URL del punto de conexión del token anterior.
    • Reemplace <client-id> por el identificador de cliente de la entidad de servicio’, que también se conoce como identificador de aplicación.
    • Reemplace <client-secret> por el secreto de OAuth de la entidad de servicio que creó.
    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
}

    Copie el objeto access_token de la respuesta.

Llamada a una API REST de Databricks

Puede usar el token de acceso de OAuth para autenticarse en Azure Databricks LAS API REST de nivel de cuenta y las API REST de nivel de área de trabajo. La entidad de servicio debe tener privilegios de administrador de cuenta para llamar a las API REST a nivel de cuenta.

Incluya el token de acceso en el encabezado de autorización mediante la autenticación Bearer. Puede usar este enfoque con curl o cualquier cliente que compile.

Solicitud de API de REST de nivel de cuenta de ejemplo

Este ejemplo usa la autenticación de Bearer para obtener una lista de todas las áreas de trabajo asociadas a una cuenta.

  • Reemplace por <oauth-access-token> el token de acceso de OAuth de la entidad de servicio que copió en el paso anterior.
  • Reemplace <account-id> por el id. de su 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'

Solicitud de API de REST de nivel de área de trabajo de ejemplo

En este ejemplo se usa la autenticación Bearer para enumerar todos los clústeres disponibles en el área de trabajo especificada.

  • Reemplace por <oauth-access-token> el token de acceso de OAuth de la entidad de servicio que copió en el paso anterior.
  • Reemplace <workspace-URL> por la URL de su área de trabajo base, que tiene una forma similar a dbc-a1b2345c-d6e7.cloud.databricks.com.
export OAUTH_TOKEN=<oauth-access-token>

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

Recursos adicionales