Configurer Google Workspace

Vue d'ensemble

RingSync lit votre annuaire Google Workspace via l'Admin SDK Directory API, en lecture seule. Deux méthodes d'enrôlement sont prises en charge :

• Méthode B — Service Account dédié + Délégation au niveau du domaine (recommandée) — vous créez et possédez un service account dans votre propre projet GCP, l'autorisez, et fournissez sa clé JSON. Fonctionne immédiatement, sans vérification Google requise. La clé reste sous votre contrôle et révocable à tout moment.
• Méthode A — OAuth admin (« Se connecter à Google ») — meilleure UX (un bouton) mais nécessite que Google vérifie l'écran de consentement (les scopes Directory sont sensibles) avant que des clients externes puissent l'utiliser.

Prérequis

• Un compte Super Admin dans le domaine Google Workspace (pour autoriser la délégation au niveau du domaine, ou pour consentir en OAuth).
• Pour la Méthode B : l'accès à un projet Google Cloud où vous pouvez créer un service account et une clé.
• Un compte back office RingSync.

Scopes Directory utilisés (lecture seule)

Les deux méthodes utilisent les mêmes scopes Directory en lecture seule :

https://www.googleapis.com/auth/admin.directory.user.readonly
https://www.googleapis.com/auth/admin.directory.group.readonly
https://www.googleapis.com/auth/admin.directory.group.member.readonly

Voir Permissions Google pour les détails, l'audit et la révocation.

Méthode B — Service Account dédié + Délégation au niveau du domaine

Le service account vit dans votre projet GCP. RingSync ne fait que recevoir la clé JSON (chiffrée dans son vault) et l'utiliser en lecture seule.

B.1 — Créer le service account (votre projet GCP)

1. Ouvrez la console Google Cloud → créez ou choisissez un projet → APIs & Services → Library → activez l'Admin SDK API.
2. Allez dans IAM & Admin → Service Accounts → Create service account (par exemple ringsync-sync). Aucun rôle IAM projet n'est nécessaire.
3. Ouvrez le service account → Keys → Add key → Create new key → JSON → téléchargez le fichier et gardez-le confidentiel.
4. Notez le Client ID numérique du service account (environ 21 chiffres) : le champ "client_id" du JSON, ou Unique ID dans les détails du service account.

B.2 — Autoriser la délégation (console Google Admin)

1. Ouvrez admin.google.com → Sécurité → Contrôle des API → Délégation au niveau du domaine → Add new.

2. Client ID = le Client ID numérique de l'étape B.1.4.

3. OAuth scopes (une ligne, séparés par des virgules) :

   https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.group.member.readonly

4. Cliquez Authorize.

B.3 — Saisir la configuration dans RingSync

Dans le back office RingSync, créez un nouvel espace → Google Workspace → Service Account (DWD) → renseignez :

• Domaine — par exemple acme.com.
• Email admin à impersonate — un admin Workspace existant pouvant lire l'annuaire (le super-admin convient). Le service account agit « en tant que » cette personne.
• Clé du Service Account (JSON) — collez le contenu du fichier téléchargé en B.1.3. Elle est chiffrée dans le vault et jamais réexposée.

Cliquez Tester la connexion pour valider l'accès, puis Créer l'espace pour provisionner et peupler les autorisations d'accès.

B.4 — Notes de sécurité pour votre sysadmin

• Vous gardez la maîtrise : le service account est dans votre projet GCP ; vous pouvez le révoquer à tout moment (supprimer la clé dans GCP, ou retirer l'entrée de délégation au niveau du domaine). L'accès est journalisé dans les Audit logs Google.
• Lecture seule : le service account ne peut rien faire hors des trois scopes Directory en lecture — pas d'email, pas de Drive, pas d'écriture. La délégation est scope par scope.
• Admin impersoné : un admin existant pouvant lire l'annuaire suffit (aucun compte à créer). En option, impersonez un rôle admin custom limité à Utilisateurs : Lire + Groupes : Lire pour réduire le rayon de souffle (un rôle custom ne consomme aucune licence).
• Côté RingSync : la clé est stockée chiffrée dans le vault, jamais en clair. Prévoyez une rotation périodique (régénérez la clé de votre côté, recollez-la dans le back office).

Méthode A — OAuth admin (« Se connecter à Google »)

Cette méthode nécessite un projet Google Cloud avec un écran de consentement External portant les scopes Directory sensibles.

A.1 — Configurer l'écran de consentement OAuth (une fois)

1. Google Auth Platform → Audience → choisissez External (ou Internal pour ne tester que sur votre propre domaine).
2. Renseignez le nom de l'app, l'email de support, le domaine autorisé, le logo, et le lien vers la politique de confidentialité.
3. Sous Scopes, ajoutez les trois scopes Directory (marqués sensibles).
4. Tant que l'app est non vérifiée, seuls les test users ajoutés ici (ou le mode Internal sur votre propre domaine) peuvent consentir. Pour des clients externes, Submit for verification (justification des scopes, vidéo de démo). Les scopes Directory sont sensibles (vérification de l'écran de consentement) et non restreints : en principe, aucun audit de sécurité tiers n'est requis.

A.2 — Créer le client OAuth Web (une fois)

1. Google Auth Platform → Clients → Create client → Web application.

2. Sous Authorized redirect URIs, ajoutez exactement :

   https://<domaine-backoffice>/api/tenants/google/install-callback
   http://localhost:3002/api/tenants/google/install-callback

   Ces URI doivent correspondre à NEXT_PUBLIC_APP_URL.

3. Définissez les variables d'environnement du back office :

   GOOGLE_OAUTH_CLIENT_ID=xxxx.apps.googleusercontent.com
   GOOGLE_OAUTH_CLIENT_SECRET=xxxx

A.3 — Saisir la configuration dans RingSync

Dans le back office, créez un nouvel espace → Google Workspace → Se connecter à Google → l'admin se connecte et consent aux scopes Directory. RingSync stocke le refresh token (chiffré dans le vault) et provisionne l'espace. L'admin connecté devient l'identité utilisée pour lire l'annuaire.

Définir quels utilisateurs sont synchronisés

Google n'a pas d'équivalent au appRoleAssignedTo d'Entra. L'ensemble des sièges autorisés se règle dans les paramètres de l'espace (« Sièges autorisés » : tout le domaine, ou des groupes Google spécifiques).

Vérifier la connexion

1. Dans le back office RingSync, utilisez Tester la connexion (Méthode B) ou confirmez que la connexion OAuth a réussi (Méthode A).
2. Vérifiez que la liste des autorisations d'accès se peuple après la création de l'espace.
3. Depuis un téléphone, ouvrez l'app mobile, tapez Continuer avec Google, et vérifiez que l'annuaire apparaît et qu'une première sync réussit.

Dépannage

• Tous les appels annuaire échouent en 403 — l'Admin SDK API n'est pas activée sur le projet. Activez-la sous APIs & Services → Library.
• « unauthorized_client » à la sync — l'entrée de délégation au niveau du domaine est manquante ou ses scopes ne correspondent pas exactement. Revérifiez le Client ID et la liste de scopes séparés par des virgules dans la console Admin.
• La vérification bloque les admins externes (Méthode A) — l'écran de consentement n'est pas vérifié. Ajoutez-les comme test users, ou utilisez la Méthode B.
• {{À COMPLÉTER : message d'erreur exact affiché dans le back office quand l'admin impersoné n'a pas les droits de lecture d'annuaire}}