# Google Workspace: připojení schránek

Aby asistent mohl číst poštu v Google Workspace a zakládat v ní koncepty,
potřebuje přístup přes Gmail API. Jde to dvěma cestami a obě stojí na tom, co
si organizace založí ve **svém Google Cloudu**. draften nemá společnou
aplikaci, které byste jen udělili souhlas. Platí to pro naši službu i pro
instalaci na vlastním serveru.

Počítáme s **Google Workspace**. Osobní účty `@gmail.com` nepodporujeme:
přihlásit se jimi do draftenu nejde a jejich připojení by vyžadovalo, aby
aplikaci ověřil Google.

## Kterou cestu zvolit

| | Za celou organizaci | Účtem schránky |
|---|---|---|
| V draftenu | registrace (servisní účet) v Organizace → **Integrace** | tlačítko **Připojit Gmail** u schránky |
| V Googlu | servisní účet s klíčem a domain-wide delegation | OAuth klient a consent screen typu Internal |
| Kdo zakládá | správce Google Cloudu a superadministrátor Google Admin | správce Google Cloudu |
| Kdo se musí přihlásit | nikdo | vlastník každé schránky, jednou |
| Na které schránky dosáhne | na všechny schránky domény | jen na schránku, jejíž účet se přihlásil |
| Přihlašování do draftenu účtem Google | ne, to je samostatná věc | tentýž OAuth klient slouží i k přihlášení |

Pro organizaci s víc schránkami je jednodušší **cesta za celou organizaci**.
**Účtem schránky** se hodí, když nechcete dát jednomu klíči přístup ke všem
schránkám domény, nebo když stejně zavádíte přihlašování účtem Google.

Obě cesty můžete mít zároveň; každá schránka používá jednu z nich. draften
žádá jen rozsah `gmail.modify` — čtení a zakládání konceptů, nic neodesílá.

## Cesta A: za celou organizaci

### V Google Cloudu

Pracujete v https://console.cloud.google.com, v organizaci vaší domény
Workspace.

1. Vyberte projekt, nebo založte nový (třeba `draften`).
2. **APIs & Services** → **Library** → **Gmail API** → **Enable**.
3. **IAM & Admin** → **Service accounts** → **Create service account**. Název
   třeba `draften-posta`. Žádné role v projektu nepotřebuje — přístup
   k poště mu dá až delegace v Google Admin. Klikněte na **Done**.
4. Otevřete servisní účet a opište si jeho **Unique ID** — číselné Client ID.
5. Záložka **Keys** → **Add key** → **Create new key** → **JSON** →
   **Create**. Stáhne se soubor s klíčem.

!> Když Google vytvoření klíče odmítne, má vaše organizace zapnutou zásadu
`iam.disableServiceAccountKeyCreation` (nové organizace ji mají ve výchozím
stavu). Pro tento projekt ji vypne správce organizace v **IAM & Admin** →
**Organization policies**.

### V Google Admin

Potřebujete superadministrátora. V https://admin.google.com otevřete
**Security** → **Access and data control** → **API controls** → **Manage
Domain Wide Delegation** → **Add new**. **Client ID**: číselné ID z kroku 4.
**OAuth scopes**: `https://www.googleapis.com/auth/gmail.modify`. Klikněte na
**Authorize**. Delegace se obvykle projeví do pár minut, výjimečně až za
několik hodin.

### V draftenu

1. Otevřete Organizace → **Integrace**, kartu **Přístup k poště pro celou
   organizaci**. Registrace spravuje vlastník nebo správce organizace.
2. **Systém**: **Google Workspace**. Vyplňte **Název**, u **Klíč servisního
   účtu (JSON)** vyberte stažený soubor a klikněte na **Přidat registraci**.
   Klíč se uloží zašifrovaný; v kartě je pak vidět jen e-mail servisního
   účtu a jeho Client ID.
3. Na stránce každé schránky v kartě **Přístup k poště** vyberte u **Použít**
   tuto registraci, klikněte na **Nastavit** a pak na **Otestovat spojení**.
   Postup se snímky ukazuje návod [Přidání a připojení
   schránky](/cs/admin/adding-a-mailbox).

**Stažený soubor s klíčem pak smažte.** Kdo ho má, dostane se do každé
schránky domény. Nový klíč téhož servisního účtu nahrajete u registrace
volbou **nový klíč (JSON)**; klíč jiného servisního účtu přidejte jako novou
registraci. Starý klíč v Google Cloudu smažte.

