\
--json '{"permissions": ["USER"]}'
```
Usa `USER`, no `ADMIN`. Devin no necesita permisos de admin del workspace.
## Paso 2: Conectar Devin a la entidad de servicio
Sigue **una** de las dos opciones siguientes. Cada una es completa por sí sola: instala la CLI de Databricks mediante un [blueprint](/es/onboard-devin/environment/blueprints) en **Settings > Environment > Blueprints** y configura la CLI para autenticarse como la entidad de servicio del Paso 1.
* [**Opción A: secreto de cliente OAuth**](#option-a-oauth-client-secret). [OAuth M2M](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) estándar: la entidad de servicio obtiene un secreto de cliente, que almacenas en Devin Secrets. Es la forma más rápida de empezar.
* [**Opción B: federación de tokens OIDC**](#option-b-oidc-token-federation). Cada sesión de Devin puede emitir un token OpenID Connect de corta duración firmado por Devin. La [federación de tokens](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) de Databricks permite que la entidad de servicio confíe en ese emisor, de modo que Devin intercambia su propio token de identidad por un token OAuth de Databricks. Nunca se crea ni se almacena ningún secreto de Databricks, y por eso Databricks la recomienda encarecidamente para cargas de trabajo automatizadas.
Los tokens de acceso personal (PAT) vinculados a un usuario humano no se recomiendan en ninguna de las dos opciones: omiten la entidad de servicio, caducan de forma impredecible y atribuyen las acciones de Devin a una persona.
### Opción A: secreto de cliente OAuth
¿Prefieres no gestionar ningún secreto de Databricks? Salta a la [Opción B: federación de tokens OIDC](#option-b-oidc-token-federation). También puedes empezar aquí y cambiar más adelante: sustituye el blueprint por el de la Opción B, crea la política de federación y luego elimina el secreto de OAuth y el Devin Secret `DATABRICKS_CLIENT_SECRET`.
#### 1. Genera un secreto de OAuth
En la consola de la cuenta, abre la entidad de servicio del paso 1 y genera un **secreto de OAuth**. Establece la vigencia más corta que permita tu proceso de rotación (el máximo es de 730 días) y limita el secreto a los ámbitos de API que Devin necesita, como `sql`, `jobs` y `unity-catalog`. Evita seleccionar todos los ámbitos.
#### 2. Agrega los Devin Secrets
En Devin, agrega lo siguiente como [Devin Secrets](/es/product-guides/secrets) en la pestaña **Secrets** del blueprint que editarás a continuación (de organización o de repositorio):
| Secreto | Valor |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABRICKS_HOST` | La URL del **workspace** en el que Devin debe trabajar, por ejemplo `https://dbc-xxxx.cloud.databricks.com` o `https://adb-xxxx.azuredatabricks.net`, sin el sufijo `/api`. No el host `accounts.*`. |
| `DATABRICKS_CLIENT_ID` | El `applicationId` de la entidad de servicio (un UUID) del paso 1, no el `id` numérico |
| `DATABRICKS_CLIENT_SECRET` | El secreto de OAuth que generaste |
La CLI selecciona OAuth M2M automáticamente cuando hay un client ID y un client secret, por lo que `DATABRICKS_AUTH_TYPE` no es necesario. Configúralo como `oauth-m2m` solo si quieres descartar explícitamente cualquier otro método.
Los secretos se inyectan como variables de entorno al inicio de cada nueva sesión, así que la CLI no necesita ningún archivo de perfil. Un secreto rotado se aplica en la siguiente sesión nueva sin necesidad de recompilar.
#### 3. Agregar el blueprint
Solo instala la CLI. La autenticación proviene por completo de los tres secretos anteriores.
```yaml theme={null}
initialize:
- name: Install Databricks CLI
run: |
sudo rm -f /usr/local/bin/databricks
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh
databricks --version
knowledge:
- name: databricks-auth
contents: |
The `databricks` CLI authenticates as a service principal using the DATABRICKS_HOST,
DATABRICKS_CLIENT_ID, and DATABRICKS_CLIENT_SECRET environment variables, which are
provided as Devin Secrets. Do not run `databricks auth login`, do not set DATABRICKS_TOKEN,
and do not ask for a personal access token. Check auth with `databricks current-user me`.
Write only to the devin_dev catalog; production catalogs are read-only. Ship notebook and
job changes through a pull request.
```
No escribas los secretos en un archivo durante `initialize`; todo lo que se escriba ahí queda incorporado en la instantánea.
Tampoco configures `DATABRICKS_TOKEN` ni dejes un perfil `~/.databrickscfg` en la instantánea. Las credenciales en conflicto son la causa más habitual de que falle la autenticación M2M.
#### 4. Compila la instantánea
Guarda el blueprint y espera a que la compilación muestre **Éxito**; luego inicia una nueva sesión. Las sesiones existentes conservan la instantánea anterior. Continúa en el [Paso 3](#step-3-grant-permissions).
### Opción B: federación de tokens OIDC
Las sesiones de Devin emiten tokens de identidad de corta duración (`iss`, `sub`, `aud`), y una política de federación en la entidad de servicio le indica a Databricks que confíe en ellos. El blueprint instala la CLI `devin-oidc`, envuelve `databricks` para que cada llamada lleve un token nuevo y escribe un perfil que apunta a tu entidad de servicio. Luego lees los claims del token desde una sesión y creas una política que coincida con ellos.
¿Prefieres ir primero por el camino más corto? Empieza por la [Opción A](#option-a-oauth-client-secret) y vuelve aquí cuando quieras prescindir del secreto almacenado.
#### 1. Agrega el blueprint
Debes reemplazar dos marcadores de posición del perfil con tus propios valores:
| Marcador de posición | Reemplazar con |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `` | La URL del **workspace** en el que Devin debe trabajar, por ejemplo `https://dbc-xxxx.cloud.databricks.com` o `https://adb-xxxx.azuredatabricks.net`, sin el sufijo `/api`. No el host `accounts.*`. Es el mismo valor que `DATABRICKS_HOST` en la Opción A. |
| `` | El `applicationId` de la entidad de servicio (un UUID) que aparece en la salida de `databricks account service-principals create` del Paso 1. No el `id` numérico, que solo se usa para asociar la política de federación. |
```yaml theme={null}
initialize:
- uses: github.com/CognitionAI/actions/setup-devin-oidc@main
- name: Install Databricks CLI
run: |
sudo rm -f /usr/local/bin/databricks
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh
sudo mv /usr/local/bin/databricks /usr/local/bin/databricks-bin
- name: Wrap the CLI so each call carries a fresh Devin OIDC token
run: |
sudo tee /usr/local/bin/databricks > /dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
DATABRICKS_OIDC_TOKEN="$(devin-oidc token --audience "${DATABRICKS_DEVIN_AUDIENCE:-databricks}")"
export DATABRICKS_OIDC_TOKEN
exec /usr/local/bin/databricks-bin "$@"
EOF
sudo chmod +x /usr/local/bin/databricks
- name: Write Databricks CLI profile
run: |
cat > ~/.databrickscfg <<'EOF'
[DEFAULT]
host =
auth_type = env-oidc
client_id =
audience = databricks
EOF
chmod 600 ~/.databrickscfg
knowledge:
- name: databricks-auth
contents: |
The `databricks` CLI is preconfigured to authenticate as a service principal through
Devin OIDC token federation. Do not run `databricks auth login`, do not set
DATABRICKS_TOKEN, and do not ask for a personal access token. Check auth with
`databricks current-user me`. Write only to the devin_dev catalog; production catalogs
are read-only. Ship notebook and job changes through a pull request.
```
| Elemento | Propósito |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| `setup-devin-oidc` | Instala la CLI `devin-oidc`, que emite tokens de identidad de Devin ([detalles](/es/product-guides/oidc)). |
| Wrapper | Los tokens de identidad de Devin caducan a los 60 segundos, por lo que cada llamada a la CLI emite el suyo. |
| `auth_type = env-oidc` | Fija la CLI a la federación de tokens para que nunca recurra a un PAT ni a un inicio de sesión interactivo. |
| `host` / `client_id` | La URL del workspace y el `applicationId` de la entidad de servicio de la tabla anterior. |
| `audience` | La audiencia que solicita el wrapper y que deberás indicar en la política de federación de más abajo. |
| `knowledge` | Indica a Devin que la CLI ya está autenticada para que no intente ejecutar `databricks auth login`. |
El perfil no contiene ningún secreto, por lo que puede escribirse sin riesgo durante `initialize`. Si vienes de la Opción A, elimina el Devin Secret `DATABRICKS_CLIENT_SECRET` en cuanto tengas aplicada la política que se describe abajo, para que la CLI no vea dos credenciales.
#### 2. Compila la instantánea
Guarda el blueprint y espera a que la compilación muestre **Éxito**. Ningún elemento del blueprint depende de la política de federación que crearás a continuación, así que no tendrás que volver a compilarlo después.
#### 3. Crear la política de federación
Una vez compilado el blueprint, las sesiones de Devin pueden emitir tokens de identidad. Usa uno para leer los claims exactos en los que Databricks debe confiar y luego crea en la entidad de servicio una política de federación que coincida con ellos.
Inicia una nueva sesión de Devin y pídele que ejecute lo siguiente. Solo imprime los claims de identidad del token, nunca el token en sí.
```bash theme={null}
devin-oidc token --audience databricks | python3 -c '
import sys, json, base64
p = sys.stdin.read().strip().split(".")[1]
c = json.loads(base64.urlsafe_b64decode(p + "=="))
print(json.dumps({k: c[k] for k in ("iss", "sub", "aud")}, indent=2))'
```
Formato esperado:
```json theme={null}
{
"iss": "https://app.devin.ai",
"sub": "org_id:",
"aud": "databricks"
}
```
En los despliegues enterprise, `iss` es tu URL personalizada de Devin (por ejemplo, `https://yourcompany.devinenterprise.com`). Copia `iss` y `sub` exactamente como aparecen. No pegues el token sin procesar en tickets ni documentos; es una credencial de portador durante los siguientes 60 segundos.
Guarda esto como `devin-federation-policy.json`, sustituyendo los valores del paso anterior:
```json theme={null}
{
"description": "Allow Devin sessions to authenticate as the devin-sessions service principal",
"oidc_policy": {
"issuer": "https://",
"audiences": ["databricks"],
"subject": "org_id:"
}
}
```
Los tres campos son de coincidencia exacta:
* `issuer` debe ser igual al `iss` del token, incluido el esquema y sin barra final.
* `audiences` debe incluir el audience que solicita Devin (`databricks` en esta guía).
* `subject` debe ser igual al `sub` del token. El subject predeterminado es el ID de tu organización, por lo que todas las sesiones de la organización pueden autenticarse como este principal. Esta es la granularidad adecuada para Databricks, ya que las políticas de federación comparan el subject como una cadena literal. Los claims por sesión, como `devin_id`, cambian en cada sesión y no pueden coincidir con una política estática.
Deja `subject_claim`, `jwks_uri` y `jwks_json` sin definir. Databricks usa de forma predeterminada el claim `sub` y descubre el JWKS a partir del `/.well-known/openid-configuration` del issuer.
```bash theme={null}
databricks account service-principal-federation-policy create \
--policy-id devin-sessions \
--json @devin-federation-policy.json
```
Confirma que existe:
```bash theme={null}
databricks account service-principal-federation-policy list
```
El perfil que escribió el blueprint ya apunta a esta entidad de servicio, así que no hace falta recompilar. Continúa al [Paso 3](#step-3-grant-permissions).
### Recompilaciones y fijado de versiones
Tanto el script de instalación de Databricks como `setup-devin-oidc@main` siguen sus ramas `main` upstream, por lo que una compilación completa incorpora las versiones nuevas; una [compilación diferencial](/es/onboard-devin/environment/differential-builds) omite `initialize` y conserva las versiones que ya están en la instantánea hasta que cambie el blueprint. Si necesitas compilaciones reproducibles, descarga el instalador desde una etiqueta de versión en lugar de `main` (por ejemplo, `.../databricks/setup-cli/v1.17.0/install.sh`), que instala exactamente esa versión de la CLI, y fija la acción a un SHA de confirmación (`setup-devin-oidc@`).
## Paso 3: Otorgar permisos
La autenticación solo acredita quién es Devin. Lo que Devin puede ver o modificar lo definen los permisos del workspace y los permisos de Unity Catalog, que puedes ajustar en cualquier momento sin tocar el blueprint. Empieza con el perfil más restringido que sirva para la tarea y amplíalo de forma deliberada.
### Perfiles de permisos
| Perfil | Trabajo habitual | Permisos de Unity Catalog | Permisos del workspace |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Explore** (empieza aquí) | Responder preguntas sobre los datos, documentar schemas, investigar jobs fallidos y proponer correcciones de queries en un PR | `USE CATALOG`, `USE SCHEMA`, `SELECT`, `BROWSE` en los catálogos de producción; `READ VOLUME` allí donde Devin necesite archivos | `CAN USE` en un SQL warehouse; `CAN VIEW` en los jobs y procesos que Devin deba investigar |
| **Build** | Prototipar tablas, funciones y cuadernos en un sandbox; ejecutar pruebas con datos reales de solo lectura | Permisos de Explore en producción, más la propiedad de (o `ALL PRIVILEGES` sobre) un catálogo o schema `devin_dev` dedicado | Permisos de Explore, más `CAN MANAGE RUN` en los jobs del sandbox y una política de clúster restrictiva si Devin puede iniciar cómputo |
| **Operate** | Volver a ejecutar o reparar jobs de producción concretos una vez validados Explore y Build | Permisos de Explore, más `MODIFY` en las tablas concretas en las que escribe un job | `CAN MANAGE RUN` en los jobs concretos, concedido job por job y no a nivel de todo el workspace |
Las sentencias de permiso apuntan a la entidad de servicio mediante su ID de aplicación:
```sql theme={null}
-- Explore: solo lectura sobre el catálogo analytics de producción
GRANT USE CATALOG, BROWSE ON CATALOG analytics TO ``;
GRANT USE SCHEMA, SELECT ON SCHEMA analytics.gold TO ``;
GRANT READ VOLUME ON VOLUME analytics.gold.landing TO ``;
-- Build: un catálogo sandbox propiedad de Devin, aislado de producción
CREATE CATALOG IF NOT EXISTS devin_dev;
ALTER CATALOG devin_dev OWNER TO ``;
```
Si prefieres la administración basada en grupos, agrega la entidad de servicio a un grupo como `devin-agents` y otorga los permisos al grupo en su lugar.
Los cambios de código deben seguir pasando por pull requests. Devin puede leer datos de producción para comprender un problema y validar una corrección en el sandbox, pero el cambio en el cuaderno, la definición del job o el Asset Bundle se aplica mediante tu proceso de revisión habitual, no editando producción directamente.
## Paso 4: Instalar el plugin de skills de Databricks (opcional)
Databricks publica [Agent Skills](https://github.com/databricks/databricks-agent-skills) que enseñan a los coding agents los flujos de trabajo de Databricks: Asset Bundles, jobs, SQL, Unity Catalog y Spark. Instalarlas como un [plugin](/es/product-guides/plugins) de Devin le aporta a Devin ese conocimiento además del CLI.
1. Abre **Customize → Plugins** y elige **Add plugin → From repository**.
2. Ingresa el repositorio `databricks/databricks-agent-skills` y el subdirectorio `plugins/databricks/claude`. El manifest del plugin está en esa subcarpeta, así que al instalarlo desde el repository root aparece **No plugin manifest found**.
3. Instálalo en el ámbito de **Organization** si usaste un blueprint de organización en el paso 2. Si usaste un blueprint del repositorio, declara el plugin en el archivo `.devin/config.json` de ese repositorio (consulta [herencia y niveles](/es/cli/extensibility/plugins/overview#inheritance-and-levels)) para que solo las sesiones que tengan el CLI reciban también las skills.
4. [Fija el plugin a un commit](/es/product-guides/plugins#pinning-a-plugin) una vez que funcione, para que los cambios upstream no lleguen a tus sesiones sin revisar.
La skill principal del plugin recomienda ejecutar `databricks auth login` para configurar un profile. Ese flujo con navegador interactivo no puede completarse en una sesión de Devin desatendida y aquí no hace falta: la entrada `knowledge` del paso 2 le indica a Devin que el CLI ya está autenticado.
## Paso 5: Verificar
Inicia una nueva sesión (una vez que la compilación del blueprint se complete correctamente) y pídele a Devin que ejecute:
```bash theme={null}
databricks --version
databricks current-user me
```
`current-user me` debería devolver la entidad de servicio, con `userName` igual a su ID de aplicación. Para confirmar qué método de autenticación eligió la CLI:
```bash theme={null}
databricks auth describe
```
Para la Opción A, esto devuelve `oauth-m2m`; para la Opción B, `env-oidc`.
Que la autenticación sea correcta no significa que Devin pueda acceder a tus datos. Confirma que se apliquen los permisos del Paso 3:
```bash theme={null}
databricks catalogs list
databricks warehouses list
databricks grants get catalog
```
Reemplaza `` por un catálogo que hayas concedido en el Paso 3 (en los ejemplos se usa `analytics`). Luego pídele a Devin que ejecute una consulta pequeña de solo lectura sobre un warehouse en el que tenga `CAN USE` y, si configuraste un perfil de compilación, que cree y elimine una tabla en `devin_dev`. Una consulta sobre una tabla de producción en la que Devin no tenga `SELECT` debería fallar; ese fallo indica que el límite de permisos está funcionando.
## Solución de problemas
| Síntoma | Se aplica a | Causa y solución |
| --------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Errores sobre credenciales en conflicto o más de un método de autenticación | Opción A | Elimina `DATABRICKS_TOKEN`, `DATABRICKS_USERNAME` y cualquier perfil de `~/.databrickscfg`. La CLI no adivina cuando hay más de un método de autenticación configurado. |
| `DATABRICKS_OIDC_TOKEN` no está definido o está vacío | Opción B | Se omitió el wrapper o no está instalado. Comprueba que `which databricks` apunte al wrapper y que `devin-oidc token --audience databricks` funcione por sí solo. |
| `invalid_grant` o un error que menciona el subject | Opción B | El `subject` de la política no coincide exactamente con el `sub` del token. Vuelve a ejecutar el script de claims del paso 2 y compáralos carácter por carácter. |
| Error que menciona el audience | Opción B | El campo `audiences` de la política no incluye el audience que solicita el wrapper. Ambos usan `databricks` de forma predeterminada; mantenlos idénticos. |
| Error que menciona el issuer, JWKS o la firma | Opción B | `issuer` tiene un error tipográfico (barra final, `http`, host incorrecto) o Databricks no puede acceder a `https:///.well-known/jwks.json`. Carga esa URL desde fuera de tu red para confirmar que es pública. |
| Token expirado | Opción B | Los tokens de identidad de Devin duran 60 segundos. Usa el wrapper en lugar de generar un token manualmente. |
| La CLI no reconoce `env-oidc` | Opción B | La instantánea tiene una CLI antigua (o el package legacy de Python `databricks-cli`). Elimina el package antiguo del blueprint y vuelve a compilarlo. |
| Autenticado, pero `catalogs list` está vacío o se deniega una query | Ambas | El principal está autenticado pero no autorizado. Revisa la asignación del workspace (paso 1) y los grants de Unity Catalog (paso 3) con `databricks grants get catalog `. |
| Tiempos de espera de conexión o fallos de DNS | Ambas | El host del workspace no es accesible desde Devin. Agrégalo (y el host de la cuenta, si es necesario) a tu [política de red](/es/product-guides/security-profiles) de Devin. |
## Soporte
Para la configuración del lado de Databricks (entidades de servicio, secretos de OAuth, políticas de federación, Unity Catalog), consulta la [documentación de autenticación de Databricks](https://docs.databricks.com/aws/en/dev-tools/auth/) (cambia a la edición de Azure o GCP según corresponda). Para la configuración del lado de Devin (blueprints, OIDC, plugins, política de red), escribe a [support@cognition.ai](mailto:support@cognition.ai) o contacta con tu equipo de cuenta.