Application Default Credentials (ADC) est la source de confusion la plus fréquente en matière d’authentification dans l’écosystème GCP. Cette confusion vient de l’existence de deux mécanismes d’authentification distincts qui se ressemblent mais servent des objectifs différents — et la plupart des équipes n’en configurent qu’un seul.
Deux mécanismes d’authentification
gcloud auth login authentifie le CLI gcloud. Lorsque vous exécutez gcloud projects list ou bq query --sql "SELECT 1", c’est cette credential qui est utilisée. Il s’agit de votre identité pour les outils en ligne de commande Google Cloud.
gcloud auth application-default login configure Application Default Credentials. Il s’agit d’une credential distincte utilisée par les applications, les SDK et les bibliothèques qui appellent les API Google Cloud de manière programmatique. Lorsqu’un script Python utilise google.cloud.bigquery.Client(), ou lorsque le MCP Toolbox se connecte à BigQuery, ils utilisent ADC — pas vos credentials CLI gcloud.
Vous avez besoin des deux. L’un n’implique pas l’autre.
# Authentifie les commandes CLI gcloudgcloud auth login
# Configure ADC pour les applications et les SDKgcloud auth application-default loginLa seconde commande ouvre un navigateur pour le consentement OAuth. Une fois approuvé, les credentials sont stockées dans ~/.config/gcloud/application_default_credentials.json. Toute application recherchant ADC consulte ce fichier.
Pourquoi deux mécanismes existent
Cette distinction existe parce que les commandes CLI gcloud et le code applicatif ont des besoins d’authentification différents.
Le CLI gcloud est un outil interactif. Il s’authentifie en tant que vous — votre identité Google, vos permissions, votre piste d’audit. La credential est limitée au CLI et ne fuit pas vers les applications s’exécutant sur votre machine.
Les applications et les SDK ont besoin de credentials utilisables de manière programmatique, sans invites interactives. ADC fournit un moyen standardisé pour toute bibliothèque cliente Google Cloud de trouver des credentials, quel que soit l’environnement d’exécution du code. Le même code applicatif fonctionne en local (en utilisant votre ADC depuis gcloud auth application-default login), dans Cloud Run (en utilisant le compte de service attaché), dans GKE (en utilisant Workload Identity), ou dans une VM (en utilisant le compte de service de l’instance de calcul).
Cette portabilité est l’objectif principal. Vous écrivez votre code une fois, et ADC résout la credential appropriée pour l’environnement.
La chaîne de résolution des credentials
Lorsqu’une application utilise ADC, les bibliothèques clientes de Google vérifient les credentials dans cet ordre :
- Variable d’environnement
GOOGLE_APPLICATION_CREDENTIALS— si définie, utilise le fichier de clé de compte de service à ce chemin - Credentials utilisateur depuis
gcloud auth application-default login— le fichier à~/.config/gcloud/application_default_credentials.json - Compte de service attaché — dans Cloud Run, GKE, Compute Engine, le service de métadonnées de l’instance fournit automatiquement des credentials
Pour le développement local, la plupart des équipes utilisent le point 2. En production, on préfère généralement le point 1 (compte de service explicite) ou le point 3 (compte de service attaché).
Le problème d’authentification MCP
Cette configuration à double mécanisme explique précisément pourquoi l’authentification pour les serveurs MCP pose problème. Le mode d’échec typique :
- Le développeur exécute
gcloud auth login(déjà fait, car il utilise gcloud régulièrement) - Le développeur installe le MCP Toolbox et le lance
- Le Toolbox tente d’utiliser ADC
- ADC n’a jamais été configuré
- Le Toolbox échoue silencieusement ou retourne des résultats vides
- Le développeur suppose que le serveur MCP est défaillant
La solution est toujours la même : gcloud auth application-default login, puis redémarrer le client MCP.
Le serveur MCP distant contourne ce problème dans Claude Desktop en gérant OAuth en interne. Mais lors de l’utilisation du Toolbox, ADC est le chemin d’authentification.
Comptes de service pour la production
En production, ne vous fiez pas à votre ADC personnel. Créez un compte de service dédié avec des permissions minimales et définissez GOOGLE_APPLICATION_CREDENTIALS :
# Créer le compte de servicegcloud iam service-accounts create bigquery-mcp \ --display-name="BigQuery MCP Service Account"
# Accorder les rôles minimaux requisgcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:bigquery-mcp@PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/bigquery.user"
gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:bigquery-mcp@PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/bigquery.dataViewer"
# Créer et télécharger le fichier de clégcloud iam service-accounts keys create bigquery-mcp-key.json \ --iam-account=bigquery-mcp@PROJECT_ID.iam.gserviceaccount.comPointez ensuite ADC vers la clé :
export GOOGLE_APPLICATION_CREDENTIALS="/chemin/vers/bigquery-mcp-key.json"Faites pivoter la clé périodiquement. La note BigQuery IAM Patterns couvre la stratégie plus large des comptes de service — notamment pourquoi Workload Identity Federation est préférable aux fichiers de clés lors de l’exécution dans des environnements GCP.
L’obligation de redémarrage
Un comportement critique : la plupart des applications (y compris les serveurs MCP) lisent ADC une seule fois au démarrage. Si vous mettez à jour vos credentials pendant que l’application est en cours d’exécution, elle ne prendra pas en compte le changement. Vous devez redémarrer l’application après avoir modifié les credentials.
Avec Claude Code, cela signifie parfois redémarrer deux fois : une fois pour la configuration du serveur MCP, et une fois pour que les nouvelles credentials prennent effet.