\
--json '{"permissions": ["USER"]}'
```
Utilisez `USER`, et non `ADMIN`. Devin n'a pas besoin des droits d'admin sur le workspace.
## Étape 2 : connecter Devin au service principal
Suivez **l'une** des deux options ci-dessous. Chacune se suffit à elle-même : elle installe la CLI Databricks via un [blueprint](/fr/onboard-devin/environment/blueprints) dans **Settings > Environment > Blueprints** et configure la CLI pour qu'elle s'authentifie en tant que service principal créé à l'étape 1.
* [**Option A : client secret OAuth**](#option-a-oauth-client-secret). [OAuth M2M](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) standard : le service principal reçoit un client secret, que vous stockez dans les Secrets de Devin. C'est la manière la plus rapide de démarrer.
* [**Option B : fédération de tokens OIDC**](#option-b-oidc-token-federation). Chaque session Devin peut générer un token OpenID Connect de courte durée signé par Devin. La [fédération de tokens](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) Databricks permet au service principal de faire confiance à cet issuer : Devin échange ainsi son propre token d'identité contre un token OAuth Databricks. Aucun secret Databricks n'est créé ni stocké, ce qui explique pourquoi Databricks recommande vivement cette approche pour les workloads automatisés.
Les jetons d'accès personnels (PAT) liés à un utilisateur humain ne sont recommandés pour aucune des deux options. Ils contournent le service principal, expirent de manière imprévisible et attribuent les actions de Devin à une personne.
### Option A : client secret OAuth
Vous préférez ne gérer aucun secret Databricks ? Passez directement à l'[Option B : fédération de tokens OIDC](#option-b-oidc-token-federation). Vous pouvez aussi commencer ici et basculer plus tard : remplacez le blueprint par celui de l'option B, créez la politique de fédération, puis supprimez le secret OAuth ainsi que le Devin Secret `DATABRICKS_CLIENT_SECRET`.
#### 1. Générer un secret OAuth
Dans la console du compte, ouvrez le service principal de l'étape 1 et générez un **secret OAuth**. Définissez la durée de vie la plus courte que votre processus de rotation permet (le maximum est de 730 jours) et limitez le secret aux périmètres d'API dont Devin a besoin, tels que `sql`, `jobs` et `unity-catalog`. Évitez de sélectionner tous les périmètres.
#### 2. Ajouter les Devin Secrets
Dans Devin, ajoutez les éléments suivants en tant que [Devin Secrets](/fr/product-guides/secrets) dans l'onglet **Secrets** du blueprint que vous modifierez ensuite (organisation ou repository) :
| Secret | Valeur |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABRICKS_HOST` | L'URL du **workspace** dans lequel Devin doit travailler, par exemple `https://dbc-xxxx.cloud.databricks.com` ou `https://adb-xxxx.azuredatabricks.net`, sans suffixe `/api`. Il ne s'agit pas de l'hôte `accounts.*`. |
| `DATABRICKS_CLIENT_ID` | L'`applicationId` du service principal (un UUID) obtenu à l'étape 1, et non l'`id` numérique |
| `DATABRICKS_CLIENT_SECRET` | Le secret OAuth que vous avez généré |
La CLI sélectionne automatiquement OAuth M2M dès qu'un client ID et un client secret sont présents : `DATABRICKS_AUTH_TYPE` n'est donc pas requis. Ne le définissez sur `oauth-m2m` que si vous souhaitez exclure explicitement toute autre méthode.
Les secrets sont injectés sous forme de variables d'environnement au démarrage de chaque nouvelle session : la CLI n'a donc besoin d'aucun fichier de profil. Un secret renouvelé prend effet dès la prochaine session, sans rebuild.
#### 3. Ajoutez le blueprint
Installe uniquement la CLI. L'authentification repose entièrement sur les trois secrets ci-dessus.
```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.
```
N'écrivez pas les secrets dans un fichier lors de l'étape `initialize` ; tout ce qui y est écrit se retrouve intégré au snapshot.
Ne définissez pas non plus `DATABRICKS_TOKEN` et ne laissez pas de profil `~/.databrickscfg` dans le snapshot. Des credentials en conflit sont la cause la plus fréquente d'échec de l'authentification M2M.
#### 4. Construire le snapshot
Enregistrez le blueprint et attendez que le build affiche **Success**, puis démarrez une nouvelle session. Les sessions existantes conservent l'ancien snapshot. Passez à l'[étape 3](#step-3-grant-permissions).
### Option B : fédération de tokens OIDC
Les sessions Devin génèrent des tokens d'identité de courte durée (`iss`, `sub`, `aud`), et une politique de fédération définie sur le service principal indique à Databricks de leur faire confiance. Le blueprint installe la CLI `devin-oidc`, encapsule `databricks` pour que chaque appel utilise un token récent, et écrit un profil qui pointe vers votre service principal. Vous lisez ensuite les claims du token depuis une session, puis vous créez une politique qui leur correspond.
Vous préférez emprunter le chemin le plus court ? Commencez par l'[option A](#option-a-oauth-client-secret) et revenez ici lorsque vous serez prêt à vous passer du secret stocké.
#### 1. Ajouter le blueprint
Deux espaces réservés dans le profil doivent être remplacés par vos propres valeurs :
| Espace réservé | Remplacer par |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `` | L'URL du **workspace** dans lequel Devin doit travailler, par exemple `https://dbc-xxxx.cloud.databricks.com` ou `https://adb-xxxx.azuredatabricks.net`, sans le suffixe `/api`. Il ne s'agit pas de l'hôte `accounts.*`. Il s'agit de la même valeur que `DATABRICKS_HOST` dans l'option A. |
| `` | L'`applicationId` du service principal (un UUID) renvoyé par `databricks account service-principals create` à l'étape 1. Il ne s'agit pas de l'`id` numérique, qui sert uniquement à attacher la politique de fédération. |
```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.
```
| Élément | Rôle |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `setup-devin-oidc` | Installe la CLI `devin-oidc` qui génère les tokens d'identité Devin ([détails](/fr/product-guides/oidc)). |
| Wrapper | Les tokens d'identité Devin expirent au bout de 60 secondes : chaque appel de la CLI génère donc le sien. |
| `auth_type = env-oidc` | Verrouille la CLI sur la fédération de tokens afin qu'elle ne se rabatte jamais sur un PAT ou une connexion interactive. |
| `host` / `client_id` | L'URL du workspace et l'`applicationId` du service principal indiqués dans le tableau ci-dessus. |
| `audience` | L'audience demandée par le wrapper, celle que vous renseignerez dans la politique de fédération ci-dessous. |
| `knowledge` | Indique à Devin que la CLI est déjà authentifiée, pour qu'il ne tente pas `databricks auth login`. |
Le profil ne contient aucun secret : il peut donc être écrit sans risque pendant l'`initialize`. Si vous passez de l'option A à celle-ci, supprimez le Devin Secret `DATABRICKS_CLIENT_SECRET` une fois la politique ci-dessous en place, afin que la CLI ne voie pas deux credentials.
#### 2. Construire le snapshot
Enregistrez le blueprint et attendez que le build affiche **Success**. Aucun élément du blueprint ne dépend de la politique de fédération que vous allez créer ensuite : vous n'aurez donc pas besoin de relancer le build par la suite.
#### 3. Créer la politique de fédération
Une fois le blueprint construit, les sessions Devin peuvent émettre des tokens d'identité. Utilisez-en un pour lire les claims exacts auxquels Databricks doit faire confiance, puis créez sur le service principal une politique de fédération qui leur correspond.
Démarrez une nouvelle session Devin et demandez-lui d'exécuter la commande suivante. Elle n'affiche que les claims d'identité du token, jamais le token lui-même.
```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))'
```
Forme attendue :
```json theme={null}
{
"iss": "https://app.devin.ai",
"sub": "org_id:",
"aud": "databricks"
}
```
Sur les déploiements Enterprise, `iss` correspond à votre URL Devin personnalisée (par exemple `https://yourcompany.devinenterprise.com`). Copiez `iss` et `sub` exactement tels qu'ils s'affichent. Ne collez pas le token brut dans des tickets ou des documents : il constitue un credential porteur valable pendant les 60 secondes qui suivent.
Enregistrez ce contenu sous le nom `devin-federation-policy.json`, en y substituant les valeurs de l'étape précédente :
```json theme={null}
{
"description": "Allow Devin sessions to authenticate as the devin-sessions service principal",
"oidc_policy": {
"issuer": "https://",
"audiences": ["databricks"],
"subject": "org_id:"
}
}
```
Les trois champs exigent une correspondance exacte :
* `issuer` doit être identique au `iss` du token, schéma inclus et sans barre oblique finale.
* `audiences` doit inclure l'audience demandée par Devin (`databricks` dans ce guide).
* `subject` doit être identique au `sub` du token. Le subject par défaut est l'ID de votre organisation : toutes les sessions de l'organisation peuvent donc s'authentifier en tant que ce principal. C'est la granularité adaptée à Databricks, car les politiques de fédération comparent le subject comme une chaîne littérale. Les claims propres à une session, comme `devin_id`, changent à chaque session et ne peuvent pas être mis en correspondance par une politique statique.
Laissez `subject_claim`, `jwks_uri` et `jwks_json` non définis. Databricks utilise par défaut le claim `sub` et découvre le JWKS via le `/.well-known/openid-configuration` de l'issuer.
```bash theme={null}
databricks account service-principal-federation-policy create \
--policy-id devin-sessions \
--json @devin-federation-policy.json
```
Vérifiez son existence :
```bash theme={null}
databricks account service-principal-federation-policy list
```
Le profil écrit par le blueprint pointe déjà vers ce service principal : aucun rebuild n'est donc nécessaire. Passez à l'[étape 3](#step-3-grant-permissions).
### Rebuilds et épinglage des versions
Le script d'installation Databricks et `setup-devin-oidc@main` suivent tous deux leurs branches `main` en amont : un full build récupère donc les nouvelles releases, tandis qu'un [build différentiel](/fr/onboard-devin/environment/differential-builds) ignore `initialize` et conserve les versions déjà présentes dans le snapshot tant que le blueprint n'est pas modifié. Si vous avez besoin de builds reproductibles, récupérez l'installateur depuis une balise de release plutôt que depuis `main` (par exemple `.../databricks/setup-cli/v1.17.0/install.sh`), ce qui installe précisément cette version du CLI, et épinglez l'action à un SHA de commit (`setup-devin-oidc@`).
## Étape 3 : Accorder les autorisations
L'authentification ne fait qu'établir l'identité de Devin. Ce que Devin peut consulter ou modifier dépend des autorisations du workspace et des autorisations Unity Catalog, que vous pouvez ajuster à tout moment sans toucher au blueprint. Commencez par le profil le plus restreint adapté au travail à réaliser, puis élargissez-le de manière réfléchie.
### Profils d'autorisations
| Profil | Travaux types | Autorisations Unity Catalog | Autorisations du workspace |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Explore** (commencez ici) | Répondre à des questions sur les données, documenter des schémas, analyser des jobs en échec, proposer des correctifs de requêtes dans une PR | `USE CATALOG`, `USE SCHEMA`, `SELECT`, `BROWSE` sur les catalogues de production ; `READ VOLUME` lorsque Devin a besoin d'accéder à des fichiers | `CAN USE` sur un entrepôt SQL ; `CAN VIEW` sur les jobs et pipelines que Devin doit analyser |
| **Build** | Prototyper des tables, des fonctions et des notebooks dans un sandbox ; exécuter des tests sur de vraies données en lecture seule | Autorisations Explore sur la production, plus la propriété (ou `ALL PRIVILEGES`) d'un catalogue ou schéma `devin_dev` dédié | Autorisations Explore, plus `CAN MANAGE RUN` sur les jobs du sandbox et une politique de cluster restrictive si Devin est autorisé à démarrer des ressources de calcul |
| **Operate** | Relancer ou réparer des jobs de production spécifiques une fois Explore et Build éprouvés | Autorisations Explore, plus `MODIFY` sur les tables spécifiques dans lesquelles un job écrit | `CAN MANAGE RUN` sur les jobs spécifiques, accordé job par job plutôt qu'à l'échelle du workspace |
Les statements d'autorisation ciblent le service principal via son ID d'application :
```sql theme={null}
-- Explore : lecture seule sur le catalog analytics de production
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 appartenant à Devin, isolé de la production
CREATE CATALOG IF NOT EXISTS devin_dev;
ALTER CATALOG devin_dev OWNER TO ``;
```
Si vous préférez une administration par groupes, ajoutez le service principal à un groupe tel que `devin-agents` et accordez plutôt les autorisations à ce groupe.
Les modifications de code doivent toujours passer par des pull requests. Devin peut lire les données de production pour comprendre un problème et valider un correctif dans le sandbox, mais la modification du notebook, de la définition de job ou de l'Asset Bundle doit être intégrée via votre processus de review habituel, et non en modifiant directement la production.
## Étape 4 : installer le plugin skills Databricks (facultatif)
Databricks publie des [Agent Skills](https://github.com/databricks/databricks-agent-skills) qui enseignent aux coding agents les workflows Databricks : Asset Bundles, jobs, SQL, Unity Catalog et Spark. Les installer en tant que [plugin](/fr/product-guides/plugins) Devin apporte à Devin ce savoir-faire, en complément de la CLI.
1. Ouvrez **Customize → Plugins**, puis choisissez **Add plugin → From repository**.
2. Saisissez le repository `databricks/databricks-agent-skills` et le sous-répertoire `plugins/databricks/claude`. Le manifeste du plugin se trouve dans ce sous-dossier : une installation depuis le repository root renvoie donc **No plugin manifest found**.
3. Installez au périmètre **Organization** si vous avez utilisé un blueprint d’organisation à l’étape 2. Si vous avez utilisé un repository blueprint, déclarez plutôt le plugin dans le fichier `.devin/config.json` de ce repository (voir [héritage et niveaux](/fr/cli/extensibility/plugins/overview#inheritance-and-levels)) : ainsi, seules les sessions disposant de la CLI obtiendront aussi les skills.
4. [Épinglez le plugin à un commit](/fr/product-guides/plugins#pinning-a-plugin) une fois qu’il fonctionne, afin que les modifications en amont n’arrivent pas dans vos sessions sans avoir été relues.
La skill principale du plugin recommande d’exécuter `databricks auth login` pour configurer un profil. Ce flux interactif dans le navigateur ne peut pas aboutir dans une session Devin sans supervision, et il est inutile ici : l’entrée `knowledge` de l’étape 2 indique à Devin que la CLI est déjà authentifiée.
## Étape 5 : Vérifier
Démarrez une nouvelle session (une fois le build du blueprint réussi) et demandez à Devin d'exécuter :
```bash theme={null}
databricks --version
databricks current-user me
```
`current-user me` doit renvoyer le service principal, avec `userName` égal à son ID d'application. Pour vérifier quelle méthode d'authentification la CLI a retenue :
```bash theme={null}
databricks auth describe
```
Pour l'option A, cela renvoie `oauth-m2m` ; pour l'option B, `env-oidc`.
Une authentification réussie ne signifie pas pour autant que Devin peut accéder à vos données. Vérifiez que les autorisations accordées à l'étape 3 s'appliquent bien :
```bash theme={null}
databricks catalogs list
databricks warehouses list
databricks grants get catalog
```
Remplacez `` par un catalogue auquel vous avez donné accès à l'étape 3 (les exemples utilisent `analytics`). Demandez ensuite à Devin d'exécuter une petite requête en lecture seule sur un entrepôt sur lequel il dispose du droit `CAN USE` et, si vous avez configuré un profil Build, de créer puis de supprimer une table dans `devin_dev`. Une requête sur une table de production pour laquelle Devin ne dispose pas du droit `SELECT` doit échouer : cet échec montre que la limite d'autorisations fonctionne.
## Dépannage
| Symptôme | S'applique à | Cause et correctif |
| ------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Erreurs signalant des credentials en conflit ou plusieurs méthodes d'authentification | Option A | Supprimez `DATABRICKS_TOKEN`, `DATABRICKS_USERNAME` et tout profil `~/.databrickscfg`. La CLI refuse de deviner lorsque plusieurs méthodes d'authentification sont configurées. |
| `DATABRICKS_OIDC_TOKEN` non défini ou vide | Option B | Le wrapper a été contourné ou n'est pas installé. Vérifiez que `which databricks` pointe bien vers le wrapper et que `devin-oidc token --audience databricks` fonctionne seul. |
| `invalid_grant` ou une erreur mentionnant le subject | Option B | Le `subject` de la politique n'est pas strictement identique au `sub` du token. Réexécutez le script de claims de l'étape 2 et comparez caractère par caractère. |
| Erreur mentionnant l'audience | Option B | Les `audiences` de la politique n'incluent pas l'audience demandée par le wrapper. Les deux valent `databricks` par défaut ; gardez-les identiques. |
| Erreur mentionnant l'issuer, JWKS ou la signature | Option B | `issuer` contient une faute de frappe (barre oblique finale, `http`, mauvais hôte) ou Databricks n'arrive pas à joindre `https:///.well-known/jwks.json`. Chargez cette URL depuis l'extérieur de votre réseau pour confirmer qu'elle est publique. |
| Token expiré | Option B | Les tokens d'identité Devin ont une durée de vie de 60 secondes. Utilisez le wrapper plutôt que de générer un token manuellement. |
| La CLI ne reconnaît pas `env-oidc` | Option B | Le snapshot contient une ancienne CLI (ou l'ancien package Python `databricks-cli`). Supprimez l'ancien package du blueprint et relancez le build. |
| Authentifié, mais `catalogs list` est vide ou une requête est refusée | Les deux | Le principal est authentifié, mais pas autorisé. Vérifiez l'attribution au workspace (étape 1) et les autorisations Unity Catalog (étape 3) avec `databricks grants get catalog `. |
| Délais d'expiration de connexion ou échecs DNS | Les deux | L'hôte du workspace n'est pas joignable depuis Devin. Ajoutez-le (ainsi que l'hôte du compte, si nécessaire) à votre [politique réseau](/fr/product-guides/security-profiles) Devin. |
## Support
Pour la configuration côté Databricks (service principals, secrets OAuth, politiques de fédération, Unity Catalog), consultez la [documentation d'authentification Databricks](https://docs.databricks.com/aws/en/dev-tools/auth/) (passez à l'édition Azure ou GCP selon vos besoins). Pour la configuration côté Devin (blueprints, OIDC, plugins, politique réseau), contactez [support@cognition.ai](mailto:support@cognition.ai) ou votre équipe de compte.