Summary
[!note] 📚 Série Pilotflow : Construire un addon Gmail
- Le mensonge à 50 000 $ qui a failli tuer mon addon Gmail — 8 juin
- Les niveaux de scopes OAuth Gmail décodés ← vous êtes ici
- Analyse du code existant avant développement — 22 juin
- Documents légaux pour les addons Gmail — 29 juin
Dans le billet précédent, j’ai expliqué comment le mythe de la certification CASA a failli tuer Pilotflow avant que j’écrive une seule ligne de code. En résumé : le chiffre de 50 000 $ qui circule dans les forums de développeurs décrit l’option d’évaluation la plus coûteuse, pas la procédure standard. Et surtout, le bon design de scope permet souvent de contourner entièrement la restriction.
Mais comment savoir quel scope utiliser ? Cela nécessite de comprendre la classification en trois niveaux de Google — un système que la plupart des documentations d’addon survolent, laissant les développeurs le reconstituer à partir des messages d’erreur lors de la vérification OAuth.
Ce billet est l’explication claire que j’aurais aimé trouver en première page.
Trois niveaux, trois conversations différentes
Lorsque votre addon Google Workspace demande des scopes OAuth, Google les classe dans l’un des trois niveaux. Le niveau ne détermine pas seulement les données auxquelles votre application peut accéder — il détermine la conversation que Google a avec votre utilisateur lors de l’autorisation.
Niveau 1 : Scopes publics
→ Écran de consentement OAuth standard
→ Aucune vérification supplémentaire requise
→ Icône bouclier bleu dans la boîte de dialogue de consentement
Niveau 2 : Scopes sensibles
→ Vérification OAuth requise (gratuit, 4–6 semaines)
→ Avertissement jaune/orange dans la boîte de dialogue de consentement
→ L'utilisateur doit explicitement accepter l'accès étendu
Niveau 3 : Scopes restreints
→ Certification CASA Niveau 2 requise (540–75 000 $+)
→ Avertissement rouge dans la boîte de dialogue de consentement
→ Les administrateurs d'entreprise peuvent bloquer l'installation
La différence d’écran de consentement importe plus que la plupart des développeurs ne le pensent. Un utilisateur qui voit un avertissement rouge lors de l’installation a une première impression fondamentalement différente de votre addon par rapport à celui qui voit un bouclier bleu. Avant de choisir un scope, la bonne question est : à quoi ressemble ce scope pour mon utilisateur ?
À retenir : Le niveau de scope affecte les exigences de sécurité ET les signaux de confiance utilisateur lors de l’installation. La couleur de l’écran de consentement est la première impression de votre posture sécurité.
Le tableau des scopes Gmail
Voici la classification pour les scopes Gmail que la plupart des développeurs d’addons rencontrent :
| Scope | Niveau | Accès | Certification |
|---|---|---|---|
gmail.addons.current.message.readonly |
Sensible | Message actuellement ouvert uniquement | Vérification OAuth (gratuit) |
gmail.addons.current.message.action |
Sensible | Action sur le message courant | Vérification OAuth (gratuit) |
calendar.addons.current.event.read |
Public | Événement calendrier courant | Aucune |
gmail.readonly |
Restreint | Boîte mail entière (lecture) | CASA + OAuth |
gmail.modify |
Restreint | Boîte mail entière (lecture + modification) | CASA + OAuth |
gmail.send |
Restreint | Envoyer en tant qu’utilisateur | CASA + OAuth |
Le schéma est clair : les scopes qui opèrent sur le contexte courant (ce que l’utilisateur consulte activement) sont sensibles ou publics. Les scopes qui opèrent sur toute la boîte mail en arrière-plan sont restreints.
Cette distinction reflète une vraie différence de risque. Un addon qui peut lire l’email actuellement ouvert est sous la supervision de l’utilisateur — l’utilisateur a choisi d’ouvrir cet email, voit l’addon fonctionner dans la barre latérale, et peut fermer les deux. Un addon avec un accès complet en lecture à la boîte mail peut exfiltrer l’historique des emails silencieusement, en arrière-plan, sans aucune action de l’utilisateur.
La décision de scope de Pilotflow
Pour Pilotflow, le flux de travail principal de l’utilisateur est : ouvrir un fil d’emails → voir les insights dans la barre latérale → décider quoi faire. Ce flux correspond exactement à gmail.addons.current.message.readonly.
Ce qu’il ne correspond pas, c’est le traitement par lot en arrière-plan — lire les six derniers mois d’emails pendant que l’utilisateur fait autre chose. Ce n’est pas ce que Pilotflow doit faire pour l’utilisateur ; c’est ce que j’imaginais avoir initialement, parce qu’un accès plus large semblait synonyme de plus de capacités.
Séparer « l’accès que j’imaginais avoir » de « l’accès que le flux de travail utilisateur nécessite réellement » est l’un des exercices de conception de scope les plus précieux. La question à se poser est : que fait l’utilisateur au moment où mon addon s’exécute ? Si l’utilisateur lit un email, le scope du message courant est suffisant. Si l’utilisateur doit déclencher une action en arrière-plan, vous pouvez demander cette permission spécifique au moment du déclenchement — pas à l’avance.
[!note] Le piège du « au cas où » Demander des scopes larges « au cas où » vous en auriez besoin plus tard est l’erreur la plus courante en conception de scope OAuth. Les permissions inutilisées sont une responsabilité en termes de confiance, pas un filet de sécurité. Demandez ce dont vous avez besoin maintenant ; étendez plus tard si un flux utilisateur spécifique le nécessite vraiment.
La stratégie du statut de test
Un défi pratique pendant le développement : les API à scope restreint peuvent se comporter différemment en test qu’en production, parce que votre application n’est pas encore certifiée. Google fournit un statut « Test » qui vous permet de tester avec des scopes restreints en utilisant un ensemble limité de comptes de test approuvés (jusqu’à 100 utilisateurs).
Pour Pilotflow, j’ai utilisé cette approche :
- Pendant le développement : Utiliser l’addon avec un compte Gmail de test ajouté à la liste approuvée
- Avant le lancement MVP : Compléter la vérification OAuth pour les scopes sensibles utilisés
- Après le lancement : Surveiller si des fonctionnalités à scope restreint sont demandées par les vrais utilisateurs avant d’investir dans une évaluation CASA
La stratégie du statut de test signifie que vous pouvez construire et valider le produit avec de vraies données email avant de vous engager dans un parcours de certification. Si les utilisateurs ne demandent jamais la fonctionnalité à scope restreint, vous ne payez jamais la certification.
Ce qui se passe si vous vous trompez
J’ai observé deux modes d’échec :
Demander des scopes restreints avant la certification. Votre application échouera lors de la revue de soumission au Workspace Marketplace. L’équipe de revue de Google vérifie les classifications de scope par rapport au statut de certification. Si vous demandez gmail.readonly sans certification CASA, la soumission est rejetée — pas signalée, rejetée.
Demander des scopes sensibles sans vérification OAuth. Votre application entre dans un flux de consentement rempli d’avertissements. Les utilisateurs voient « Cette application n’a pas été vérifiée par Google » avec une option pour revenir en arrière. Certains utilisateurs continuent. Beaucoup ne le font pas. Le taux d’abandon sur les écrans de consentement non vérifiés est significatif — j’ai vu des estimations de 30 à 50 % d’abandon. Pour un outil B2B ciblant des utilisateurs en entreprise, le statut non vérifié peut aussi déclencher des blocages au niveau administrateur dans toute l’organisation.
[!info] Le délai de vérification à planifier La vérification OAuth prend 4 à 6 semaines. L’évaluation CASA prend 4 à 12 semaines selon le TAP et le type d’évaluation. Intégrez ce délai dans votre planification de lancement — pas comme une réflexion après coup une fois le code terminé.
Appliquer ceci à votre propre addon
Lorsque vous concevez les scopes pour un addon Gmail Workspace, parcourez ces questions dans l’ordre :
- Que fait l’utilisateur lorsque votre addon s’exécute ? Si c’est lire un email spécifique, commencez avec les scopes du message courant.
- Votre fonctionnalité nécessite-t-elle un accès en arrière-plan ? Si oui, cette exigence est-elle technique ou architecturale ? Le design peut-il être ajusté ?
- Pour chaque scope que vous envisagez : Cherchez-le dans la documentation OAuth 2.0 Scopes for Google APIs de Google. Trouvez sa classification.
- Calculez le coût et le délai de certification pour tout scope restreint. Incluez cela dans le coût de votre MVP.
- Demandez-vous : le même résultat utilisateur peut-il être atteint avec un scope moins invasif ? Souvent la réponse est oui — et le scope moins invasif offre aussi une meilleure expérience utilisateur sur l’écran de consentement.
Le prochain billet couvre l’analyse du code existant avant le développement — spécifiquement, ce que j’ai trouvé en analysant la base de code existante avant d’écrire une ligne de nouveau code, y compris un bug de concurrence qui aurait causé une perte de données silencieuse.
