# Google Workspace : connecter les boîtes mail

Pour que l’assistant puisse lire les e-mails dans Google Workspace et y créer
des brouillons, il a besoin d’un accès via la Gmail API. Deux voies sont
possibles, et toutes deux reposent sur ce que l’organisation crée dans **son
propre Google Cloud**. draften n’a pas d’application commune à laquelle il vous
suffirait de donner votre consentement. Cela vaut pour notre service comme pour
une installation sur votre propre serveur.

Nous partons de **Google Workspace**. Les comptes personnels `@gmail.com` ne
sont pas pris en charge : ils ne permettent pas de se connecter à draften, et
leur connexion exigerait que Google valide l’application.

## Quelle voie choisir

| | Pour toute l’organisation | Avec le compte de la boîte mail |
|---|---|---|
| Dans draften | inscription (compte de service) dans Organisation → **Intégrations** | bouton **Connecter Gmail** sur la boîte mail |
| Chez Google | compte de service avec une clé et domain-wide delegation | client OAuth et écran de consentement de type Internal |
| Qui le crée | un administrateur Google Cloud et un super-administrateur Google Admin | un administrateur Google Cloud |
| Qui doit se connecter | personne | le propriétaire de chaque boîte mail, une fois |
| Boîtes mail atteintes | toutes les boîtes mail du domaine | uniquement la boîte mail dont le compte s’est connecté |
| Connexion à draften avec un compte Google | non, c’est une chose distincte | le même client OAuth sert aussi à la connexion |

Pour une organisation qui a plusieurs boîtes mail, la **voie pour toute
l’organisation** est la plus simple. La voie **avec le compte de la boîte
mail** convient lorsque vous ne voulez pas donner à une seule clé l’accès à
toutes les boîtes mail du domaine, ou lorsque vous mettez de toute façon en
place la connexion avec un compte Google.

Vous pouvez utiliser les deux voies en même temps ; chaque boîte mail utilise
l’une d’elles. draften ne demande que le champ d’application `gmail.modify` –
lire et créer des brouillons ; il n’envoie rien.

## Voie A : pour toute l’organisation

### Dans Google Cloud

Vous travaillez dans https://console.cloud.google.com, dans l’organisation de
votre domaine Workspace.

1. Choisissez un projet ou créez-en un nouveau (par exemple `draften`).
2. **APIs & Services** → **Library** → **Gmail API** → **Enable**.
3. **IAM & Admin** → **Service accounts** → **Create service account**. Un nom,
   par exemple `draften-emails`. Il n’a besoin d’aucun rôle dans le projet –
   c’est la délégation dans Google Admin qui lui donne accès aux e-mails.
   Cliquez sur **Done**.
4. Ouvrez le compte de service et notez son **Unique ID** – le Client ID
   numérique.
5. Onglet **Keys** → **Add key** → **Create new key** → **JSON** →
   **Create**. Un fichier contenant la clé est téléchargé.

!> Si Google refuse de créer la clé, votre organisation a activé la règle
`iam.disableServiceAccountKeyCreation` (les nouvelles organisations l’ont par
défaut). Un administrateur de l’organisation la désactive pour ce projet dans
**IAM & Admin** → **Organization policies**.

### Dans Google Admin

Il vous faut un super-administrateur. Dans https://admin.google.com, ouvrez
**Security** → **Access and data control** → **API controls** → **Manage
Domain Wide Delegation** → **Add new**. **Client ID** : l’ID numérique de
l’étape 4. **OAuth scopes** : `https://www.googleapis.com/auth/gmail.modify`.
Cliquez sur **Authorize**. La délégation prend effet en général en quelques
minutes, exceptionnellement au bout de plusieurs heures.

### Dans draften

1. Ouvrez Organisation → **Intégrations**, carte **Accès aux e-mails pour toute
   l’organisation**. Les inscriptions sont gérées par le propriétaire ou les
   gestionnaires de l’organisation.
2. **Système** : **Google Workspace**. Remplissez **Nom**, choisissez le fichier
   téléchargé sous **Clé du compte de service (JSON)** et cliquez sur **Ajouter
   une inscription**. La clé est stockée chiffrée ; la carte n’affiche ensuite
   que l’e-mail du compte de service et son Client ID.
3. Sur la page de chaque boîte mail, dans la carte **Accès aux e-mails**,
   choisissez cette inscription sous **Utiliser**, cliquez sur **Appliquer** puis
   sur **Tester la connexion**. Le guide [Ajouter et connecter une boîte
   mail](/fr/admin/adding-a-mailbox) montre la marche à suivre avec des
   captures d’écran.

**Supprimez ensuite le fichier de clé téléchargé.** Quiconque le possède accède
à toutes les boîtes mail du domaine. Vous importez une nouvelle clé du même
compte de service au niveau de l’inscription avec **nouvelle clé (JSON)** ;
ajoutez la clé d’un autre compte de service comme nouvelle inscription.
Supprimez l’ancienne clé dans Google Cloud.

