# Google Workspace: podłączanie skrzynek

Żeby asystent mógł czytać pocztę w Google Workspace i tworzyć w niej szkice,
potrzebuje dostępu przez Gmail API. Są na to dwie drogi i obie opierają się na
tym, co organizacja tworzy we **własnym Google Cloud**. draften nie ma
wspólnej aplikacji, której wystarczyłoby udzielić zgody. Dotyczy to zarówno
naszej usługi, jak i instalacji na własnym serwerze.

Zakładamy **Google Workspace**. Kont osobistych `@gmail.com` nie obsługujemy:
nie da się nimi zalogować do draften, a ich podłączenie wymagałoby, żeby
aplikację zweryfikował Google.

## Którą drogę wybrać

| | Za całą organizację | Kontem skrzynki |
|---|---|---|
| W draften | rejestracja (konto usługi) w Organizacja → **Integracje** | przycisk **Podłącz Gmail** przy skrzynce |
| W Google | konto usługi z kluczem i domain-wide delegation | klient OAuth i ekran zgody typu Internal |
| Kto tworzy | administrator Google Cloud i superadministrator Google Admin | administrator Google Cloud |
| Kto musi się zalogować | nikt | właściciel każdej skrzynki, jeden raz |
| Do których skrzynek sięga | do wszystkich skrzynek domeny | tylko do skrzynki, której konto się zalogowało |
| Logowanie do draften kontem Google | nie, to osobna sprawa | ten sam klient OAuth służy też do logowania |

Dla organizacji z wieloma skrzynkami prostsza jest **droga za całą
organizację**. **Kontem skrzynki** przydaje się, gdy nie chcesz dawać jednemu
kluczowi dostępu do wszystkich skrzynek domeny albo gdy i tak wprowadzasz
logowanie kontem Google.

Obie drogi możesz mieć jednocześnie; każda skrzynka używa jednej z nich.
draften prosi tylko o zakres `gmail.modify` – odczyt i tworzenie szkiców,
niczego nie wysyła.

## Droga A: za całą organizację

### W Google Cloud

Pracujesz w https://console.cloud.google.com, w organizacji swojej domeny
Workspace.

1. Wybierz projekt albo utwórz nowy (na przykład `draften`).
2. **APIs & Services** → **Library** → **Gmail API** → **Enable**.
3. **IAM & Admin** → **Service accounts** → **Create service account**. Nazwa
   na przykład `draften-poczta`. Nie potrzebuje żadnych ról w projekcie –
   dostęp do poczty da mu dopiero delegowanie w Google Admin. Kliknij
   **Done**.
4. Otwórz konto usługi i zanotuj jego **Unique ID** – numeryczny Client ID.
5. Zakładka **Keys** → **Add key** → **Create new key** → **JSON** →
   **Create**. Pobierze się plik z kluczem.

!> Gdy Google odmówi utworzenia klucza, twoja organizacja ma włączoną zasadę
`iam.disableServiceAccountKeyCreation` (nowe organizacje mają ją domyślnie).
Dla tego projektu wyłączy ją administrator organizacji w **IAM & Admin** →
**Organization policies**.

### W Google Admin

Potrzebujesz superadministratora. W https://admin.google.com otwórz
**Security** → **Access and data control** → **API controls** → **Manage
Domain Wide Delegation** → **Add new**. **Client ID**: numeryczne ID z kroku 4.
**OAuth scopes**: `https://www.googleapis.com/auth/gmail.modify`. Kliknij
**Authorize**. Delegowanie zaczyna zwykle działać w ciągu kilku minut,
wyjątkowo dopiero po kilku godzinach.

### W draften

1. Otwórz Organizacja → **Integracje**, kartę **Dostęp do poczty dla całej
   organizacji**. Rejestracjami zarządza właściciel lub menedżer organizacji.
2. **System**: **Google Workspace**. Wypełnij **Nazwa**, w polu **Klucz konta
   usługi (JSON)** wybierz pobrany plik i kliknij **Dodaj rejestrację**.
   Klucz jest przechowywany w postaci zaszyfrowanej; na karcie widać potem
   tylko e-mail konta usługi i jego Client ID.
3. Na stronie każdej skrzynki, na karcie **Dostęp do poczty**, wybierz w polu
   **Użyj** tę rejestrację, kliknij **Zastosuj**, a potem **Przetestuj
   połączenie**. Postępowanie ze zrzutami ekranu pokazuje instrukcja [Dodanie
   i podłączenie skrzynki](/pl/admin/adding-a-mailbox).

**Pobrany plik z kluczem potem usuń.** Kto go ma, dostanie się do każdej
skrzynki domeny. Nowy klucz tego samego konta usługi prześlesz przy
rejestracji opcją **nowy klucz (JSON)**; klucz innego konta usługi dodaj jako
nową rejestrację. Stary klucz w Google Cloud usuń.

