Żeby asystent mógł czytać pocztę w Google Workspace i tworzyć w niej szkice, potrzebuje dostępu przez Gmail API. W tym celu organizacja tworzy coś 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.
Wszystko tutaj dotyczy tylko kont Google Workspace z własną domeną. Osobistym kontem @gmail.com nie da się zalogować do draften; osobisty Gmail podłączysz jednak przez IMAP z hasłem aplikacji – zobacz Obsługiwani dostawcy i ograniczenia.
Czego chcesz i co ustawić
| Czego chcesz | Co ustawić |
|---|---|
| Członkowie logują się kontem Google i każdy ma własną skrzynkę | klient organizacji – to wystarczy |
| Do tego skrzynki, do których nikt się nie loguje (na przykład info@), albo dostęp do skrzynek ustawiany centralnie, bez ich właścicieli | dodatkowo rejestracja organizacji (konto usługi) |
| Logowania kontem Google nie chcesz | ludzie logują się hasłem z zaproszenia, pocztę podłącza rejestracja organizacji (albo IMAP) |
Dwie różne rzeczy w Google
Klient organizacji i rejestracja organizacji to dwie osobne rzeczy w Google Cloud. Każda robi coś innego i jedna nie zastąpi drugiej:
| Klient organizacji | Rejestracja organizacji | |
|---|---|---|
| Co to jest | klient OAuth z ekranem zgody typu Internal | konto usługi z kluczem i domain-wide delegation |
| Co robi | logowanie członków przyciskiem Zaloguj się przez Google i przycisk Podłącz Gmail przy własnej skrzynce | dostęp asystenta do skrzynek bez logowania się ich właścicieli |
| Gdzie w draften | Organizacja → Logowanie i dostęp do poczty → karta Logowanie kontem i podłączanie skrzynek | Organizacja → Logowanie i dostęp do poczty → karta Rejestracje dla skrzynek współdzielonych i zarządzania centralnego |
| Kto ją ustawia w draften | właściciel organizacji | właściciel lub menedżer organizacji |
| Kto ją tworzy w Google | administrator Google Cloud | administrator Google Cloud i superadministrator Google Admin |
| Kto loguje się do skrzynki | właściciel każdej skrzynki, jeden raz | nikt |
| Do których skrzynek sięga | tylko do tych, które ludzie podłączą sami | do wszystkich skrzynek domeny |
To celowo dwie rzeczy. Zgoda na klienta daje prawa tylko do skrzynek, które ludzie podłączą sami – nigdy do poczty całej domeny. Konto usługi sięga natomiast do każdej skrzynki domeny, dlatego dostaje je tylko draften do dostępu do skrzynek, a nie logowanie. Nie łącz ich.
Każda skrzynka używa jednego z obu dostępów; obie rzeczy możesz mieć jednocześnie. draften prosi tylko o zakres gmail.modify – odczyt i tworzenie szkiców, niczego nie wysyła.
Klient organizacji: logowanie i Podłącz Gmail
Właściciel skrzynki loguje się swoim kontem Google i zezwala na dostęp tylko do swojej poczty. Ten sam klient służy też do logowania do draften kontem Google.
W Google Cloud
Pracujesz w https://console.cloud.google.com, zalogowany kontem administratora swojej domeny Workspace. Wszystko dzieje się w jednym projekcie – wybrany projekt widać u góry po lewej obok logo Google Cloud; tam go też przełączysz albo utworzysz nowy. Menu główne otworzysz ikoną ☰ w lewym górnym rogu.
- W draften najpierw otwórz Organizacja → Logowanie i dostęp do poczty, kartę Logowanie kontem i podłączanie skrzynek. Pokazuje dwa redirect URI dokładnie dla twojego adresu draften – kończą się na
/auth/google/callbacki/mailboxes/connect/google/callback. Skopiuj je stamtąd; muszą się zgadzać znak po znaku. - Wybierz projekt albo utwórz nowy (na przykład
draften) i włącz w nim Gmail API: ☰ → APIs & Services → Library, wyszukaj Gmail API, otwórz je i kliknij Enable. Bezpośrednio: https://console.cloud.google.com/apis/library/gmail.googleapis.com - Ustaw, jak aplikacja przedstawi się użytkownikom (consent screen): ☰ → APIs & Services → OAuth consent screen. Otworzy się strona Google Auth Platform; bezpośrednio: https://console.cloud.google.com/auth/overview (sprawdź, czy u góry jest wybrany właściwy projekt). Kliknij Get started i przejdź kreator:
- App Information – App name
drafteni User support email (twój e-mail albo grupa administratorów). Next. - Audience – wybierz Internal. Zalogować się może wtedy tylko konto twojej domeny Workspace, a aplikacji nie musi weryfikować Google. Next.
- Contact Information – e-mail, na który Google wyśle ci powiadomienia dotyczące aplikacji. Next.
- Finish – zaznacz pole zgody na zasady Google (I agree to the Google API Services: User Data Policy), kliknij Continue, a potem Create.
- App Information – App name
- Zezwól aplikacji na zakresy. W Google Auth Platform w menu po lewej otwórz Data Access (bezpośrednio: https://console.cloud.google.com/auth/scopes) → Add or remove scopes. Na liście zaznacz
openid,.../auth/userinfo.emaili.../auth/userinfo.profile. Zakres dla Gmaila wklej do pola Manually add scopes:https://www.googleapis.com/auth/gmail.modify→ Add to table. Kliknij Update, a na dole Save. - Utwórz klienta. W Google Auth Platform w menu po lewej otwórz Clients (bezpośrednio: https://console.cloud.google.com/auth/clients) → Create client. Application type: Web application, nazwa na przykład
draften. Przy Authorized redirect URIs kliknij Add URI i wklej pierwszy adres z karty, potem znowu Add URI i drugi. Kliknij Create. - Wyświetlą się Client ID i Client secret – od razu skopiuj oba. Client secret Google później już nie pokaże; gdybyś go zgubił, utworzysz przy kliencie nowy.
W draften
- Właściciel organizacji otwiera Organizacja → Logowanie i dostęp do poczty, na karcie Logowanie kontem i podłączanie skrzynek wypełnia w sekcji Klient Google OAuth pola Client ID i Client secret z kroku 6 i klika Zapisz.
- Logowanie kontem Google włącza na tej samej stronie w karcie Logowanie członków: w polu Domeny e-mail organizacji wpisuje swoją domenę Workspace – główną, nie domenę aliasu (tej Google przy logowaniu nie wysyła). Gdy organizacja ma klienta i domenę, członkowie logują się kontem Google, a ich hasła przestają działać – zobacz Logowanie członków.
- Właściciel skrzynki otwiera stronę skrzynki i na karcie Dostęp do poczty w wierszu Podłącz kontem skrzynki: 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; bez niego karta zamiast przycisku napisze, że podłączenie kontem będzie możliwe, gdy właściciel organizacji doda klienta.
- Potem Przetestuj połączenie.
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 rejestracją organizacji (poniżej).
- „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.
Rejestracja organizacji: dostęp bez logowania
Konto usługi z domain-wide delegation daje asystentowi dostęp do skrzynek domeny bez tego, żeby ktokolwiek się logował. Przydaje się dla skrzynek, do których nikt się nie loguje (na przykład info@), i dla organizacji, które chcą zarządzać dostępem centralnie. Z logowaniem do draften nie ma nic wspólnego.
W Google Cloud
Pracujesz w https://console.cloud.google.com, w tym samym projekcie, w którym jest włączone Gmail API (krok 2 przy kliencie organizacji; bez klienta włącz je tak samo). Projekt sprawdź u góry po lewej obok logo Google Cloud.
- Otwórz listę kont usługi: ☰ → IAM & Admin → Service accounts. Bezpośrednio: https://console.cloud.google.com/iam-admin/serviceaccounts
- U góry kliknij + Create service account i przejdź trzy kroki:
- Service account details – Service account name na przykład
draften-poczta(ID uzupełni się samo). Kliknij Create and continue. - Permissions (optional) – niczego nie wybieraj; konto nie potrzebuje żadnych ról w projekcie, dostęp do poczty da mu dopiero delegowanie w Google Admin. Kliknij Continue.
- Principals with access (optional) – niczego nie wypełniaj, kliknij Done.
- Service account details – Service account name na przykład
- Na liście kliknij nowe konto usługi. Na zakładce Details skopiuj Unique ID – długą liczbę; to Client ID dla Google Admin.
- Zakładka Keys → Add key → Create new key → Key type: JSON → Create. Przeglądarka pobierze plik z kluczem (
….json).
Gdy Google odmówi utworzenia klucza, twoja organizacja ma włączoną zasadę Disable service account key creation (iam.disableServiceAccountKeyCreation; nowe organizacje mają ją domyślnie). Administrator organizacji wyłącza ją dla tego projektu: ☰ → IAM & Admin → Organization policies (https://console.cloud.google.com/iam-admin/orgpolicies), wyszukuje iam.disableServiceAccountKeyCreation → Manage policy → Override parent's policy → Enforcement: Off → Set policy. Potem powtórz krok 4.
W Google Admin
Potrzebujesz konta superadministratora Google Workspace.
- Otwórz https://admin.google.com → w menu po lewej Security → Access and data control → API controls → na dole Domain wide delegation → Manage domain wide delegation. Bezpośrednio: https://admin.google.com/ac/owl/domainwidedelegation
- Kliknij Add new i wypełnij:
- Client ID – numeryczne Unique ID z kroku 3,
- OAuth scopes (comma-delimited) –
https://www.googleapis.com/auth/gmail.modify.
Kliknij Authorize. Delegowanie pojawi się na liście. Zaczyna działać zwykle w ciągu kilku minut, wyjątkowo dopiero po kilku godzinach.
W draften
- Otwórz Organizacja → Logowanie i dostęp do poczty, kartę Rejestracje dla skrzynek współdzielonych i zarządzania centralnego. Rejestracjami zarządza właściciel lub menedżer organizacji.
- 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.
- Na stronie każdej skrzynki, na karcie Dostęp do poczty, wybierz w polu Rejestracja organizacji 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 (krok 4 powyżej) prześlesz przy rejestracji opcją nowy klucz (JSON); klucz innego konta usługi dodaj jako nową rejestrację. Stary klucz potem usuń w Google Cloud: konto usługi → zakładka Keys → ikona kosza przy starym kluczu.
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.
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 |
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 usunięty | Podłącz Gmail ponownie |
Pozostałe błędy opisuje strona Rozwiązywanie problemów.