Bezpieczna autentykacja w Google Workspace CLI – OAuth, Service Accounts, CI/CD

Danie agentowi AI dostępu do firmowego Gmaila brzmi ryzykownie. I słusznie – jeden błąd w konfiguracji może oznaczać wyciek poufnych danych, nieautoryzowane wiadomości wysłane w imieniu firmy lub dostęp do dokumentów, które nigdy nie powinny opuścić organizacji. Ale przy właściwej konfiguracji uwierzytelniania agent AI może być bezpieczniejszy niż przeciętny pracownik z hasłem zapisanym na karteczce.

1. Dlaczego uwierzytelnianie to fundament bezpieczeństwa
2. Metody uwierzytelniania w gws
3. Wiele kont: różne konteksty, jedno narzędzie
4. Domain-Wide Delegation: kiedy i jak
5. Pułapki i jak ich uniknąć
6. Lista kontrolna bezpiecznego wdrożenia

Dlaczego uwierzytelnianie to fundament bezpieczeństwa

Agent AI z dostępem do Google Workspace to potężne narzędzie. Może czytać i wysyłać wiadomości, zarządzać kalendarzem, edytować dokumenty, analizować arkusze. Ale każda z tych możliwości to również potencjalne ryzyko.

Wyobraź sobie scenariusz: agent dostaje polecenie „wyślij podsumowanie projektu do klienta". Bez właściwej konfiguracji:

• Może wysłać wiadomość do niewłaściwej osoby
• Może załączyć poufne dokumenty
• Może działać pod kontem użytkownika, który nie powinien mieć takiego dostępu
• Może zostawić ślad w logach, który nie pozwoli zidentyfikować zleceniodawcy

Z właściwą konfiguracją uwierzytelniania każda z tych sytuacji jest kontrolowana. Agent działa tylko w ramach przyznanych uprawnień, każda akcja jest rejestrowana, a dostęp można w każdej chwili cofnąć.

Metody uwierzytelniania w gws

Google Workspace CLI oferuje kilka metod uwierzytelniania – każda dopasowana do innego scenariusza.

Desktop OAuth – dla programistów

Najprostszy sposób na start. Uruchamiasz komendę, otwiera się przeglądarka, logujesz się na konto Google i autoryzujesz dostęp.

gws auth setup
gws auth login --scopes drive,gmail,calendar

Przy pierwszym uruchomieniu gws auth setup tworzy projekt OAuth w Google Cloud Console (lub wykorzystuje istniejący, jeśli masz zainstalowane gcloud CLI). Następnie gws auth login przeprowadza standardowy proces OAuth – przekierowuje do Google, gdzie zatwierdzasz dostęp.

Zalety: Szybki start, intuicyjny proces.

Wady: Wymaga interakcji, nie nadaje się do automatyzacji, poświadczenia powiązane z konkretnym użytkownikiem.

Service Account – dla produkcji

Service Account to „konto robota" – tożsamość bez człowieka za klawiaturą. Idealne dla agentów AI działających na serwerach.

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
gws auth login --service-account

Service Account nie przechodzi przez proces OAuth. Zamiast tego używa klucza JSON wydanego przez Google Cloud Console. Ten klucz to „dowód osobisty" Twojego agenta – przechowuj go jak hasło do sejfu.

Headless/CI – dla procesów automatycznych

W środowisku CI/CD (GitHub Actions, GitLab CI, Jenkins) nie możesz otworzyć przeglądarki. gws oferuje eksport poświadczeń do zmiennej środowiskowej:

# Lokalnie: wygeneruj zaszyfrowany token
gws auth export > credentials.enc

# W CI: użyj tokenu
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=credentials.enc
gws drive files list

Poświadczenia są szyfrowane algorytmem AES-256-GCM. Klucz szyfrujący przechowujesz w sekretach CI/CD.

Wiele kont: różne konteksty, jedno narzędzie

W codziennej pracy często korzystasz z wielu kont – firmowego, osobistego, klienta. gws obsługuje to elegancko:

# Dodaj konto firmowe
gws auth login --account work --scopes drive,gmail

# Dodaj konto osobiste  
gws auth login --account personal --scopes drive

# Użyj konkretnego konta
gws drive files list --account work
gws calendar-agenda --account personal