Se zapnutou **automatickou schránkou** ([Přihlašování
členů](/cs/admin/member-sign-in)) se nová schránka na registraci naváže sama,
když je pro Google Workspace právě jedna aktivní.

## Cesta B: účtem schránky (Připojit Gmail)

Tady se vlastník schránky přihlásí svým účtem Google a povolí přístup jen ke
své poště. Tentýž OAuth klient slouží i k **přihlašování do draftenu účtem
Google**.

### V Google Cloudu

1. V draftenu si nejdřív otevřete Organizace → **Přihlašování členů**, kartu
   **Přihlášení účtem a připojení schránek**. Ukazuje dvě **redirect URI**
   přesně pro vaši adresu draftenu — končí na `/auth/google/callback`
   a `/mailboxes/connect/google/callback`. Zkopírujte je odtud; musí sedět znak
   po znaku.
2. V projektu se zapnutým **Gmail API** (krok 2 cesty A) otevřete **APIs
   & Services** → **OAuth consent screen**. **User type**: **Internal** —
   přihlásit se pak může jen účet vaší domény a aplikaci nemusí ověřovat
   Google. Vyplňte název aplikace (třeba `draften`) a kontaktní e-mail.
3. V části s rozsahy (**Scopes** / **Data access**) přidejte `openid`,
   `email`, `profile` a `https://www.googleapis.com/auth/gmail.modify`.
4. **APIs & Services** → **Credentials** → **Create credentials** → **OAuth
   client ID**. **Application type**: **Web application**. Do **Authorized
   redirect URIs** vložte obě adresy z karty a klikněte na **Create**.
5. Zkopírujte **Client ID** a **Client secret**.

### V draftenu

1. **Vlastník organizace** v kartě **Přihlášení účtem a připojení schránek**
   vyplní u **Google OAuth klient** hodnoty **Client ID** a **Client secret**
   a klikne na **Uložit**.
2. **Vlastník schránky** otevře stránku schránky a v kartě **Přístup
   k poště** klikne na **Připojit Gmail**. Přihlásí se **účtem té schránky**
   — jiný účet draften odmítne — a povolí přístup. Tlačítko vidí jen vlastník
   schránky, a jen když organizace OAuth klienta má.
3. Pak **Otestovat spojení**.

**Přihlašování účtem Google** zapnete na téže stránce: do **E-mailové domény
organizace** napište svou doménu Workspace — primární, ne aliasovou (tu Google
při přihlášení neposílá). Jakmile má organizace OAuth klienta i doménu,
členové se přihlašují účtem Google a jejich hesla přestanou platit — viz
[Přihlašování členů](/cs/admin/member-sign-in).

### Když se schránka odpojí

- **Účet byl smazán nebo zablokován, nebo přístup odvolán** — Google přestane
  vydávat tokeny a draften schránku odpojí. Připojte ji znovu (**Znovu
  připojit Gmail**), nebo cestou A.
- **„Poskytovatel nevydal obnovovací token“** — vlastník schránky odebere
  aplikaci v nastavení svého účtu Google (**Zabezpečení** → **Aplikace
  třetích stran**) a připojí schránku znovu.
- **„Přihlásil se jiný účet, než je adresa schránky“** — při připojení vyberte
  účet právě té schránky.

## Chyby testu spojení

Test ověří tři kroky: **Přístup**, **Token a oprávnění** a **Čtení Inboxu**.

| V hlášce | Co to znamená | Co udělat |
|---|---|---|
| delegace pro rozsah není povolená (`unauthorized_client`) | v Google Admin chybí domain-wide delegation, nebo má jiné Client ID či rozsah | zkontrolovat delegaci v Google Admin: číselné ID a přesný rozsah `gmail.modify` |
| `invalid_grant` u servisního účtu | taková schránka v doméně Workspace není | zkontrolovat adresu schránky |
| „Gmail API has not been used…“ | v projektu není zapnuté Gmail API | zapnout Gmail API (krok 2) |
| token bez `gmail.modify` | delegace nebo consent screen nemá rozsah `gmail.modify` | doplnit rozsah |
| `invalid_grant`, `deleted_client` u připojeného účtu | připojení bylo odvoláno nebo OAuth klient smazán | **Znovu připojit Gmail** |

Další chyby popisuje [Řešení potíží](/cs/admin/troubleshooting).