DOCSEARCHbyAlgolia
Submit Docs

GAM

repository·main·Indexed 26 days ago

https://github.com/gam-team/gam

A free, open-source command-line tool built with Python 3 for Google Workspace administrators to efficiently manage domain and user settings. GAM7 is a rewrite and extension of Legacy GAM that maintains backwards compatibility with Legacy GAM syntax. It requires an API project, administrator authorization, and a special service account for full functionality.

Tokens
212.8K
Snippets
485
Records
1.3K
Agent score
88%

What's inside GAM

  1. Overview of GAM7

    main
    GAM7 is a free, open-source command-line tool built with Python 3 designed for Google Workspace (formerly G Suite) Administrators. It allows for quick and easy management of domain and user settings. GAM7 is a rewrite/extension of Legacy GAM and maintains backwards compatibility with Legacy GAM syntax.

  2. Requirements for using GAM7

    main

    To use GAM7 effectively, ensure your environment meets the following requirements:

    1. Google Workspace Edition: Requires a paid, Education, or Non-profit edition of Google Workspace. Note that G Suite Legacy Free Edition has limited API support and may not support all GAM commands.
    2. API Project: An API project is required to identify your GAM7 installation to Google and manage API quotas.
    3. Administrator Authorization: You must authorize GAM7 to act as a Google Workspace Administrator to perform management tasks (e.g., adding users, modifying group settings, pulling domain reports).
    4. Special Service Account: A special service account is required to authorize GAM7 to act on behalf of users for modifying user-specific data (e.g., Drive files, Calendars, Gmail messages, and signatures).

  3. Understand GAM configuration file structure

    main

    GAM uses a configuration file named gam.cfg to store environment variables and signal file locations. This file allows you to manage multiple clients, domains, or users on a single machine.

    Key directory concepts used by GAM:

    • GamCfgDir: Location of gam.cfg (Default: ~/.gam)
    • GamConfigDir: Location of client_secrets.json, oauth2.txt, oauth2service.json, and extra_args.txt (Default: ~/.gam)
    • GamCacheDir: Google API cache files (Default: ~/.gam/gamcache)
    • GamDriveDir: Directory for files downloaded via gam user <User> get drivefile <DriveFileID> (Default: ~/Downloads)

    gam.cfg must be a plain text file.

  4. Understand GAM Authorization Types

    main

    GAM uses two distinct types of authorization to perform tasks on your Google Workspace domain:

    • Client: Acts on its own behalf to manipulate domain objects. Examples include adding a user, updating a group, deleting a class, or sharing a printer.
    • Service Account: Acts on behalf of a user to manipulate objects belonging to that user. Examples include viewing user files or calendars.

    These authorizations are defined through Google Cloud Projects.

  5. Understand User Attribute types

    main

    GAM distinguishes between two types of user attributes:

    1. <UserBasicAttribute>: Attributes that have a single instance per user (e.g., email, firstname, lastname, suspend).
    2. <UserMultiAttribute>: Attributes that can have multiple instances (e.g., address, im, organization, phone, website).

    Important rules for Multi-Attributes:

    • Primary vs Secondary: For attributes like address, im, organization, phone, and website, you can use the keywords primary or notprimary to indicate the status of the instance.
    • Full Replacement: When specifying a <UserMultiAttribute>, you must provide all instances. You cannot insert or remove a single specific instance via standard attribute setting.
    • Clearing Attributes: To remove all instances of a multi-attribute, use the <UserClearAttribute> syntax (e.g., address clear).

  6. Filter CSV input rows in GAM

    main

    When using gam csv commands, you can filter which rows from your input file are processed by configuring specific keys in gam.cfg.

    There are two primary configuration keys for this:

    • csv_input_row_filter: A list or JSON dictionary used to include specific rows based on column values.
    • csv_input_row_drop_filter: A list or JSON dictionary used to exclude specific rows based on column values.

    These filters can be used alone or in conjunction with the matchfield|skipfield <FieldName> <REMatchPattern> command options.

  7. Enable Google Keep API for GAM

    main

    To use Google Keep commands, you must enable the 'Keep API' in your Google Cloud project and update your service account authorization.

    Run the following commands to update your project and service account:

    gam update project