Poświadczenia dla każdego konta są przechowywane osobno, szyfrowane AES-256-GCM, z kluczem w systemowym pęku kluczy (Keychain na macOS, Secret Service na Linuksie, Credential Manager na Windows).

Domain-Wide Delegation: kiedy i jak

Domain-Wide Delegation to supermoc – pozwala Service Account działać w imieniu dowolnego użytkownika w domenie Google Workspace. Agent może wysłać wiadomość „jako" Jan Kowalski, bez znajomości hasła Jana.

Brzmi niebezpiecznie? Bo jest. Dlatego wymaga świadomej konfiguracji.

Kiedy używać DWD

• Agent obsługuje wielu użytkowników w organizacji
• Potrzebujesz automatyzacji obejmującej wielu użytkowników (np. zbieranie raportów z kalendarzy zespołu)
• Budujesz narzędzie dla całej firmy, nie pojedynczego użytkownika

Jak skonfigurować bezpiecznie

1. Stwórz dedykowany Service Account – osobny do tego celu, nie współdzielony z innymi aplikacjami.
2. Przyznaj minimalne zakresy uprawnień – nie https://www.googleapis.com/auth/gmail (pełny dostęp), tylko https://www.googleapis.com/auth/gmail.readonly jeśli agent tylko czyta.
3. Ogranicz użytkowników – w Admin Console możesz określić, których użytkowników Service Account może reprezentować.
4. Włącz rejestrowanie audytowe – każda akcja wykonana przez DWD jest zapisywana w Admin Reports API.

# Użycie DWD
gws gmail users messages list   --service-account   --impersonate "jan.kowalski@firma.pl"

Więcej o bezpieczeństwie agentów AI znajdziesz w artykule Anatomia bezpiecznego agenta AI.

Pułapki i jak ich uniknąć

Konfiguracja OAuth dla Google Workspace ma swoje pułapki. Oto najczęstsze:

„Access blocked" lub 403

Przyczyna: Niezweryfikowana aplikacja OAuth ma limit około 100 użytkowników. Jeśli nie jesteś na liście użytkowników testowych, dostaniesz błąd.

Rozwiązanie: W Google Cloud Console → OAuth consent screen → Test users dodaj swoje konto.

„Google hasn't verified this app"

Przyczyna: Normalne dla aplikacji w trybie testowym.

Rozwiązanie: Kliknij „Advanced" → „Go to [nazwa aplikacji] (unsafe)". To ostrzeżenie zniknie po weryfikacji aplikacji przez Google (dla produkcji).

Limit 25 zakresów uprawnień

Przyczyna: Niezweryfikowane aplikacje mają ograniczoną liczbę zakresów.

Rozwiązanie: Nie żądaj wszystkich zakresów naraz. Użyj --scopes drive,gmail,calendar zamiast domyślnego recommended.

redirect_uri_mismatch

Przyczyna: Klient OAuth skonfigurowany jako „Web application" zamiast „Desktop app".

Rozwiązanie: W Cloud Console → Credentials → OAuth 2.0 Client IDs zmień typ na Desktop app.

Lista kontrolna bezpiecznego wdrożenia

Przed uruchomieniem agenta AI z dostępem do Google Workspace przejdź przez tę listę:

Uwierzytelnianie:

• Service Account z osobnym kluczem (nie współdzielonym)
• Minimalne zakresy uprawnień – tylko to, czego agent naprawdę potrzebuje
• Klucz w menedżerze sekretów, nie w repozytorium
• Harmonogram rotacji kluczy (minimum co 90 dni)

Uprawnienia:

• Domain-Wide Delegation tylko jeśli konieczne
• Lista dozwolonych użytkowników do reprezentowania
• Brak dostępu do Admin API (chyba że absolutnie wymagane)

Monitoring:

• Rejestrowanie audytowe włączone w Admin Console
• Alerty na nietypową aktywność
• Regularne przeglądy logów

Testy:

• Przetestuj na koncie testowym przed produkcją
• Zweryfikuj, że agent nie może wyjść poza przyznane zakresy
• Sprawdź, co się dzieje przy cofnięciu uprawnień

Jeśli chcesz zobaczyć, jak OpenClaw integruje się z zewnętrznymi narzędziami przez MCP, sprawdź nasz przewodnik po integracji.