Administracja Google Workspace

GAM 7: instalacja, zastosowania i administracja Google Workspace

Opublikowano: 26 września 2026 r. · Autor: Jan Chmielewski · Polecenia i semantyka dat: GAM 7.48.14.

GAM 7 ułatwia zarządzanie kontami, grupami, raportami i usługami Google Workspace. W tym poradniku poznasz jego zastosowania oraz przejdziesz przez konfigurację na konkretnym przykładzie: pracownik wyjechał na urlop, a w firmowej poczcie zabrakło automatycznej odpowiedzi. Administrator Google Workspace może ustawić ją przez GAM 7 bez poznawania lub resetowania hasła pracownika. Potrzebuje jednak prawidłowo przygotowanego projektu Google Cloud, konta usługi i świadomie ograniczonej delegacji uprawnień.

GAM wykonuje polecenia przez API. Bezpieczeństwo zależy od delegacji, zakresów dostępu i ochrony poświadczeń.

Czym jest GAM 7?

GAM 7 to otwartoźródłowe narzędzie wiersza poleceń rozwijane w projekcie GAM-team/GAM. Ułatwia administratorom pracę z API Google Workspace: od kont i grup po ustawienia usług użytkowników. Nie jest panelem Google ani sposobem na obejście zabezpieczeń. Samo zainstalowanie programu nie daje dostępu do organizacji. Wymagania dotyczące edycji Workspace opisuje oficjalna dokumentacja GAM 7.

Ten scenariusz dotyczy firmowego konta Workspace z aktywną usługą Gmail. Nie jest instrukcją przejmowania prywatnej skrzynki Gmail. Najpierw uzgodnij z osobą uprawnioną adres pracownika, treść odpowiedzi, okres nieobecności i odbiorców. W przykładach używamy wyłącznie fikcyjnego adresu pracownik@example.com.

Trzy różne mechanizmy autoryzacji

OAuth przy tworzeniu projektu: zgoda administratora na operacje w Google Cloud, np. przygotowanie projektu i konta usługi. Nie jest delegacją dostępu do Gmaila pracowników.
Klient OAuth typu Desktop app: umożliwia interaktywne uwierzytelnienie operatora. Plik client_secrets.json opisuje aplikację, a oauth2.txt przechowuje uzyskane poświadczenia użytkownika.
Konto usługi i Domain-Wide Delegation (DWD): pozwalają aplikacji działać w imieniu użytkownika Workspace w granicach zatwierdzonych zakresów. Lokalne dane konta usługi znajdują się w oauth2service.json.

Delegacja skrzynki w interfejsie Gmail jest innym mechanizmem. Nie należy zakładać, że delegat skrzynki ma prawo zmieniać autoresponder. Poniższa procedura korzysta z API i DWD, a nie z logowania do skrzynki jako delegat.

1. Zainstaluj GAM 7 i oddziel konfigurację

Pobierz pakiet z oficjalnych wydań GAM-team/GAM. Dobierz system, architekturę (np. Apple Silicon/ARM64 lub Intel/x86_64) i wspieraną wersję systemu. Na macOS i Linux można rozpakować archiwum, na Windows użyć instalatora lub ZIP. Szczegóły i dostępne warianty zawiera instrukcja instalacji. Numer 7.48.14 wskazuje wersję sprawdzaną dla tego przykładu, nie deklarację najnowszego wydania.

Dalsze bloki są przeznaczone dla terminala macOS/Linux. Długie polecenia na telefonie można przewijać poziomo w obrębie bloku. Przyjmujemy, że plik wykonywalny znajduje się w $HOME/bin/gam7; jeśli wybrano inne miejsce, dostosuj ścieżkę. Nie uruchamiaj GAM jako root. Przed pierwszą autoryzacją przygotuj oddzielny katalog, poza repozytorium strony i folderem udostępnianym innym osobom:

umask 077
mkdir -p "$HOME/.gam-urlop"
chmod 700 "$HOME/.gam-urlop"
export GAMCFGDIR="$HOME/.gam-urlop"
export PATH="$HOME/bin/gam7:$PATH"
export TZ=Europe/Warsaw
command -v gam
gam version

