# Google Workspace: Postfächer verbinden

Damit der Assistent Post in Google Workspace lesen und dort Entwürfe anlegen
kann, braucht er Zugriff über die Gmail API. Dafür gibt es zwei Wege, und
beide beruhen auf dem, was die Organisation in **ihrer eigenen Google Cloud**
anlegt. draften hat keine gemeinsame App, der Sie nur zustimmen müssten. Das
gilt für unseren Dienst ebenso wie für eine Installation auf dem eigenen
Server.

Wir gehen von **Google Workspace** aus. Private Konten `@gmail.com`
unterstützen wir nicht: Mit ihnen kann man sich nicht bei draften anmelden, und
ihre Verbindung würde voraussetzen, dass Google die App überprüft.

## Welchen Weg wählen

| | Für die ganze Organisation | Mit dem Konto des Postfachs |
|---|---|---|
| In draften | Registrierung (Dienstkonto) unter Organisation → **Integrationen** | Schaltfläche **Gmail verbinden** beim Postfach |
| Bei Google | Dienstkonto mit Schlüssel und Domain-wide Delegation | OAuth-Client und Consent Screen vom Typ Internal |
| Wer es anlegt | ein Administrator der Google Cloud und ein Super Admin in Google Admin | ein Administrator der Google Cloud |
| Wer sich anmelden muss | niemand | der Inhaber jedes Postfachs, einmal |
| Welche Postfächer erreicht werden | alle Postfächer der Domain | nur das Postfach, dessen Konto sich angemeldet hat |
| Anmeldung bei draften mit dem Google-Konto | nein, das ist eine eigene Sache | derselbe OAuth-Client dient auch der Anmeldung |

Für eine Organisation mit mehreren Postfächern ist der **Weg für die ganze
Organisation** einfacher. **Mit dem Konto des Postfachs** eignet sich, wenn Sie
nicht einem einzigen Schlüssel Zugriff auf alle Postfächer der Domain geben
möchten oder wenn Sie ohnehin die Anmeldung mit dem Google-Konto einführen.

Beide Wege können Sie gleichzeitig nutzen; jedes Postfach verwendet einen
davon. draften verlangt nur den Berechtigungsbereich `gmail.modify` – Lesen und
Anlegen von Entwürfen, es sendet nichts.

## Weg A: für die ganze Organisation

### In der Google Cloud

Sie arbeiten in https://console.cloud.google.com, in der Organisation Ihrer
Workspace-Domain.

1. Wählen Sie ein Projekt, oder legen Sie ein neues an (etwa `draften`).
2. **APIs & Services** → **Library** → **Gmail API** → **Enable**.
3. **IAM & Admin** → **Service accounts** → **Create service account**. Name
   etwa `draften-post`. Rollen im Projekt braucht es keine – Zugriff auf die
   Post erhält es erst durch die Delegation in Google Admin. Klicken Sie auf
   **Done**.
4. Öffnen Sie das Dienstkonto und notieren Sie seine **Unique ID** – die
   numerische Client-ID.
5. Registerkarte **Keys** → **Add key** → **Create new key** → **JSON** →
   **Create**. Eine Datei mit dem Schlüssel wird heruntergeladen.

!> Lehnt Google das Anlegen des Schlüssels ab, hat Ihre Organisation die
Richtlinie `iam.disableServiceAccountKeyCreation` eingeschaltet (neue
Organisationen haben sie standardmäßig). Für dieses Projekt schaltet sie ein
Administrator der Organisation unter **IAM & Admin** → **Organization
policies** aus.

### In Google Admin

Sie brauchen einen Super Admin. Öffnen Sie in https://admin.google.com
**Security** → **Access and data control** → **API controls** → **Manage
Domain Wide Delegation** → **Add new**. **Client ID**: die numerische ID aus
Schritt 4. **OAuth scopes**: `https://www.googleapis.com/auth/gmail.modify`.
Klicken Sie auf **Authorize**. Die Delegation wirkt meist innerhalb weniger
Minuten, in Ausnahmefällen erst nach einigen Stunden.

### In draften

1. Öffnen Sie Organisation → **Integrationen**, Karte **Zugriff auf die Post
   für die ganze Organisation**. Registrierungen verwalten der Inhaber und die
   Manager der Organisation.
2. **System**: **Google Workspace**. Füllen Sie **Name** aus, wählen Sie bei
   **Schlüssel des Dienstkontos (JSON)** die heruntergeladene Datei und klicken
   Sie auf **Registrierung hinzufügen**. Der Schlüssel wird verschlüsselt
   gespeichert; in der Karte sind danach nur die E-Mail-Adresse des
   Dienstkontos und seine Client-ID zu sehen.
3. Wählen Sie auf der Seite jedes Postfachs in der Karte **Zugriff auf die
   Post** bei **Verwenden** diese Registrierung, klicken Sie auf **Übernehmen**
   und dann auf **Verbindung testen**. Den Ablauf mit Bildschirmfotos zeigt die
   Anleitung [Ein Postfach hinzufügen und
   verbinden](/de/admin/adding-a-mailbox).

**Löschen Sie danach die heruntergeladene Schlüsseldatei.** Wer sie hat,
kommt in jedes Postfach der Domain. Einen neuen Schlüssel desselben
Dienstkontos laden Sie bei der Registrierung über **neuer Schlüssel (JSON)**
hoch; den Schlüssel eines anderen Dienstkontos fügen Sie als neue
Registrierung hinzu. Löschen Sie den alten Schlüssel in der Google Cloud.

