How to install and set up GAM7 for Google Workspace

Install GAM7 on Windows, macOS or Linux, create its Google Cloud project and authorize it for your domain. Includes the service account key upload error newer Google Cloud organizations hit, and how to allow the upload for the GAM project alone.

GAM7 is the current, merged version of GAM, the open-source command-line tool for Google Workspace administration. Setting it up is one install and three authorizations: a Google Cloud project for GAM, consent from your admin account, and domain-wide delegation for GAM's service account. Most of it is following GAM's own prompts. One step fails by default on newer Google Cloud organizations, and it has its own section below.

The short answer

  1. Install GAM7 from the GAM team's GitHub releases: the .exe installer on Windows, or the install script on macOS and Linux.
  2. Check three settings in the Admin console, and two more on an Education edition.
  3. Run gam create project. GAM creates its Google Cloud project, walks you through making an OAuth client, and asks you to mark two client IDs as trusted.
  4. If GAM reports that service account key uploads are disabled, allow them for the GAM project only, then run gam upload sakey.
  5. Run gam oauth create to authorize your admin account.
  6. Run GAM's check serviceaccount against an ordinary staff account, and authorize domain-wide delegation from the link it prints.
  7. Run gam info domain to confirm.

On Windows the installer also adds a setup script, gam-setup.bat, that runs steps 3, 5 and 6 in order. On macOS and Linux the install script offers the same three steps when it finishes.

Install GAM7

Download GAM7 from the GAM team's GitHub releases page and nowhere else.

Windows. Download gam-7.wx.yz-windows-x86_64.exe, or gam-7.wx.yz-windows-arm64.exe on a Windows 11 ARM device, and run it. The Windows files are near the end of the release's asset list; if the list is collapsed, choose Show all assets. The installer needs administrator rights, installs to C:\GAM7 by default, and adds that folder to the system PATH. If SmartScreen warns about it, check the signature first: GAM's Windows files are code-signed, and the GAM documentation shows how to confirm it (Verifying a GAM7 build).

macOS and Linux. Run the GAM team's install script in a terminal:

bash <(curl -s -S -L https://git.io/gam-install)

It installs GAM7 in $HOME/bin/gam7 and, when it finishes, offers to run the setup steps below for you.

Pick GAM's configuration folder before the first command. GAM keeps its settings and credential files in a configuration folder, .gam in your home folder unless you choose otherwise. The GAM documentation suggests a folder that is not tied to one person's profile, such as C:\GAMConfig, named in a system environment variable called GAMCFGDIR, and a separate working folder for the files GAM writes. Set the variable, open a new command prompt, and initialize GAM with this as its first command:

gam config drive_dir C:\GAMWork save verify

A shared location matters when another Windows account or a scheduled task will run GAM, because by default each account looks in its own profile. On macOS and Linux the same idea applies with folders in your home directory.

Check the Admin console first

These settings decide whether GAM can create its project at all. In the Admin console, under Apps, then Additional Google services:

  • Google Cloud Platform is on for the organizational unit that holds the super admin you will use.
  • In that service's Cloud Resource Manager API settings, Allow users to create projects is checked for the same organizational unit.
  • Access to additional services without individual control is on for everyone. The GAM documentation asks for this so that all of GAM's API scopes are available.

On an Education edition, two more:

  • The super admin is in an organizational unit set to All users are 18 or older, under Account, Account settings, Age based access settings.
  • If you will use GAM's Classroom commands, Users can authorize apps to access their Google Classroom data is checked under Apps, Google Workspace, Classroom, Data access.

If your Google Cloud organization is new, read the key upload section before you start. Google blocks service account key uploads by default on organizations created on or after May 3, 2024, and that includes one created during this setup.

Create the GAM project

On a computer with no browser, such as a server you reach over SSH, run gam config no_browser true save first; GAM then prints links to open on another computer. Otherwise, start here:

gam create project

Before it asks for your super admin address, GAM stops and asks you to mark its project creation app as trusted, because your domain may block apps it has not configured. In the Admin console, under Security, Access and data control, API controls, Manage third-party app access, configure a new app, search for the client ID GAM prints, select GAM Project Creation, and set it to Trusted. The client ID is the same for every GAM installation:

297408095146-fug707qsjv4ikron0hugpevbrjhkmsk7.apps.googleusercontent.com

Press Enter in the terminal, and sign in as the super admin when the browser opens.

GAM then creates the project, turns on the Google APIs it uses, and asks you to make an OAuth client in the Google Cloud console, at a link it prints. Follow its numbered steps: set the audience to Internal, create a client of type Desktop app, and paste the client ID and client secret back into the terminal. Next it asks you to trust a second client ID, the one you just made, on the same Admin console page.

Last, GAM creates its service account, generates a key on your computer, and uploads the key's public certificate to Google. If your organization allows that, GAM reports that the project is created and ready to use. If it does not, you will see the message in the next section.

If the service account key upload is blocked

GAM prints:

Your workspace is configured to disable service account private key uploads.

The cause is a Google Cloud organization policy constraint:

constraints/iam.disableServiceAccountKeyUpload

Google enforces it by default on every Google Cloud organization created on or after May 3, 2024, and possibly on some created between February and April 2024, together with a companion restriction on Google-generated keys. If no one in your district used Google Cloud before GAM, the organization is created during this setup, so both are already on. GAM generates its own key and uploads only the certificate, which is why the upload restriction is the one that stops it.

Do not run gam create project again. It refuses to start while the files from the first run are in place. If you started from the Windows setup script, it offers to try project creation again: answer n, which ends the script, and run the remaining steps yourself. The project and your OAuth client already exist. Only the key is missing.

Get the role that changes organization policies. Overriding a policy, even on one project, takes the Organization Policy Administrator role (roles/orgpolicy.policyAdmin) on the organization. Owning the project is not enough; Google notes that neither the Owner nor the Editor role includes the permission. A super admin can grant the role in the Google Cloud console under IAM & Admin, IAM, with the organization, not the project, selected in the resource picker.

Turn the restriction off for the GAM project only. Two constraints carry it, the original and Google's newer managed form, and the GAM documentation changes both:

iam.disableServiceAccountKeyUpload
iam.managed.disableServiceAccountKeyUpload

In the Google Cloud console:

  1. Open IAM & Admin, Organization policies, and select the GAM project in the resource picker. GAM names it in its message; by default its ID begins gam-project-.
  2. Filter for disableServiceAccountKeyUpload, and both constraints appear.
  3. For each one, choose Manage policy (or Edit policy), then Override parent's policy, Add a rule, set Enforcement to Off, and choose Set policy.
  4. Reload the page and check that the policy now shows as not enforced for the project. When we changed this policy, the console displayed its success message for a change that had not saved.

Wait, then upload the key. Google says organization policy changes can take up to 15 minutes to take effect. Then run:

gam upload sakey

GAM signs you in again, uploads a new key, saves it to its credentials file, and reports that the project is ready. Carry on with authorizing your admin account.

Why one project and not the organization. Google's guidance is to keep these restrictions on and exempt only the projects that need keys, and its best-practice guide describes exactly this per-project override. Switching the policy off for the whole organization would allow keys in every project your district ever creates, which is not what the GAM documentation asks for either.

If your district manages exemptions centrally, Google's page on uploading keys describes a tag-based alternative: a tag set at the organization, changed to not enforced on the projects that need keys, and a conditional policy. It also needs the Tag Administrator and Organization Viewer roles, and the effect is the same: one project exempt, everything else still protected.

If you can avoid the key altogether, do. The GAM documentation itself points out that Google's best practice is not to use service account keys, and it documents keyless setups for GAM on a Google Compute Engine VM and, outside Google Cloud, through Workload Identity Federation. The standard setup on a district workstation or server is the key route above.

Authorize your admin account

gam oauth create

GAM lists the APIs it can use, with a default set already selected. Enter c to continue with the defaults rather than selecting everything: the GAM documentation warns that Google will probably refuse an authorization that asks for every scope. Sign in as your super admin in the browser that opens and allow access. GAM saves the result as oauth2.txt in its configuration folder.

Authorize the service account

GAM's service account is what lets it work inside users' mail, Drive and calendars, and that access is granted in the Admin console as domain-wide delegation. GAM checks it for you and prints what is missing:

gam user staff.member@example.org check serviceaccount

Use an ordinary staff account, not an administrator: GAM's reference describes the target as a non-administrator, and GAM's own setup script asks for a regular user. The first run reports every scope as failed, which is expected. GAM then prints a link that opens the Admin console's domain-wide delegation page with the service account's client ID and scope list filled in, ready to authorize. Delegation can take several minutes to take effect, so wait, then run the same command again until every scope passes.

Confirm it works

gam info domain

It prints your customer ID, primary domain and other details. Saving the first two in GAM's configuration spares it extra API calls and lets you leave the domain off addresses in later commands:

gam config customer_id C01234567 domain example.org timezone local save verify

With timezone local, GAM converts the times it prints from UTC to your own time zone.

Common mistakes

Trusting one client ID instead of two. GAM Project Creation and the OAuth client you made are separate apps, and each has to be marked trusted.

Authorizing as the wrong account. If the browser is signed in to several Google accounts, check which one you are allowing before you click. A private window avoids the question.

Moving the configuration folder later. Credentials are written wherever GAMCFGDIR pointed at the time. Change it afterward and GAM looks in a folder with no credentials in it.

A reauthentication rule on the admin account. If the super admin's organizational unit requires reauthentication for Google Cloud, under Security, Google Cloud session control, the Google Cloud scopes in GAM's authorization are subject to it. The GAM documentation's options are to exempt trusted apps, to leave the Google Cloud scopes out of gam oauth create, or to run it again on that schedule.

Sources