Sprawdź, czy uruchamia się GAM 7 z oczekiwanego katalogu, a nie starszy program lub alias. Zmienne export działają w bieżącej sesji. Przy kolejnej sesji ustaw je ponownie lub umieść w dedykowanym skrypcie uruchamiającym. Nie zmieniaj bez sprawdzenia konfiguracji używanej do innych klientów. Osobny GAMCFGDIR izoluje pliki, ale sam nie ogranicza praw w Google.

Na Windows ustaw GAMCFGDIR w zmiennych środowiskowych zgodnie z instrukcją dla Windows, zabezpiecz katalog uprawnieniami NTFS i sprawdź strefę systemową. Składni export TZ z tego poradnika nie należy kopiować do PowerShell.

2. Utwórz i skonfiguruj projekt Google Cloud

Potrzebne są uprawnienia do tworzenia lub przygotowania projektu Cloud. Rola superadministratora Workspace nie zastępuje wszystkich uprawnień IAM i polityk organizacji Google Cloud. Usługa Google Cloud Platform musi być dostępna dla administratora. Jeżeli organizacja blokuje tworzenie projektów lub kluczy, uzgodnij konfigurację z jej administratorem, zamiast wyłączać politykę globalnie.

gam create project

Podaj konto administratora lub osoby zarządzającej projektem. W przeglądarce sprawdź właściwe konto i zakres zgody na przygotowanie zasobów Cloud.
Postępuj według kreatora GAM. Przygotowuje on projekt, API i konto usługi. Zapisz identyfikator projektu w dokumentacji administracyjnej.
W konsoli Google Cloud wybierz ten sam projekt. W Google Auth Platform sprawdź Branding i Audience; dla aplikacji wyłącznie firmowej wybierz odbiorców wewnętrznych, jeżeli taka opcja jest dostępna w organizacji. Uzupełnij wymagane dane aplikacji i kontaktu.
Pod wskazanym przez GAM adresem utwórz klienta OAuth typu Desktop app (aplikacja komputerowa), nie Web application. Przekaż jego Client ID i Client Secret do lokalnego kreatora GAM. Nie wysyłaj tych danych przez czat ani e-mail.
Sprawdź w APIs & Services → Enabled APIs, czy w tym projekcie włączone jest Gmail API. Kreator GAM może włączyć również inne API; samo ich włączenie nie nadaje aplikacji dostępu do danych Workspace.

Jeśli dział Cloud wcześniej utworzył pusty projekt, zamiast zakładać drugi użyj udokumentowanego gam use project i wskaż właściwy projekt. Nie uruchamiaj kreatora na istniejącym projekcie produkcyjnym bez sprawdzenia jego zastosowań. Przebieg i nazwy ekranów mogą się zmieniać; punktem odniesienia jest instrukcja GAM 7.

Wąska zgoda klienta OAuth na potrzeby testów

W GAM 7.48.14 test konta usługi korzysta także z poświadczeń klienta OAuth. Aby nie zaczynać od testu kończącego się komunikatem o braku dostępu klienta, przygotuj w tym osobnym profilu token identyfikacyjny operatora:

gam oauth create scopes https://www.googleapis.com/auth/userinfo.email

Zaloguj się właściwym kontem operatora. GAM dodaje wymagane zakresy identyfikacyjne; sprawdź ekran zgody. Nie wybieraj kompletu uprawnień administracyjnych. Ten token nie nadaje uprawnień do ustawień Gmaila pracownika — zostaną one nadane osobno kontu usługi. To wariant wynikający z dokumentowanej składni autoryzacji klienta i analizy kodu 7.48.14; przed użyciem na innym wydaniu zweryfikuj zachowanie testu.

3. Konto usługi, Domain-Wide Delegation i minimalne uprawnienia

W IAM & Admin → Service Accounts otwórz konto usługi utworzone dla tego projektu. W ustawieniach zaawansowanych sprawdź konfigurację delegacji domenowej i skopiuj numeryczny Client ID konta usługi. To nie jest adres e-mail konta usługi, numer projektu ani Client ID aplikacji Desktop.

