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ć

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.

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) 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.

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.

Pozostałe błędy opisuje strona Rozwiązywanie problemów.