Pièges de la configuration OAuth CLI de Google

La configuration manuelle de Google OAuth pour les outils CLI présente trois modes d’échec courants qui sont faciles à éviter une fois identifiés. Le fil Hacker News pour le CLI gws documentait des utilisateurs passant 30 à 45 minutes sur ces pièges. Les patterns s’appliquent à tout outil CLI utilisant Google OAuth, pas seulement à gws.

Le chemin le plus rapide : configuration automatisée

Avant de passer par le flux manuel, vérifiez si l’outil propose une configuration automatisée. gws auth setup gère la création du projet, l’activation des API, la configuration de l’écran de consentement OAuth et la création des credentials client automatiquement si vous avez déjà gcloud configuré :

npm install -g @googleworkspace/cli
gws auth setup

Cela contourne tous les pièges ci-dessous. Ne passez au flux manuel que lorsque vous rencontrez des restrictions d’organisation qui empêchent la création automatisée de projets, ou quand vous avez besoin d’un contrôle explicite sur la configuration.

Piège 1 : Mauvais type d’application OAuth

Lors de la création d’un ID client OAuth dans la console Google Cloud (APIs & Services > Identifiants > Créer des identifiants > ID client OAuth), vous devez choisir Application de bureau comme type d’application.

La console propose par défaut Application Web. Rien ne vous avertit que vous avez fait le mauvais choix. Le flux d’authentification semblera réussir — vous obtiendrez un fichier JSON, vous configurerez les credentials — puis échouera lors de la connexion avec une erreur qui n’indique pas le type d’application comme cause.

Si vous avez créé un client Application Web, supprimez-le et créez-en un nouveau. Il n’est pas possible de changer le type d’application après la création.

# Après avoir sauvegardé les credentials correctes Application de bureau dans ~/.config/gws/client_secret.json
gws auth login

Piège 2 : Utilisateur de test manquant

Après avoir configuré l’écran de consentement OAuth (APIs & Services > Écran de consentement OAuth), vous devez ajouter votre propre adresse e-mail Google en tant qu’utilisateur de test. Cette étape est enfouie sous un onglet séparé.

Sans cela, vous obtiendrez une erreur générique « Access blocked: [Nom de l’app] n’a pas terminé le processus de vérification de Google » lors de la tentative de connexion. L’erreur ne donne aucune indication qu’un utilisateur de test manquant en est la cause — cela ressemble à un problème de vérification d’application, pas à un problème de configuration.

Le correctif : retournez à l’écran de consentement OAuth, cliquez sur la section « Utilisateurs de test », ajoutez votre adresse e-mail et réessayez la connexion.

Pour un usage personnel ou de développement, vous n’avez pas besoin de terminer le processus de vérification de Google. L’avertissement d’application non vérifiée que vous verrez (« Google n’a pas vérifié cette application ») est attendu et sans danger. Cliquez sur Avancé, puis sur « Accéder à [nom de l’app] (non sécurisé) » pour continuer.

Piège 3 : La limite de portées

Les applications OAuth non vérifiées en mode test sont limitées à environ 25 portées OAuth. Cette limite est appliquée silencieusement — vous n’obtenez pas d’erreur claire, vous obtenez une autorisation de portée tronquée ou un échec difficile à diagnostiquer.

Le préréglage « tous les services » recommandé par le CLI gws inclut 85+ portées et échouera silencieusement ou génèrera une erreur si vous essayez de tous les autoriser à la fois.

Le correctif : autorisez uniquement les services dont vous avez réellement besoin. Si vous utilisez Drive, Gmail et Calendar, cela représente une fraction des portées disponibles et restera bien en dessous de la limite :

# En mode serveur MCP, limitez à des services spécifiques
gws mcp -s drive,gmail,calendar

# Lors de la configuration auth, vous pouvez limiter les APIs de service activées

Vous pouvez toujours ajouter d’autres services plus tard avec un autre appel gws auth login. La limite de portées est une contrainte du mode test ; les applications publiées (qui ont terminé le processus de vérification de Google) n’ont pas cette restriction.

La confusion lors de la connexion OAuth

Quand gws auth login demande interactivement des credentials (si vous n’avez pas sauvegardé le fichier JSON), il demande votre « OAuth ID ». Ce qu’il veut réellement, c’est l’ID client — la longue chaîne se terminant par .apps.googleusercontent.com. À l’invite suivante, il demande le « secret client ».

Les deux valeurs proviennent du fichier JSON que vous avez téléchargé lors de la création du client OAuth. Les étiquettes des invites ne correspondent pas aux noms dans le JSON, ce qui crée une confusion sur quelle valeur va où.

Si vous avez sauvegardé le fichier JSON dans ~/.config/gws/client_secret.json, le CLI le lit automatiquement et ne demandera pas interactivement. Vous pouvez également définir des variables d’environnement :

export GWS_CLIENT_ID="votre-client-id.apps.googleusercontent.com"
export GWS_CLIENT_SECRET="votre-secret-client"

Configuration multi-comptes et headless

Pour plusieurs comptes Google, gws gère l’isolation des credentials nativement :

# Se connecter avec des comptes spécifiques
gws auth login --account work@corp.com
gws auth login --account personal@gmail.com

# Lister les comptes enregistrés
gws auth list

# Définir un compte par défaut, surcharger par commande, ou utiliser une variable d'environnement
gws auth default work@corp.com
gws --account personal@gmail.com drive files list
export GOOGLE_WORKSPACE_CLI_ACCOUNT=personal@gmail.com

Chaque compte obtient son propre fichier de credentials chiffré dans ~/.config/gws/credentials.<base64-email>.enc, avec la clé de chiffrement stockée dans votre trousseau du système d’exploitation.

Pour les environnements headless (CI, serveurs, pipelines sans accès navigateur) :

# Sur une machine AVEC navigateur : exporter les credentials après la connexion interactive
gws auth export --unmasked > credentials.json

# Sur la machine headless : pointer vers le fichier exporté
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/chemin/vers/credentials.json
gws drive files list   # fonctionne sans interaction navigateur

Pour les flux serveur-à-serveur utilisant un compte de service GCP avec Domain-Wide Delegation :

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/chemin/vers/service-account.json
export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=admin@example.com
gws drive files list

Priorité d’authentification

Quand plusieurs sources de credentials existent, le CLI résout dans cet ordre (la première correspondance l’emporte) :

Token d’accès (GOOGLE_WORKSPACE_CLI_TOKEN)
Fichier de credentials (GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE)
Credentials chiffrées par compte (depuis gws auth login --account)
Credentials en clair (~/.config/gws/credentials.json)

Vous pouvez également injecter un token d’accès pré-obtenu, ce qui est utile quand gcloud génère déjà des tokens :

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

Erreurs « API non activée »

Lorsque vous essayez d’utiliser un service Workspace pour la première fois, vous pouvez obtenir une erreur 403 avec la raison accessNotConfigured. Le correctif : cliquez sur l’URL que le CLI affiche avec l’erreur, activez l’API dans la console Cloud, attendez environ 10 secondes et réessayez. Vous pouvez aussi relancer gws auth setup — il active automatiquement toutes les API requises.

Le flux OAuth manuel n’active pas les API automatiquement ; il crée uniquement les credentials OAuth. Chaque service (Gmail, Drive, Calendar, etc.) nécessite que son API correspondante soit activée séparément dans la console Cloud avant que le CLI puisse l’utiliser.