Jako superadministrator Workspace przejdź do Bezpieczeństwo → Kontrola dostępu i danych → Zarządzanie interfejsami API → Zarządzaj przekazywaniem dostępu w całej domenie. Dodaj Client ID konta usługi i tylko ten zakres:

https://www.googleapis.com/auth/gmail.settings.basic

Po autoryzacji otwórz szczegóły wpisu i sprawdź zapisany zakres. Jeśli organizacja wymaga zatwierdzenia przez drugiego administratora, dokończ ten proces. Propagacja może potrwać do 24 godzin. Procedurę opisuje dokumentacja Google dotycząca DWD.

Nie dodawaj https://mail.google.com/, uprawnień do Dysku ani Directory API na zapas. Nie oznaczaj automatycznie aplikacji jako w pełni zaufanej. Kontrola aplikacji OAuth i delegacja DWD to odrębne ustawienia. Jeśli polityka blokuje aplikację, sprawdź konkretny Client ID i wymagany zakres. Zestawienie praw znajduje się w opisie zakresów Gmail API, a wymaganie metody w updateVacation.

Ustaw także zakresy żądane lokalnie przez GAM

Lista w Admin określa, na co Google pozwala. Lista w konfiguracji GAM określa, o jakie zakresy program występuje. Muszą być zgodne. Po przygotowaniu DWD i klienta OAuth wykonaj:

gam user pracownik@example.com update serviceaccount scopes https://www.googleapis.com/auth/gmail.settings.basic
gam user pracownik@example.com check serviceaccount scopes https://www.googleapis.com/auth/gmail.settings.basic
gam user pracownik@example.com show vacation

update serviceaccount zapisuje lokalną listę zakresów w pliku konta usługi; nie zastępuje zatwierdzenia w Admin. check serviceaccount sprawdza wskazany zakres, a show vacation potwierdza rzeczywisty odczyt ustawień konkretnej skrzynki. W dedykowanym profilu oczekuj pozytywnego wyniku testu DWD dla gmail.settings.basic i poprawnego odczytu. Nie zmieniaj zakresów współdzielonego profilu, bo możesz zakłócić inne zadania.

4. Ustaw autoresponder urlopowy bez hasła pracownika

Najpierw odczytaj bieżące ustawienia

gam user pracownik@example.com show vacation
gam user pracownik@example.com show vacation > vacation-przed.txt

Zachowaj wynik w chronionym katalogu roboczym, ponieważ może zawierać treść służbowej odpowiedzi. To zapis do porównania i ręcznego odtworzenia, nie plik do automatycznego importu. Sprawdź wcześniejszy tekst, stan włączenia, daty oraz ograniczenia odbiorców.

Przykład: 28 września – 2 października 2026 włącznie

export TZ=Europe/Warsaw
gam config timezone Europe/Warsaw save
gam user pracownik@example.com vacation on \
  subject "Nieobecność – urlop" \
  message "Dziękuję za wiadomość. Do 2 października włącznie przebywam na urlopie. Odpowiem po powrocie." \
  start 2026-09-28 end 2026-10-03 \
  contactsonly false domainonly false

contactsonly false nie ogranicza odpowiedzi do zapisanych kontaktów. domainonly false dopuszcza również nadawców spoza organizacji. Jeśli odpowiedź ma być wyłącznie wewnętrzna, ustaw domainonly true. Zatwierdź treść odpowiednią dla wybranych odbiorców; nie ujawniaj zbędnych szczegółów nieobecności.

Dlaczego end wskazuje 3 października?

W kodzie GAM 7.48.14 daty start i end są przeliczane przez getYYYYMMDD i time.mktime na północ w lokalnej strefie procesu. GAM nie dodaje automatycznie do end całej doby. Gmail odpowiada na wiadomości odebrane przed końcową granicą czasu. Dlatego koniec o 00:00 dnia 3 października obejmuje cały 2 października, a koniec 2 października zakończyłby urlop już na początku tego dnia.