Avec la **Boîte mail automatique** activée ([Comment les membres se
connectent](/fr/admin/member-sign-in)), une nouvelle boîte mail est liée
d’elle-même à l’inscription lorsqu’il y en a exactement une active pour Google
Workspace.

## Voie B : avec le compte de la boîte mail (Connecter Gmail)

Ici, le propriétaire de la boîte mail se connecte avec son compte Google et
n’autorise l’accès qu’à ses propres e-mails. Le même client OAuth sert aussi à
la **connexion à draften avec un compte Google**.

### Dans Google Cloud

1. Dans draften, ouvrez d’abord Organisation → **Comment les membres se
   connectent**, carte **Connexion des comptes et des boîtes mail**. Elle
   affiche deux **Redirect URIs** établies exactement pour votre adresse
   draften – elles se terminent par `/auth/google/callback`
   et `/mailboxes/connect/google/callback`. Copiez-les depuis cette carte ;
   elles doivent correspondre caractère pour caractère.
2. Dans le projet où la **Gmail API** est activée (étape 2 de la voie A),
   ouvrez **APIs & Services** → **OAuth consent screen**. **User type** :
   **Internal** – seul un compte de votre domaine peut alors se connecter, et
   Google n’a pas besoin de valider l’application. Saisissez le nom de
   l’application (par exemple `draften`) et une adresse e-mail de contact.
3. Dans la partie des champs d’application (**Scopes** / **Data access**),
   ajoutez `openid`, `email`, `profile`
   et `https://www.googleapis.com/auth/gmail.modify`.
4. **APIs & Services** → **Credentials** → **Create credentials** → **OAuth
   client ID**. **Application type** : **Web application**. Dans **Authorized
   redirect URIs**, collez les deux adresses de la carte et cliquez sur
   **Create**.
5. Copiez le **Client ID** et le **Client secret**.

### Dans draften

1. Le **propriétaire de l’organisation** renseigne, dans la carte **Connexion
   des comptes et des boîtes mail**, sous **Client OAuth Google**, les valeurs
   **Client ID** et **Client secret**, puis clique sur **Enregistrer**.
2. Le **propriétaire de la boîte mail** ouvre la page de la boîte mail et
   clique sur **Connecter Gmail** dans la carte **Accès aux e-mails**. Il se
   connecte **avec le compte de cette boîte mail** – draften refuse tout autre
   compte – et autorise l’accès. Le bouton n’est visible que pour le
   propriétaire de la boîte mail, et seulement si l’organisation a le client
   OAuth.
3. Puis **Tester la connexion**.

Vous activez la **connexion avec un compte Google** sur la même page : dans
**Domaines e-mail de l’organisation**, saisissez votre domaine Workspace – le
domaine principal, pas un domaine d’alias (Google ne l’envoie pas lors de la
connexion). Dès que l’organisation a le client OAuth et le domaine, les membres
se connectent avec leur compte Google et leurs mots de passe cessent de
fonctionner – voir [Comment les membres se connectent](/fr/admin/member-sign-in).

### Quand une boîte mail se déconnecte

- **Le compte a été supprimé ou bloqué, ou l’accès révoqué** – Google cesse
  d’émettre des jetons et draften déconnecte la boîte mail. Reconnectez-la
  (**Reconnecter Gmail**) ou passez par la voie A.
- **« Le fournisseur n’a émis aucun jeton d’actualisation »** – le propriétaire
  de la boîte mail supprime l’application dans les paramètres de son compte
  Google (**Sécurité** → **Applications et services tiers**) et reconnecte la
  boîte mail.
- **« Un autre compte que celui de l’adresse de la boîte mail s’est
  connecté »** – lors de la connexion, choisissez le compte de cette boîte mail
  précisément.

## Erreurs du test de connexion

Le test vérifie trois étapes : **Accès**, **Jeton et autorisation** et
**Lecture de la boîte de réception**.

| Dans le message | Ce que cela signifie | Que faire |
|---|---|---|
| délégation non autorisée pour le champ d’application (`unauthorized_client`) | la domain-wide delegation manque dans Google Admin, ou elle a un autre Client ID ou un autre champ d’application | vérifier la délégation dans Google Admin : l’ID numérique et le champ d’application exact `gmail.modify` |
| `invalid_grant` pour un compte de service | cette boîte mail n’existe pas dans le domaine Workspace | vérifier l’adresse de la boîte mail |
| « Gmail API has not been used… » | la Gmail API n’est pas activée dans le projet | activer la Gmail API (étape 2) |
| jeton sans `gmail.modify` | la délégation ou l’écran de consentement n’a pas le champ d’application `gmail.modify` | ajouter le champ d’application |
| `invalid_grant`, `deleted_client` pour un compte connecté | la connexion a été révoquée ou le client OAuth supprimé | **Reconnecter Gmail** |

Les autres erreurs sont décrites dans [Résolution des problèmes](/fr/admin/troubleshooting).