Przy włączonej **automatycznej skrzynce** ([Logowanie
członków](/pl/admin/member-sign-in)) nowa skrzynka zostaje powiązana
z rejestracją sama, jeśli dla Google Workspace jest dokładnie jedna aktywna.

## Droga B: kontem skrzynki (Podłącz Gmail)

Tutaj właściciel skrzynki loguje się swoim kontem Google i zezwala na dostęp
tylko do swojej poczty. Ten sam klient OAuth służy też do **logowania do
draften kontem Google**.

### W Google Cloud

1. W draften najpierw otwórz Organizacja → **Logowanie członków**, kartę
   **Logowanie kontem i podłączanie skrzynek**. Pokazuje dwa **redirect URI**
   dokładnie dla twojego adresu draften – kończą się na `/auth/google/callback`
   i `/mailboxes/connect/google/callback`. Skopiuj je stamtąd; muszą się
   zgadzać znak po znaku.
2. W projekcie z włączonym **Gmail API** (krok 2 drogi A) otwórz **APIs
   & Services** → **OAuth consent screen**. **User type**: **Internal** –
   zalogować się może wtedy tylko konto twojej domeny, a aplikacji nie musi
   weryfikować Google. Wpisz nazwę aplikacji (na przykład `draften`)
   i kontaktowy e-mail.
3. W części z zakresami (**Scopes** / **Data access**) dodaj `openid`,
   `email`, `profile` i `https://www.googleapis.com/auth/gmail.modify`.
4. **APIs & Services** → **Credentials** → **Create credentials** → **OAuth
   client ID**. **Application type**: **Web application**. W **Authorized
   redirect URIs** wklej oba adresy z karty i kliknij **Create**.
5. Skopiuj **Client ID** i **Client secret**.

### W draften

1. **Właściciel organizacji** na karcie **Logowanie kontem i podłączanie
   skrzynek** wypełnia w sekcji **Klient Google OAuth** pola **Client ID**
   i **Client secret** i klika **Zapisz**.
2. **Właściciel skrzynki** otwiera stronę skrzynki i na karcie **Dostęp do
   poczty** klika **Podłącz Gmail**. Loguje się **kontem tej skrzynki** – inne
   konto draften odrzuci – i zezwala na dostęp. Przycisk widzi tylko
   właściciel skrzynki i tylko wtedy, gdy organizacja ma klienta OAuth.
3. Potem **Przetestuj połączenie**.

**Logowanie kontem Google** włączysz na tej samej stronie: w polu **Domeny
e-mail organizacji** wpisz swoją domenę Workspace – główną, nie domenę aliasu
(tej Google przy logowaniu nie wysyła). Gdy organizacja ma klienta OAuth
i domenę, członkowie logują się kontem Google, a ich hasła przestają działać –
zobacz [Logowanie członków](/pl/admin/member-sign-in).

### Gdy skrzynka się odłączy

- **Konto zostało usunięte albo zablokowane lub dostęp został cofnięty** –
  Google przestaje wydawać tokeny i draften odłącza skrzynkę. Podłącz ją
  ponownie (**Podłącz Gmail ponownie**) albo drogą A.
- **„Dostawca nie wydał tokenu odświeżania”** – właściciel skrzynki usuwa
  aplikację w ustawieniach swojego konta Google (**Bezpieczeństwo** →
  **Aplikacje innych firm**) i podłącza skrzynkę ponownie.
- **„Zalogowało się inne konto niż adres skrzynki”** – przy podłączaniu wybierz
  konto właśnie tej skrzynki.

## Błędy testu połączenia

Test sprawdza trzy kroki: **Dostęp**, **Token i uprawnienie** i **Odczyt
skrzynki odbiorczej**.

| W komunikacie | Co to znaczy | Co zrobić |
|---|---|---|
| delegowanie dla zakresu nie jest dozwolone (`unauthorized_client`) | w Google Admin brakuje domain-wide delegation albo ma ona inny Client ID lub zakres | sprawdź delegowanie w Google Admin: numeryczne ID i dokładny zakres `gmail.modify` |
| `invalid_grant` przy koncie usługi | takiej skrzynki nie ma w domenie Workspace | sprawdź adres skrzynki |
| „Gmail API has not been used…” | w projekcie nie jest włączone Gmail API | włącz Gmail API (krok 2) |
| token bez `gmail.modify` | delegowanie albo ekran zgody nie ma zakresu `gmail.modify` | uzupełnij zakres |
| `invalid_grant`, `deleted_client` przy podłączonym koncie | połączenie zostało cofnięte albo klient OAuth usunięty | **Podłącz Gmail ponownie** |

Pozostałe błędy opisuje strona [Rozwiązywanie problemów](/pl/admin/troubleshooting).