Na macOS/Linux TZ=Europe/Warsaw ustala strefę procesu. Ustawienie timezone w GAM zapewnia spójne wyświetlanie dat; w tej wersji nie należy traktować go jako zamiennika strefy procesu przy parsowaniu dat urlopu. W pokazanym okresie Warszawa używa UTC+02:00, więc granice w UTC to 27 września 22:00 i 2 października 22:00. Po zmianie wersji lub przy uruchamianiu z harmonogramu sprawdź wynik ponownie. Podstawa: przeliczanie dat w GAM 7.48.14 oraz semantyka VacationSettings.

Dłuższa treść z pliku UTF-8

Zapisz zatwierdzoną odpowiedź w pliku urlop.txt w kodowaniu UTF-8. Następnie możesz zastąpić parametr message treścią z pliku:

gam user pracownik@example.com vacation on \
  subject "Nieobecność – urlop" file urlop.txt charset utf-8 \
  start 2026-09-28 end 2026-10-03 \
  contactsonly false domainonly false

Sprawdź zapis i wyłącz odpowiedź w razie potrzeby

gam user pracownik@example.com show vacation

Porównaj temat, polskie znaki, treść, daty i flagi odbiorców. Sam stan włączenia nie oznacza, że odpowiedź jest już wysyłana: przyszła data rozpoczęcia nadal obowiązuje. W uzgodnionym czasie wyślij wiadomość kontrolną z właściwego typu konta. Gmail nie musi odpowiadać na każdą kolejną wiadomość tego samego nadawcy — brak drugiej odpowiedzi nie jest sam w sobie dowodem awarii.

Aby zakończyć autoresponder przed terminem:

gam user pracownik@example.com vacation off
gam user pracownik@example.com show vacation

Wyłączenie nie odtwarza poprzedniej treści. Jeśli wymagana jest pełna restauracja, przywróć świadomie pola zapisane przed zmianą. Składnię opisuje dokumentacja poleceń vacation.

5. Diagnostyka: sprawdzaj warstwy dostępu osobno

No Client Access allowed: sprawdź profil GAMCFGDIR i istnienie poprawnej autoryzacji klienta OAuth. W 7.48.14 update serviceaccount zapisuje zakresy przed dalszym testem, który korzysta z klienta OAuth. Dlatego błąd na tym etapie może wystąpić mimo skutecznego zapisu lokalnego. Nie traktuj go jako poprawnego zakończenia konfiguracji ani powodu do dodania pełnych praw do Gmaila. Dokończ wąską autoryzację klienta z kroku 2, powtórz test i odczyt.
unauthorized_client lub access_denied: porównaj Client ID konta usługi oraz zakresy w DWD z zakresem żądanym przez GAM. Uwzględnij czas propagacji i polityki organizacji.
API disabled: sprawdź Gmail API we właściwym projekcie Cloud. Autoryzacja DWD nie włącza automatycznie usługi API.
Service not applicable / brak Gmaila: zweryfikuj adres, aktywność konta, licencję i dostępność Gmaila. Nie rozszerzaj delegacji, aby naprawić brak usługi.
Odpowiedź nie przychodzi: sprawdź odczytane daty, strefę, ograniczenie do domeny lub kontaktów oraz reguły wysyłania odpowiedzi w Gmailu.

Rozróżnienie zapisu zakresów i testu wynika z funkcji checkServiceAccount w kodzie 7.48.14. Nigdy nie publikuj całych plików autoryzacji ani niezredagowanych logów diagnostycznych.

6. Cofnij dostęp po zakończeniu zadania

Wyłączenie autorespondera i odebranie dostępu GAM to dwie różne czynności. Jeśli odpowiedź ma działać do końca urlopu, pozostaw zapisane ustawienia; odebranie delegacji narzędziu nie cofa już zapisanej odpowiedzi.