gam user user@domain.com update serviceaccount

  8. Enable People API for GAM contact management

    main

    GAM uses the Google People API (rather than the Contacts API) to manage user contacts. To use contact management commands, you must add the People API to your Google Cloud project and authorize the following scopes:

    For Client Access:

    • People API (supports readonly)
    • People Directory API - read only

    For Service Account Access:

    • https://www.googleapis.com/auth/userinfo.profile (OAuth2 API)
    • https://www.googleapis.com/auth/contacts (People API supports readonly)
    • https://www.googleapis.com/auth/contacts.other.readonly (People API - Other Contacts - read only)
    • https://www.googleapis.com/auth/directory.readonly (People Directory API - read only)

    To apply these changes, use the following workflow:

    1. Update your project: gam update project
    2. Re-authorize: gam oauth create
    3. If using a service account, update the user: gam user <user@domain.com> update serviceaccount
    gam update project
gam oauth create
gam user user@domain.com update serviceaccount

  9. Enable GAM7 Client Access (OAuth2 Scopes)

    main

    To authorize GAM7 to act on behalf of users via OAuth2, use the gam oauth create command.

    1. Delete existing oauth2.txt: The new format is different from legacy GAM. Run rm -f $GAMCFGDIR/oauth2.txt first.
    2. Select Scopes: Run gam oauth create and select the required scopes from the interactive list. You can use r for read-only or a for action-only access.
    3. Authenticate: Follow the browser prompts. If using a remote machine, paste the 'Unable to connect' URL provided after clicking 'Allow' in your local browser.

  10. Configure GAM7 for AWS using Workload Identity Federation

    main

    Follow these steps to allow an AWS identity to authenticate GAM7 keylessly:

    1. Create an AWS Provider in your pool:
      gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \
    --workload-identity-pool="POOL_ID" \
    --account-id="YOUR_AWS_ACCOUNT_ID" \
    --location="global"
    2. Allow Impersonation: Grant the AWS role permission to impersonate your service account:
      gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role="roles/iam.workloadIdentityUser" \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/arn:aws:sts::YOUR_AWS_ACCOUNT:assumed-role/YOUR_ROLE_NAME"
    3. Generate Credential Config: Create a JSON file for the environment (use --enable-imdsv2 for IMDSv2):
      gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --aws \
    --output-file=FILEPATH.json
    4. Set Environment Variables: Export the path to the generated JSON:
      export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credential-configurations.json"
    5. Update oauth2service.json: Set "key_type": "signjwt" in your oauth2service.json file.
    6. Verify: Run gam version and gam info user to confirm.

  11. Configure GAM7 directories and environment variables on Windows

    main

    To upgrade to GAM7 on Windows, you must establish a configuration directory and a working directory. It is recommended to use non-user-specific locations.

    1. Create Directories: Create a directory for configuration (e.g., C:\GAMConfig) and a directory for working data (e.g., C:\GAMWork).
    2. Set System Path: Add the GAM7 installation directory (e.g., C:\GAM7) to your system Path environment variable. If a legacy GAM path exists, delete it.
    3. Set GAMCFGDIR: Create a new system environment variable named GAMCFGDIR and set its value to your configuration directory (e.g., C:\GAMConfig).
    4. Set OLDGAMPATH: Set an environment variable OLDGAMPATH pointing to your existing legacy GAM directory to facilitate the migration.

  12. Handle contact group names with spaces using special quoting

    main

    Because contact group names can contain spaces, GAM's list parser may incorrectly split a single name into multiple items if you only use standard shell quotes. To ensure a name with spaces is treated as a single item in a list, wrap the name in single quotes inside your double quotes.

    Incorrect: gam info contactgroup "Sales Contacts" (splits into Sales and Contacts) Correct: gam info contactgroup "'Sales Contacts'" (treats Sales Contacts as one item)

    For multiple groups with spaces, use a comma-separated list of single-quoted names inside double quotes: gam info contactgroup "'Sales Contacts','Tech Contacts'"