\
--json '{"permissions": ["USER"]}'
```
Usa `USER`, non `ADMIN`. Devin non ha bisogno dei permessi di admin del workspace.
## Passaggio 2: collegare Devin al service principal
Segui **una** delle due opzioni seguenti. Ciascuna è completa di per sé: installa la CLI di Databricks tramite un [blueprint](/it/onboard-devin/environment/blueprints) in **Settings > Environment > Blueprints** e configura la CLI per autenticarsi come il service principal creato nel Passaggio 1.
* [**Opzione A: client secret OAuth**](#option-a-oauth-client-secret). [OAuth M2M](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) standard: al service principal viene assegnato un client secret, che memorizzi in Devin Secrets. È il modo più rapido per iniziare.
* [**Opzione B: federazione dei token OIDC**](#option-b-oidc-token-federation). Ogni sessione Devin può generare un token OpenID Connect di breve durata firmato da Devin. La [federazione dei token](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) di Databricks consente al service principal di considerare attendibile quell'issuer, così Devin scambia il proprio token di identità con un token OAuth di Databricks. Nessun segreto di Databricks viene mai creato o memorizzato: è per questo che Databricks la consiglia vivamente per i workload automatizzati.
I token di accesso personale (PAT) associati a un utente umano non sono consigliati per nessuna delle due opzioni: aggirano il service principal, scadono in modo imprevedibile e attribuiscono le azioni di Devin a una persona.
### Opzione A: client secret OAuth
Preferisci non gestire alcun secret Databricks? Vai direttamente a [Opzione B: federazione dei token OIDC](#option-b-oidc-token-federation). Puoi anche partire da qui e cambiare in seguito: sostituisci il blueprint con quello dell'Opzione B, crea la policy di federazione, quindi elimina il secret OAuth e il Devin Secret `DATABRICKS_CLIENT_SECRET`.
#### 1. Genera un OAuth secret
Nella console dell'account, apri il service principal del passaggio 1 e genera un **OAuth secret**. Imposta la durata più breve consentita dal tuo processo di rotazione (il massimo è 730 giorni) e limita il secret agli ambiti API necessari a Devin, come `sql`, `jobs` e `unity-catalog`. Evita di selezionare tutti gli ambiti.
#### 2. Aggiungi i Devin Secrets
In Devin, aggiungi i seguenti valori come [Devin Secrets](/it/product-guides/secrets) nella tab **Secrets** del blueprint che modificherai subito dopo (organizzazione o repository):
| Segreto | Valore |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABRICKS_HOST` | L'URL del **workspace** in cui Devin deve operare, ad esempio `https://dbc-xxxx.cloud.databricks.com` o `https://adb-xxxx.azuredatabricks.net`, senza il suffisso `/api`. Non l'host `accounts.*`. |
| `DATABRICKS_CLIENT_ID` | L'`applicationId` del service principal (un UUID) ottenuto al passaggio 1, non l'`id` numerico |
| `DATABRICKS_CLIENT_SECRET` | Il segreto OAuth che hai generato |
La CLI seleziona automaticamente OAuth M2M quando sono presenti un client ID e un client secret, quindi `DATABRICKS_AUTH_TYPE` non è necessario. Impostalo su `oauth-m2m` solo se vuoi escludere esplicitamente ogni altro metodo.
I segreti vengono iniettati come variabili d'ambiente all'avvio di ogni nuova sessione, quindi la CLI non necessita di alcun file di profile. Un segreto ruotato ha effetto dalla sessione successiva, senza bisogno di un rebuild.
#### 3. Aggiungi il blueprint
Installa solo la CLI. L'authentication deriva interamente dai tre segreti sopra indicati.
```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.
```
Non scrivere i segreti in un file durante `initialize`; tutto ciò che viene scritto lì finisce incorporato nello snapshot.
Non impostare anche `DATABRICKS_TOKEN` e non lasciare un profile `~/.databrickscfg` nello snapshot. Le credenziali in conflitto sono la causa più comune di fallimento dell'authentication M2M.
#### 4. Esegui il build dello snapshot
Salva il blueprint e attendi che il build mostri **Success**, quindi avvia una nuova sessione. Le sessioni esistenti mantengono lo snapshot precedente. Prosegui con il [Passaggio 3](#step-3-grant-permissions).
### Opzione B: federazione dei token OIDC
Le sessioni Devin generano token di identità di breve durata (`iss`, `sub`, `aud`) e una policy di federazione sul service principal indica a Databricks di considerarli attendibili. Il blueprint installa la CLI `devin-oidc`, incapsula `databricks` in modo che ogni chiamata includa un token aggiornato e scrive un profilo che punta al tuo service principal. A quel punto puoi leggere i claim del token da una sessione e creare una policy che li rispecchi.
Vuoi prima il percorso più rapido? Inizia con l'[Opzione A](#option-a-oauth-client-secret) e torna qui quando sei pronto a rinunciare al secret memorizzato.
#### 1. Aggiungi il blueprint
Nel profile occorre sostituire due segnaposto con i tuoi valori:
| Segnaposto | Sostituisci con |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` | L'URL del **workspace** in cui Devin deve operare, per esempio `https://dbc-xxxx.cloud.databricks.com` o `https://adb-xxxx.azuredatabricks.net`, senza il suffisso `/api`. Non l'host `accounts.*`. È lo stesso valore di `DATABRICKS_HOST` nell'Opzione A. |
| `` | L'`applicationId` del service principal (un UUID) restituito dall'output di `databricks account service-principals create` nel Passaggio 1. Non l'`id` numerico, che serve solo a collegare la policy di federazione. |
```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 | Scopo |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| `setup-devin-oidc` | Installa la CLI `devin-oidc` che genera i token di identità di Devin ([dettagli](/it/product-guides/oidc)). |
| Wrapper | I token di identità di Devin scadono dopo 60 secondi, quindi ogni chiamata della CLI genera il proprio. |
| `auth_type = env-oidc` | Blocca la CLI sulla token federation, così da non ricorrere mai a un PAT o a un login interattivo. |
| `host` / `client_id` | L'URL del workspace e l'`applicationId` del service principal riportati nella tabella sopra. |
| `audience` | L'audience richiesta dal wrapper, la stessa che inserirai nella federation policy qui sotto. |
| `knowledge` | Comunica a Devin che la CLI è già autenticata, così non tenta `databricks auth login`. |
Il profile non contiene alcun secret, quindi può essere scritto senza rischi durante l'`initialize`. Se stai passando dall'Opzione A, rimuovi il Devin Secret `DATABRICKS_CLIENT_SECRET` una volta attiva la policy descritta qui sotto, così la CLI non rileva due credenziali.
#### 2. Crea lo snapshot
Salva il blueprint e attendi che la build mostri **Success**. Nel blueprint non c'è nulla che dipenda dalla policy di federazione che creerai al passaggio successivo, quindi non dovrai rieseguire la build in seguito.
#### 3. Creare la policy di federazione
Una volta creato il blueprint, le sessioni Devin possono generare token di identità. Usane uno per leggere i claim esatti che Databricks deve considerare attendibili, quindi crea sul service principal una policy di federazione che vi corrisponda.
Avvia una nuova sessione Devin e chiedile di eseguire il comando seguente. Stampa solo i claim di identità del token, mai il token stesso.
```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))'
```
Struttura prevista:
```json theme={null}
{
"iss": "https://app.devin.ai",
"sub": "org_id:",
"aud": "databricks"
}
```
Nelle distribuzioni enterprise, `iss` corrisponde al tuo URL Devin personalizzato (ad esempio `https://yourcompany.devinenterprise.com`). Copia `iss` e `sub` esattamente come vengono stampati. Non incollare il token grezzo in ticket o documenti: è una credenziale bearer valida per i successivi 60 secondi.
Salva quanto segue come `devin-federation-policy.json`, sostituendo i valori ottenuti al passaggio precedente:
```json theme={null}
{
"description": "Allow Devin sessions to authenticate as the devin-sessions service principal",
"oidc_policy": {
"issuer": "https://",
"audiences": ["databricks"],
"subject": "org_id:"
}
}
```
Tutti e tre i campi richiedono una corrispondenza esatta:
* `issuer` deve essere uguale al claim `iss` del token, schema incluso e senza barra finale.
* `audiences` deve includere l'audience richiesta da Devin (`databricks` in questa guida).
* `subject` deve essere uguale al claim `sub` del token. Il subject predefinito è l'ID della tua organizzazione, quindi ogni sessione dell'organizzazione può autenticarsi come questo principal. È la granularità corretta per Databricks, perché le policy di federazione confrontano il subject come stringa letterale. I claim specifici della singola sessione, come `devin_id`, cambiano a ogni sessione e non possono essere abbinati da una policy statica.
Lascia `subject_claim`, `jwks_uri` e `jwks_json` non impostati. Databricks usa per impostazione predefinita il claim `sub` e individua il JWKS tramite l'endpoint `/.well-known/openid-configuration` dell'issuer.
```bash theme={null}
databricks account service-principal-federation-policy create \
--policy-id devin-sessions \
--json @devin-federation-policy.json
```
Verifica che esista:
```bash theme={null}
databricks account service-principal-federation-policy list
```
Il profilo scritto dal blueprint punta già a questo service principal, quindi non è necessaria alcuna ricostruzione. Prosegui con il [Passaggio 3](#step-3-grant-permissions).
### Rebuild e blocco delle versioni
Sia lo script di installazione di Databricks sia `setup-devin-oidc@main` seguono i rispettivi branch `main` upstream, quindi una build completa include le nuove release; una [build differenziale](/it/onboard-devin/environment/differential-builds) salta `initialize` e mantiene le versioni già presenti nello snapshot finché il blueprint non cambia. Se ti servono build riproducibili, scarica l'installer da un tag di release anziché da `main` (per esempio `.../databricks/setup-cli/v1.17.0/install.sh`), così da installare esattamente quella versione della CLI, e blocca l'action su uno SHA di commit (`setup-devin-oidc@`).
## Passaggio 3: concedere le autorizzazioni
L'authentication dimostra soltanto chi è Devin. Ciò che Devin può vedere o modificare dipende invece dalle autorizzazioni del workspace e dalle concessioni di Unity Catalog, che puoi modificare in qualsiasi momento senza intervenire sul blueprint. Parti dal profilo più ristretto adatto al lavoro da svolgere ed ampliarlo solo quando serve.
### Profili di autorizzazione
| Profilo | Attività tipiche | Concessioni Unity Catalog | Autorizzazioni workspace |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Explore** (inizia da qui) | Rispondere a domande sui dati, documentare gli schema, analizzare i job falliti, proporre soluzioni alle query in una PR | `USE CATALOG`, `USE SCHEMA`, `SELECT`, `BROWSE` sui catalog di produzione; `READ VOLUME` dove Devin necessita di file | `CAN USE` su un SQL warehouse; `CAN VIEW` sui job e sulle pipeline che Devin deve analizzare |
| **Build** | Prototipare tabelle, funzioni e notebook in una sandbox; eseguire test su dati reali in sola lettura | Concessioni Explore in produzione, più la proprietà di (o `ALL PRIVILEGES` su) un catalog o schema `devin_dev` dedicato | Autorizzazioni Explore, più `CAN MANAGE RUN` sui job sandbox e una cluster policy restrittiva se Devin può avviare risorse di calcolo |
| **Operate** | Rieseguire o riparare job di produzione specifici dopo aver validato Explore e Build | Concessioni Explore, più `MODIFY` sulle tabelle specifiche su cui scrive un job | `CAN MANAGE RUN` sui job specifici, concesso per singolo job anziché a livello di workspace |
Le istruzioni di concessione fanno riferimento al service principal tramite il suo ID applicazione:
```sql theme={null}
-- Explore: sola lettura sul catalog analytics di produzione
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 catalog sandbox di proprietà di Devin, isolato dalla produzione
CREATE CATALOG IF NOT EXISTS devin_dev;
ALTER CATALOG devin_dev OWNER TO ``;
```
Se preferisci un'amministrazione basata su gruppi, aggiungi il service principal a un gruppo come `devin-agents` e concedi i permessi al gruppo anziché al singolo principal.
Le modifiche al codice dovrebbero comunque passare dalle pull request. Devin può leggere i dati di produzione per comprendere un problema e validare una soluzione nella sandbox, ma la modifica al notebook, alla definizione del job o all'Asset Bundle viene applicata tramite il tuo normale processo di review, non intervenendo direttamente sulla produzione.
## Passaggio 4: installare il plugin delle skill di Databricks (opzionale)
Databricks pubblica [Agent Skills](https://github.com/databricks/databricks-agent-skills) che insegnano ai coding agent i flussi di lavoro Databricks: Asset Bundles, job, SQL, Unity Catalog e Spark. Installarle come [plugin](/it/product-guides/plugins) di Devin fornisce a Devin queste competenze, oltre alla CLI.
1. Apri **Customize → Plugins** e scegli **Add plugin → From repository**.
2. Inserisci il repository `databricks/databricks-agent-skills` e la sottodirectory `plugins/databricks/claude`. Il manifest del plugin si trova in quella sottocartella, quindi l'installazione dalla repository root restituisce **No plugin manifest found**.
3. Installa nell'ambito **Organization** se al Passaggio 2 hai usato un blueprint di organizzazione. Se invece hai usato un blueprint del repository, dichiara il plugin nel file `.devin/config.json` di quel repository (vedi [ereditarietà e livelli](/it/cli/extensibility/plugins/overview#inheritance-and-levels)): in questo modo solo le sessioni che dispongono della CLI otterranno anche le skill.
4. [Blocca il plugin su un commit](/it/product-guides/plugins#pinning-a-plugin) una volta verificato che funziona, così le modifiche upstream non finiranno nelle tue sessioni senza essere state esaminate.
La skill principale del plugin consiglia di eseguire `databricks auth login` per configurare un profile. Quel flusso interattivo via browser non può essere completato in una sessione Devin non presidiata e qui non è necessario: la voce `knowledge` del Passaggio 2 indica a Devin che la CLI è già autenticata.
## Passaggio 5: verifica
Avvia una nuova sessione (una volta completato con successo il build del blueprint) e chiedi a Devin di eseguire:
```bash theme={null}
databricks --version
databricks current-user me
```
`current-user me` dovrebbe restituire il service principal, con `userName` uguale al suo ID applicazione. Per verificare quale metodo di authentication ha scelto la CLI:
```bash theme={null}
databricks auth describe
```
Per l'opzione A viene riportato `oauth-m2m`; per l'opzione B, `env-oidc`.
Un'authentication riuscita non significa che Devin possa accedere ai tuoi dati. Verifica che le concessioni del passaggio 3 siano attive:
```bash theme={null}
databricks catalogs list
databricks warehouses list
databricks grants get catalog
```
Sostituisci `` con un catalog concesso al Passaggio 3 (negli esempi viene usato `analytics`). Poi chiedi a Devin di eseguire una piccola query in sola lettura su un warehouse su cui dispone di `CAN USE` e, se hai configurato un profilo Build, di creare ed eliminare una tabella in `devin_dev`. Una query su una tabella di produzione su cui Devin non ha `SELECT` dovrebbe fallire: proprio quel fallimento dimostra che il confine delle autorizzazioni funziona.
## Troubleshooting
| Sintomo | Si applica a | Causa e soluzione |
| --------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Errori relativi a credenziale in conflitto o a più di un metodo di autenticazione | Opzione A | Rimuovi `DATABRICKS_TOKEN`, `DATABRICKS_USERNAME` e qualsiasi profile `~/.databrickscfg`. La CLI non tenta di indovinare quando è configurato più di un metodo di autenticazione. |
| `DATABRICKS_OIDC_TOKEN` non impostato o vuoto | Opzione B | Il wrapper è stato aggirato o non è installato. Verifica che `which databricks` punti al wrapper e che `devin-oidc token --audience databricks` funzioni autonomamente. |
| `invalid_grant` o un errore che menziona il subject | Opzione B | Il `subject` della policy non corrisponde esattamente al `sub` del token. Esegui di nuovo lo script dei claims del Passaggio 2 e confronta carattere per carattere. |
| Errore che menziona l'audience | Opzione B | Il campo `audiences` della policy non include l'audience richiesta dal wrapper. Per entrambi il valore di default è `databricks`; mantienili identici. |
| Errore che menziona l'issuer, JWKS o la firma | Opzione B | `issuer` contiene un errore di battitura (barra finale, `http`, host errato) oppure Databricks non riesce a raggiungere `https:///.well-known/jwks.json`. Apri quell'URL dall'esterno della tua rete per confermare che sia public. |
| Token scaduto | Opzione B | I token di identity di Devin hanno una durata di 60 secondi. Usa il wrapper invece di generare un token manualmente. |
| La CLI non riconosce `env-oidc` | Opzione B | Lo snapshot contiene una CLI datata (oppure il package Python legacy `databricks-cli`). Rimuovi il package obsoleto dal blueprint ed esegui il rebuild. |
| Autenticazione riuscita ma `catalogs list` è vuoto o una query viene negata | Entrambe | Il principal è autenticato ma non autorizzato. Verifica l'assignment al workspace (Passaggio 1) e i grant di Unity Catalog (Passaggio 3) con `databricks grants get catalog `. |
| Timeout di connessione o errori DNS | Entrambe | L'host del workspace non è raggiungibile da Devin. Aggiungilo (e, se necessario, anche l'host dell'account) alla tua [network policy](/it/product-guides/security-profiles) di Devin. |
## Supporto
Per la configurazione lato Databricks (service principal, secret OAuth, policy di federazione, Unity Catalog), consulta la [documentazione sull'authentication di Databricks](https://docs.databricks.com/aws/en/dev-tools/auth/) (passa all'edizione Azure o GCP se necessario). Per la configurazione lato Devin (blueprint, OIDC, plugin, network policy), contatta [support@cognition.ai](mailto:support@cognition.ai) o il tuo account team.