Zapisz w wewnętrznej ewidencji operatora, czas, uzgodniony zakres i wynik zmiany. Nie dołączaj kluczy ani tokenów.
Jeśli projekt służył wyłącznie temu zadaniu, usuń jego wpis DWD w Admin. Jeśli jest współdzielony, najpierw ustal zależności; usunięcie scope może zatrzymać inne automatyzacje.
W Google Cloud wyłącz lub usuń niepotrzebny klucz konta usługi i odbierz zbędne uprawnienia IAM. Cofnij też zgodę OAuth operatora, jeśli nie jest potrzebna.
Po propagacji i wygaśnięciu wcześniej wydanych tokenów sprawdź ponownie show vacation z wycofywanego profilu — oczekiwany jest brak dostępu. Samo skasowanie plików na laptopie nie odwołuje ich kopii ani delegacji w Google.

Katalog GAM traktuj jak magazyn poświadczeń: szyfrowany dysk, ograniczone uprawnienia, kontrolowana kopia bezpieczeństwa i brak synchronizacji do publicznych repozytoriów. Dla stałej automatyzacji warto rozważyć wariant bez długowiecznych plików kluczy zgodnie z zaleceniami Google dla kluczy kont usług.

Inne możliwości GAM 7 — praktyczne zastosowania w firmie

Autoresponder to tylko jeden przykład. Najwięcej czasu GAM oszczędza wtedy, gdy administrator musi zebrać porównywalne dane z wielu kont lub wykonać powtarzalną, dokładnie określoną zmianę. Poniższe przykłady pokazują, od czego zacząć. Nie uruchomią się wszystkie na profilu przygotowanym wyłącznie do urlopu. Do zadań spoza Gmaila przygotuj osobny profil z właściwą autoryzacją i rolą administratora.

Inwentaryzacja kont i przygotowanie stanowiska nowego pracownika

GAM pozwala zestawić użytkowników, sprawdzić ich podstawowe atrybuty i stan kont, a po nadaniu praw do zapisu także tworzyć konta, aktualizować dane i przypisywać je do jednostek organizacyjnych. Przy zatrudnieniu kilku osób uporządkowany plik wejściowy ogranicza powtarzanie tych samych czynności w panelu. Zacznij od raportu:

gam print users > uzytkownicy.csv

Do podstawowego odczytu użytkowników służy zakres admin.directory.user.readonly w Admin SDK Directory API oraz odpowiednia rola administratora. Tworzenie i zmiana kont wymagają szerszego zakresu do zapisu. Nie przechowuj haseł startowych w ogólnodostępnym CSV. Źródło: GAM — zarządzanie użytkownikami.

Grupy, listy mailingowe i kontrola członkostwa

Przy reorganizacji działu można porównać członków grup, wskazać brakujące osoby i dopiero po zatwierdzeniu listy wprowadzić zmiany. GAM obsługuje grupy i członkostwo, ale ich odczyt, edycja członków oraz zmiana ustawień grupy to odrębne operacje z różnymi wymaganiami.

gam print groups > grupy.csv

Podstawowy raport grup korzysta z Directory API, np. zakresu admin.directory.group.readonly. Odczyt członkostwa i operacje dodatkowe należy dopasować do wybranych opcji polecenia. Zmiany ustawień mogą korzystać również z Groups Settings API. Źródło: GAM — grupy i członkowie.

Raporty logowań i przegląd zdarzeń administracyjnych

Zamiast ręcznie przepisywać zdarzenia z konsoli, można wyeksportować raport za określony okres i przeanalizować go w arkuszu. Przykład odczytu zdarzeń logowania z poprzedniego dnia:

gam report login yesterday > logowania-wczoraj.csv

Raport audytowy wymaga Reports API, zakresu admin.reports.audit.readonly i odpowiednich uprawnień do raportów. Raporty wykorzystania usług mają osobny zakres admin.reports.usage.readonly. Dostępność zdarzeń, opóźnienia i okres przechowywania zależą od usługi oraz edycji Workspace. Pusty raport nie jest dowodem braku incydentu. Źródło: GAM — raporty.

Podpisy e-mail i spójne dane kontaktowe

