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

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

1. Dlaczego auth to fundament bezpieczeństwa
2. Metody autentykacji w gws
3. Multi-account: różne konta, różne konteksty
4. Domain-Wide Delegation: kiedy i jak
5. Pułapki i jak ich uniknąć
6. Checklist bezpiecznego wdrożenia

Dlaczego auth to fundament bezpieczeństwa

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

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

• Może wysłać maila 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ć, kto naprawdę zlecił akcję

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

Metody autentykacji w gws

Google Workspace CLI oferuje kilka metod autentykacji, każda dopasowana do innego scenariusza użycia.

Desktop OAuth — dla deweloperów

Najprostrzy 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 flow OAuth — przekierowuje do Google, gdzie zatwierdzasz dostęp.

Zalety: Szybki start, intuicyjny proces.

Wady: Wymaga interakcji, nie nadaje się do automatyzacji, credentials 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 OAuth flow. Zamiast tego używa klucza JSON wydanego przez Google Cloud Console. Ten klucz to Twój „dowód osobisty" agenta — przechowuj go jak hasło do sejfu.

Headless/CI — dla pipeline'ów

W środowisku CI/CD (GitHub Actions, GitLab CI, Jenkins) nie możesz otworzyć przeglądarki. gws oferuje export credentials 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

Credentials są szyfrowane AES-256-GCM. Klucz szyfrujący przechowujesz w sekretach CI/CD.

Multi-account: różne konta, różne konteksty

W realnym świecie często pracujesz z wieloma kontami — firmowe, osobiste, 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

Credentials dla każdego konta są przechowywane osobno, szyfrowane AES-256-GCM, z kluczem w systemowym keyringu (Keychain na macOS, Secret Service na Linux, 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ć maila „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 cross-user (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 dla tego celu, nie współdzielony z innymi aplikacjami.
2. Przyznaj minimalne scopes — 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 impersonować.
4. Włącz audit logging — każda akcja wykonana przez DWD jest logowana 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 ~100 użytkowników. Jeśli nie jesteś na liście test users, 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 [app name] (unsafe)". To ostrzeżenie zniknie po weryfikacji aplikacji przez Google (dla produkcji).

Limit 25 scopes

Przyczyna: Niezweryfikowane aplikacje mają limit scope'ów.

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

redirect_uri_mismatch

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

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

Checklist bezpiecznego wdrożenia

Przed uruchomieniem agenta AI z dostępem do Google Workspace, przejdź przez ten checklist:

Autentykacja:

• Service Account z osobnym kluczem (nie współdzielonym)
• Minimalne scopes — tylko to, co agent naprawdę potrzebuje
• Klucz w secret managerze, nie w repo
• Harmonogram rotacji kluczy (co 90 dni minimum)

Uprawnienia:

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

Monitoring:

• Audit logging włączony 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 scope'y
• 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.