Ist **Postfach automatisch** eingeschaltet ([Wie sich Mitglieder
anmelden](/de/admin/member-sign-in)), wird ein neues Postfach von selbst an die
Registrierung gebunden, wenn für Google Workspace genau eine aktiv ist.

## Weg B: mit dem Konto des Postfachs (Gmail verbinden)

Hier meldet sich der Inhaber des Postfachs mit seinem Google-Konto an und
erlaubt den Zugriff nur auf seine eigene Post. Derselbe OAuth-Client dient auch
der **Anmeldung bei draften mit dem Google-Konto**.

### In der Google Cloud

1. Öffnen Sie zuerst in draften Organisation → **Wie sich Mitglieder
   anmelden**, Karte **Kontoanmeldung und Postfachverbindungen**. Sie zeigt
   zwei **Redirect URIs** genau für Ihre Adresse von draften – sie enden auf
   `/auth/google/callback` und `/mailboxes/connect/google/callback`. Kopieren
   Sie sie von dort; sie müssen Zeichen für Zeichen stimmen.
2. Öffnen Sie im Projekt mit eingeschalteter **Gmail API** (Schritt 2 von
   Weg A) **APIs & Services** → **OAuth consent screen**. **User type**:
   **Internal** – anmelden kann sich dann nur ein Konto Ihrer Domain, und
   Google muss die App nicht überprüfen. Tragen Sie den Namen der App (etwa
   `draften`) und eine Kontakt-E-Mail-Adresse ein.
3. Fügen Sie im Abschnitt mit den Berechtigungsbereichen (**Scopes** / **Data
   access**) `openid`, `email`, `profile` und
   `https://www.googleapis.com/auth/gmail.modify` hinzu.
4. **APIs & Services** → **Credentials** → **Create credentials** → **OAuth
   client ID**. **Application type**: **Web application**. Tragen Sie unter
   **Authorized redirect URIs** beide Adressen aus der Karte ein und klicken
   Sie auf **Create**.
5. Kopieren Sie **Client ID** und **Client secret**.

### In draften

1. Der **Inhaber der Organisation** trägt in der Karte **Kontoanmeldung und
   Postfachverbindungen** unter **Google-OAuth-Client** die **Client ID** und
   das **Client secret** ein und klickt auf **Speichern**.
2. Der **Inhaber des Postfachs** öffnet die Seite des Postfachs und klickt in
   der Karte **Zugriff auf die Post** auf **Gmail verbinden**. Er meldet sich
   **mit dem Konto dieses Postfachs** an – ein anderes Konto lehnt draften ab –
   und erlaubt den Zugriff. Die Schaltfläche sieht nur der Inhaber des
   Postfachs, und nur wenn die Organisation den OAuth-Client hat.
3. Dann **Verbindung testen**.

Die **Anmeldung mit dem Google-Konto** schalten Sie auf derselben Seite ein:
Tragen Sie unter **E-Mail-Domains der Organisation** Ihre Workspace-Domain
ein – die primäre, keine Alias-Domain (die sendet Google bei der Anmeldung
nicht). Sobald die Organisation den OAuth-Client und die Domain hat, melden
sich die Mitglieder mit dem Google-Konto an, und ihre Passwörter gelten nicht
mehr – siehe [Wie sich Mitglieder anmelden](/de/admin/member-sign-in).

### Wenn das Postfach getrennt wird

- **Das Konto wurde gelöscht oder gesperrt, oder der Zugriff wurde
  widerrufen** – Google stellt keine Tokens mehr aus, und draften trennt das
  Postfach. Verbinden Sie es erneut (**Gmail neu verbinden**) oder über Weg A.
- **„Der Anbieter hat kein Refresh-Token ausgestellt“** – der Inhaber des
  Postfachs entfernt die App in den Einstellungen seines Google-Kontos
  (**Sicherheit** → **Drittanbieter-Apps**) und verbindet das Postfach erneut.
- **„Es hat sich ein anderes Konto angemeldet als die Adresse des Postfachs“** –
  wählen Sie beim Verbinden das Konto genau dieses Postfachs.

## Fehler beim Verbindungstest

Der Test prüft drei Schritte: **Zugriff**, **Token und Berechtigung** und
**Lesen des Posteingangs**.

| In der Meldung | Was es bedeutet | Was zu tun ist |
|---|---|---|
| die Delegation für den Berechtigungsbereich ist nicht erlaubt (`unauthorized_client`) | in Google Admin fehlt die Domain-wide Delegation, oder sie hat eine andere Client-ID oder einen anderen Berechtigungsbereich | die Delegation in Google Admin prüfen: die numerische ID und den genauen Berechtigungsbereich `gmail.modify` |
| `invalid_grant` beim Dienstkonto | ein solches Postfach gibt es in der Workspace-Domain nicht | die Adresse des Postfachs prüfen |
| „Gmail API has not been used…“ | im Projekt ist die Gmail API nicht eingeschaltet | die Gmail API einschalten (Schritt 2) |
| Token ohne `gmail.modify` | der Delegation oder dem Consent Screen fehlt der Berechtigungsbereich `gmail.modify` | den Berechtigungsbereich ergänzen |
| `invalid_grant`, `deleted_client` bei einem verbundenen Konto | die Verbindung wurde widerrufen oder der OAuth-Client gelöscht | **Gmail neu verbinden** |

Weitere Fehler beschreibt [Fehlerbehebung](/de/admin/troubleshooting).