GAM może odczytać podpis lub ustawić zatwierdzony szablon HTML dla wskazanych pracowników. Przydaje się to po zmianie telefonu, adresu biura albo identyfikacji wizualnej. Dla domyślnego podpisu warto rozpocząć od pojedynczego konta:

gam user pracownik@example.com show signature

Podstawowe operacje na podpisie mieszczą się w obszarze ustawień Gmaila, ale tworzenie adresów nadawcy i inne operacje SendAs mogą wymagać dodatkowych uprawnień. Podpis ustawiony przez API nie oznacza automatycznej kontroli każdego podpisu używanego przez wszystkie programy pocztowe. Sprawdź rezultat w rzeczywiście używanym kliencie. Źródło: GAM — SendAs, podpisy i autoresponder.

Kalendarze i porządkowanie dostępu do spotkań

Administrator może inwentaryzować kalendarze użytkowników, analizować udostępnienia i wykonywać uzgodnione operacje na wydarzeniach. Przykład odczytu listy kalendarzy:

gam user pracownik@example.com show calendars

Wymaga to Calendar API i zakresu odpowiedniego do odczytu listy kalendarzy. Zmiana wydarzenia lub listy uprawnień wymaga innych praw; nie dodawaj pełnego dostępu do Kalendarza tylko dla inwentaryzacji. Przy zmianach wydarzeń uwzględnij powiadomienia wysyłane uczestnikom. Źródła: GAM — kalendarze i zakresy Calendar API.

Dysk Google: inwentaryzacja plików i przegląd udostępnień

GAM pomaga ustalić, jakie pliki posiada użytkownik, a po dobraniu parametrów i uprawnień także przeanalizować ich udostępnienia. Jest to przydatne przed zmianą zespołu lub odejściem pracownika:

gam user pracownik@example.com print filelist > pliki.csv

Podstawowa lista nie jest pełnym audytem wszystkich uprawnień ani kopią zapasową plików. Wymaga Drive API oraz zakresów do wybranych pól i operacji; do samej analizy metadanych rozważ wariant tylko do odczytu metadanych. Pobieranie treści, przenoszenie własności i modyfikacja udostępnień wymagają osobnej oceny praw i ograniczeń, zwłaszcza na dyskach współdzielonych. Źródła: GAM — raporty plików i zakresy Drive API.

Odejście pracownika i zadania masowe z CSV

GAM może być częścią procedury zakończenia współpracy: inwentaryzacji konta, przeglądu grup, przekazania danych i ostatecznego wyłączenia dostępu. Kolejność jest istotna — zawieszenie konta lub odebranie licencji przed przekazaniem danych może utrudnić dalsze czynności. Retencja, archiwizacja i kopia zapasowa wymagają osobnego planu; samo narzędzie administracyjne go nie zastępuje.

Mechanizm gam csv powtarza polecenie dla kolejnych wierszy pliku. Przydaje się np. do odczytu ustawień urlopowych zatwierdzonej listy osób. Plik pracownicy.csv powinien zawierać kolumnę email i wyłącznie sprawdzone adresy:

gam csv pracownicy.csv gam user "~email" show vacation

Najpierw uruchom odczyt dla jednej osoby, potem dla krótkiej listy. Przed operacją zapisującą sprawdź liczbę wierszy, domeny, duplikaty, parametry i sposób odtworzenia poprzedniego stanu. Nie zakładaj, że każde polecenie ma tryb próbny lub że przerwanie zadania wycofa już wykonane zmiany. Składnię przetwarzania opisuje dokumentacja operacji masowych GAM.

Pełne nazwy wymienionych skrótowo zakresów Directory i Reports zaczynają się od https://www.googleapis.com/auth/. Dobór zakresu to tylko jedna część autoryzacji: liczą się również rola administratora, tożsamość użyta w poleceniu, włączone API i polityki organizacji. Nie dopisuj wszystkich zakresów z tej sekcji do profilu autorespondera.

Potrzebujesz uporządkować administrację pocztą firmową?

Opisz środowisko i oczekiwany efekt. Pozwoli to ustalić zakres konfiguracji, dostęp administratorów i sposób weryfikacji zmian.

Skontaktuj się