## File: README.md GAM is a command line tool for Google Workspace admins to manage domain and user settings quickly and easily. [](https://github.com/GAM-team/GAM/actions/workflows/build.yml) # Quick Start ## Linux / MacOS Open a terminal and run: ```sh bash <(curl -s -S -L https://gam-shortn.appspot.com/gam-install) ``` this will download GAM, install it and start setup. ## Windows Download the EXE Installer from the [GitHub Releases] page. Run it and you'll be prompted to setup GAM. ## Use your own Python If you'd prefer to install GAM as a Python package you can install with pip: ``` pip install gam7 ``` # Documentation The GAM documentation is hosted in the [GitHub Wiki] # Mailing List / Discussion group The GAM mailing list / discussion group is hosted on [Google Groups]. You can join the list and interact via email, or just post from the web itself. # Chat Room There is a public chat room hosted in Google Chat. [Instructions to join](https://github.com/GAM-team/GAM/wiki/GAM-Public-Chat-Room). # Author GAM is maintained by [Jay (James) Lee](mailto:jay0lee@gmail.com) and [Ross Scroggs](mailto:ross.scroggs@gmail.com). Please direct "how do I?" questions to [Google Groups]. [GAM release]: https://github.com/GAM-team/GAM/releases [GitHub Releases]: https://github.com/GAM-team/GAM/releases [GitHub]: https://github.com/GAM-team/GAM/tree/master [GitHub Wiki]: https://github.com/GAM-team/GAM/wiki/ [Google Groups]: http://groups.google.com/group/google-apps-manager --- ## File: wiki/_Sidebar.md [FAQ](GAM7-FAQ) Update History * [GAM Updates](GamUpdates) Installation * [How to Install GAM7](How-to-Install-GAM7) * [How to Upgrade GAMADV-XTD3 to GAM7](How-to-Upgrade-GAMADV-XTD3-to-GAM7) * [How to Upgrade Legacy GAM to GAM7](How-to-Upgrade-Legacy-GAM-to-GAM7) * [How to Update GAM7](How-to-Update-GAM7) * [Verifying a GAM7 Build is Legitimate and Official](Verifying-a-GAM7-Build-is-Legitimate-and-Official) * [Install GAM as Python Library](Install-GAM-as-Python-Library) * [GAM7 on Chrome OS Devices](GAM7-on-Chrome-OS-Devices) * [GAM7 on Android Devices](GAM7-on-Android-Devices) * [Google Network Addresses](Google-Network-Addresses) * [HTTPS Proxy](HTTPS-Proxy) * [SSL Root CA Certificates](SSL-Root-CA-Certificates) * [How to Uninstall GAM7](How-to-Uninstall-GAM7) Configuration * [Authorization](Authorization) * [GAM Configuration](gam.cfg) * [Multiple Customers and Domains](https://github.com/GAM-team/GAM/wiki/gam.cfg#multiple-customers-and-domains) * [Multiple Users-Projects on One Computer](https://github.com/GAM-team/GAM/wiki/gam.cfg#multiple-users-projects-on-one-computer) * [Running GAM7 securely on a Google Compute Engine](Running-GAM7-securely-on-a-Google-Compute-Engine) * [Using GAM7 with a delegated admin service account](Using-GAM7-with-a-delegated-admin-service-account) * [Using GAM7 with keyless authentication - Workload Identity Federation](Using-GAM7-with-keyless-authentication-Workload-Identity-Federation) * [Using GAM7 with a YubiKey](Using-GAM7-with-a-YubiKey) * [GAM with minimal GCP rights](GAM-with-minimal-GCP-rights) Notes and Information * [Upgrade Benefits](Upgrade-Benefits) * [Questions? Visit the GAM Discussion Forum](https://groups.google.com/forum/#!forum/google-apps-manager) * [GAM Public Chat Room](GAM-Public-Chat-Room) * [GAM Scripts](https://github.com/GAM-team/GAM-Scripts) * [Code Wiki](https://codewiki.google/github.com/gam-team/gam) * [Other Resources](Other-Resources) * [Drive REST API v3](Drive-REST-API-v3) * [BNF Syntax](BNF-Syntax) * [GAM Return Codes](GAM-Return-Codes) * [Python Regular Expressions](Python-Regular-Expressions) * [Rclone](Rclone) Definitions * [Basic Items](Basic-Items) * [List Items](List-Items) * [Drive Items](Drive-Items) Command Processing * [Bulk Processing](Bulk-Processing) * [Command Line Parsing](Command-Line-Parsing) * [Command Logging and Progress](Command-Logging-Progress) * [Command data from Google Docs/Sheets/Storage](Command-Data-From-Google-Docs-Sheets-Storage) * [CSV Special Characters](CSV-Special-Characters) * [CSV Input Filtering](CSV-Input-Filtering) * [CSV Output Filtering](CSV-Output-Filtering) * [Meta Commands and File Redirection](Meta-Commands-and-File-Redirection) * [Permission matches](Permission-Matches) * [Tag Replace](Tag-Replace) * [Todrive](Todrive) Collections * [Collections of ChromeOS Devices](Collections-of-ChromeOS-Devices) * [Collections of Items](Collections-of-Items) * [Collections of Users](Collections-of-Users) * [Drive File Selection](Drive-File-Selection) Client Access * [Addresses](Addresses) * [Administrators](Administrators) * [Alert Center](Alert-Center) * [Aliases](Aliases) * [Calendars](Calendars) * [Calendars - Access](Calendars-Access) * [Calendars - Events](Calendars-Events) * [Calendars - Secondary Calendars with no Owner](No-Owner-Secondary-Calendars) * [Chrome Auto Update Expiration Counts](Chrome-AUE-Counts) * [Chrome Browser Cloud Management](Chrome-Browser-Cloud-Management) * [Chrome Device Counts](Chrome-Device-Counts) * [Chrome Device Needs Attention Counts](Chrome-Needs-Attention-Counts) * [Chrome Installed Apps](Chrome-Installed-Apps) * [Chrome Policies](Chrome-Policies) * [Chrome Printers](Chrome-Printers) * [Chrome Profile Management](Chrome-Profile-Management) * [Chrome Version Counts](Chrome-Version-Counts) * [Chrome Version History](Chrome-Version-History) * [ChromeOS Devices](ChromeOS-Devices) * [Classroom - Courses](Classroom-Courses) * [Classroom - Guardians](Classroom-Guardians) * [Classroom - Invitations](Classroom-Invitations) * [Classroom - Membership](Classroom-Membership) * [Classroom - Student Groups](Classroom-StudentGroups) * [Cloud Channel](Cloud-Channel) * [Cloud Identity Allowlisted Domains](Cloud-Identity-Allowlisted-Domains) * [Cloud Identity Devices](Cloud-Identity-Devices) * [Cloud Identity Groups](Cloud-Identity-Groups) * [Cloud Identity Groups - Membership](Cloud-Identity-Groups-Membership) * [Cloud Identity Policies](Cloud-Identity-Policies) * [Cloud Storage](Cloud-Storage) * [Context Aware Access Levels](Context-Aware-Access-Levels) * [Customer](Customer) * [Domains](Domains) * [Domains - Verification](Domains-Verification) * [Domain People - Contacts & Profiles](Domain-People-Contacts-Profiles) * [Domain Shared Contacts](Domain-SharedContacts) * [Email Audit Monitor](Email-Audit-Monitor) * [Find File Owner](Find-File-Owner) * [Global Address List](Global-Address-List) * [Google Data Transfers](Google-Data-Transfers) * [Groups](Groups) * [Groups - Membership](Groups-Membership) * [Inbound SSO](Inbound-SSO) * [Licenses](Licenses) * [Mobile Devices](Mobile-Devices) * [Organizational Units](Organizational-Units) * [Reports](Reports) * [Reseller](Reseller) * [Resources](Resources) * [Send Email](Send-Email) * [Schemas](Schemas) * [Shared Drives](Shared-Drives) * [Sites](Sites) * [Unmanaged Accounts](Unmanaged-Accounts) * [Users](Users) * [Users - Application Specific Passwords](Users-Application-Specific-Passwords) * [Users - Backup Verification Codes](Users-Backup-Verification-Codes) * [Users - Classroom - Profile](Users-Classroom-Profile) * [Users - Contacts - Delegates](Users-Contacts-Delegates) * [Users - Deprovision](Users-Deprovision) * [Users - Group Membership](Users-Group-Membership) * [Users - Photo](Users-Photo) * [Users - Profile Sharing](Users-Profile-Sharing) * [Users - Signout and Turn off 2-Step Verification](Users-Signout-Turnoff2SV) * [Users - Tokens](Users-Tokens) * [Vault - Takeout](Vault-Takeout) * [Version and Help](Version-and-Help) Special Service Account Access * [Chat Bot Setup and Use](Chat-Bot-Setup-Use) Service Account Access * [Users - Analytics Admin](Users-Analytics-Admin) * [Users - Business Account Management](Users-Business-Account-Management) * [Users - Calendars](Users-Calendars) * [Users - Calendars - Access](Users-Calendars-Access) * [Users - Calendars - Events](Users-Calendars-Events) * [Users - Chat](Users-Chat) * [Users - Classification Labels](Users-Classification-Labels) * [Users - Contacts](Users-People-Contacts-Profiles) * [Users - Data Studio](Users-Data-Studio) * [Users - Drive - File Selection](Drive-File-Selection) * [Users - Drive - Activity/Settings](Users-Drive-Activity-Settings) * [Users - Drive - Cleanup](Users-Drive-Cleanup) * [Users - Drive - Comments](Users-Drive-Comments) * [Users - Drive - Copy/Move](Users-Drive-Copy-Move) * [Users - Drive - Files-Display](Users-Drive-Files-Display) * [Users - Drive - Files-Manage](Users-Drive-Files-Manage) * [Users - Drive - Orphans](Users-Drive-Orphans) * [Users - Drive - Ownership](Users-Drive-Ownership) * [Users - Drive - Permissions](Users-Drive-Permissions) * [Users - Drive - Query](Users-Drive-Query) * [Users - Drive - Revisions](Users-Drive-Revisions) * [Users - Drive - Shortcuts](Users-Drive-Shortcuts) * [Users - Drive - Transfer](Users-Drive-Transfer) * [Users - Forms](Users-Forms) * [Users - Gmail - Client Side Encryption](Users-Gmail-CSE) * [Users - Gmail - Delegates](Users-Gmail-Delegates) * [Users - Gmail - Filters](Users-Gmail-Filters) * [Users - Gmail - Forwarding](Users-Gmail-Forwarding) * [Users - Gmail - Labels](Users-Gmail-Labels) * [Users - Gmail - Messages/Threads](Users-Gmail-Messages-Threads) * [Users - Gmail - Profile](Users-Gmail-Profile) * [Users - Gmail - S/MIME](Users-Gmail-S-MIME) * [Users - Gmail - SendAs/Signature/Vacation](Users-Gmail-Send-As-Signature-Vacation) * [Users - Gmail - Settings](Users-Gmail-Settings) * [Users - Keep - Notes](Users-Keep-Notes) * [Users - Meet](Users-Meet) * [Users - Classroom - Profile](Users-Classroom-Profile) * [Users - People - Contacts & Profiles](Users-People-Contacts-Profiles) * [Users - Profile Photo](Users-Profile-Photo) * [Users - Shared Drives](Users-Shared-Drives) * [Users - Spreadsheets](Users-Spreadsheets) * [Users - Tag Manager](Users-Tag-Manager) * [Users - Tasks](Users-Tasks) * [Users - YouTube](Users-YouTube) * [Users - Web Resources and Sites](Users-Web-Resources-and-Sites) --- ## File: wiki/00scratch.md # Scratch Me Wiki editing these files shouldn't trigger a regular GitHub Action build. # Counter 00010 --- ## File: wiki/Addresses.md # Addresses - [API documentation](#api-documentation) - [Display addresses](#display-addresses) ## API documentation * [Directory API - Domains](https://developers.google.com/admin-sdk/directory/reference/rest/v1/domains) * [Directory API - Groups](https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups) * [Directory API - Resources Calendars](https://developers.google.com/admin-sdk/directory/reference/rest/v1/resources.calendars) * [Directory API - Users](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users) ## Display addresses Produces a three column CSV file (headers Type, Email, Target) that displays all group and user primary email addresses and aliases; resource calendar addresses and domain names. The types are: ``` DomainPrimary, DomainSecondary, DomainAlias Group, GroupAlias, GroupNEAlias Resource SuspendedUser, SuspendedUserAlias, SuspendedUserNEAlias User, UserAlias, UserNEAlias ``` 'NE' is an abbreviation for NonEditable. ``` gam print addresses [todrive *] [domain ] ``` By default, groups and users in all domains in the account are selected; this options allows selection of subsets of groups and users: * `domain ` - Limit groups and users to those in `` --- ## File: wiki/Administrators.md # Administrators - [API documentation](#api-documentation) - [Definitions](#definitions) - [Display administrative privileges](#display-administrative-privileges) - [Manage administrative roles](#manage-administrative-roles) - [Display administrative roles](#display-administrative-roles) - [Create an administrator](#create-an-administrator) - [Delete an administrator](#delete-an-administrator) - [Display administrators](#display-administrators) - [Copy privileges from one role to a new role](#copy-privileges-from-one-role-to-a-new-role) - [Copy roles from one administrator to another](#copy-roles-from-one-administrator-to-another) - [Copy non-system admin roles from a source workspace to a target workspace](#copy-non-system-admin-roles-from-a-source-workspace-to-a-target-workspace) ## API documentation * [About Administrator roles](https://support.google.com/a/answer/33325?ref_topic=4514341) * [Directory API - Privileges](https://developers.google.com/admin-sdk/directory/reference/rest/v1/privileges) * [Directory API - Roles](https://developers.google.com/admin-sdk/directory/reference/rest/v1/roles) * [Directory API - Role Assignments](https://developers.google.com/admin-sdk/directory/reference/rest/v1/roleAssignments) ## Definitions ``` ::= group|user|serviceaccount|unknown ::= "(,)*" ::= (.)+ ::= @ ::= || ::= (json [charset ] ) | (json file [charset ]) | ::= id: ::= /|(/ ::= | ::= ::= "(, ::= ::= ::= ::= id:| ::= id: ::= || ``` ## Display administrative privileges ``` gam print privileges [todrive *] gam show privileges ``` Here is the output from `gam show privileges`; use this to find a specific ``. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Manage administrative roles ``` gam create adminrole [description ] privileges all|all_ou||(select |>)| [csv [todrive *] [formatjson [quotechar ]] (addcsvdata )*] gam update adminrole [name ] [description ] [privileges all|all_ou||(select |>)|] [csv [todrive *] [formatjson [quotechar ]] (addcsvdata )*] gam delete adminrole ``` * `privileges all` - All defined privileges * `privileges all_ou` - All defined privileges than can be scoped to an OU * `privileges ` - A specific list of privileges * `privileges select |>` - A collection of privileges from a flat or CSV file By default, when an admin role is created|update, GAM displays `() created|updated`. * `csv [todrive *] [formatjson [quotechar ]]` - Output the admin roledetails in CSV format. When `csv` is uused, Add additional columns of data from the command line to the output. * `addcsvdata ` ## Display administrative roles ``` gam info adminrole [privileges] [formatjson] ``` * `privileges` - Display privileges associated with role By default, Gam displays the information as an indented list of keys and values. * `formatjson` - Display the fields in JSON format. ``` gam show adminroles|roles [role ] [privileges] [nosystemroles] [formatjson] ``` * `privileges` - Display privileges associated with each role By default, all roles are displayed: * `role ` - Display a specific role. * `nosystemroles` - Display onnly non-system roles. By default, Gam displays the information as an indented list of keys and values. * `formatjson` - Display the fields in JSON format. ``` gam print adminroles|roles [todrive *] [role ] [privileges] [oneitemperrow] [nosystemroles] [formatjson [quotechar ]] ``` * `privileges` - Display privileges associated with each role By default, all privileges for a role are shown on one row as a repeating item. When `oneitemperrow` is specified, each privilege is output on a separate row/line with the other role fields. By default, all roles are displayed: * `role ` - Display a specific role. * `nosystemroles` - Display onnly non-system roles. By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format: * `formatjson` - Display the fields in JSON format. By default, when writing CSV files, Gam uses a quote character of double quote `"`. The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the `formatjson` option, double quotes are used extensively in the data resulting in hard to read/process output. The `quotechar ` option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. `quotechar` defaults to `gam.cfg/csv_output_quote_char`. When uploading CSV files to Google, double quote `"` should be used. ## Create an administrator Add an administrator role to an administrator. ``` gam create admin | customer|(org_unit ) [condition securitygroup|nonsecuritygroup] [expires ] ``` * `customer` - The administrator can manage all organization units * `org_unit ` - The administrator can manage the specified organization unit The option `condition` limits the conditions for delegate admin access. This currently only works with the _GROUPS_EDITOR_ROLE and _GROUPS_READER_ROLE roles. * `condition securitygroup` - limit the delegated admin to managing security groups * `condition nonsecuritygroup` - limit the delegated admin to managing non-security groups The option `expires ` specifies when the role assignment expires; it must be within one year. ## Delete an administrator Remove an administrator role from an administrator. ``` gam delete admin ``` ## Display administrators ``` gam print admins [todrive *] [user|group |] [role ] [types ] [recursive] [condition] [privileges] [oneitemperrow] gam show admins [user|group |] [role ] [types ] [recursive] [condition] [privileges] ``` By default, all administrators and roles are displayed; choose from the following options to limit the display: * `user|group |` - Display assignments to this administrator * `role ` - Display only administrators with this role By default, all admin assignee types are displayed. use `types ` to filter admin assignments by the type of the assignee. By default, assignments to security groups are displayed as a single item; use `recursive` to display assignments to the members of the security groups; the security group membershop is recursively expanded. * `condition` - Display any conditions associated with a role assignment * `privileges` - Display privileges associated with each role assignment By default, all role privileges for an admin are shown on one row as a repeating item. When `oneitemperrow` is specified, each role privilege is output on a separate row/line with the other admin fields. ## Copy privileges from one role to a new role Get privileges for existing role; replace Role Name with actual role name ``` gam redirect csv ./RolePrivileges.csv print adminrole role 'Role Name' privileges oneitemperrow ``` Create a new role with those privileges ``` gam create adminrole "New Role Name" privileges select csvfile RolePrivileges.csv:privilegeName ``` ## Copy roles from one administrator to another Get roles for current admin. ``` gam redirect csv ./CurrentAdminRoles.csv print admins user currentadmin@domain.com ``` Add roles to new admin. ``` gam config csv_input_row_filter "scopeType:regex:CUSTOMER" redirect stdout ./UpdateNewAdminCustomerRoles.txt multiprocess redirect stderr stdout csv CurrentAdminRoles.csv gam create admin newadmin@domain.com "id:~~roleId~~" customer gam config csv_input_row_filter "scopeType:regex:ORG_UNIT" redirect stdout ./UpdateNewAdminOrgUnitRoles.txt multiprocess redirect stderr stdout csv CurrentAdminRoles.csv gam create admin newadmin@domain.com "id:~~roleId~~" org_unit "id:~~orgUnitId~~" ``` ## Copy non-system admin roles from a source workspace to a target workspace In the source workspace do the following: ``` gam redirect csv ./SourceNonSystemRoles.csv print adminroles privileges nosystemroles formatjson quotechar "'" ``` In the target workspacce do the following: ``` gam redirect csv ./TargetNonSystemRoles.csv multiprocess quotechar "'" redirect stderr - multiprocess csv SourceNonSystemRoles.csv quotechar "'" gam create adminrole "~roleName" description "~roleDescription" privileges json "~JSON" csv addcsvdata oldRoleId "~roleId" formatjson ``` --- ## File: wiki/Alert-Center.md # Alert Center - [API documentation](#api-documentation) - [Query documentation](#query-documentation) - [Definitions](#definitions) - [Introduction](#introduction) - [Manage alerts](#manage-alerts) - [Display alerts](#display-alerts) - [Manage alert feedback](#manage-alert-feedback) - [Display alert feedback](#display-alert-feedback) - [Configuring settings](#configuring-settings) ## API documentation * [Alert Center API](https://developers.google.com/admin-sdk/alertcenter/reference/rest/) ## Query documentation * [Query Filters](https://developers.google.com/admin-sdk/alertcenter/guides/query-filters) * [Query Fields](https://developers.google.com/admin-sdk/alertcenter/reference/filter-fields) ## Definitions ``` ::= ::= ::= See: https://developers.google.com/admin-sdk/alertcenter/guides/query-filters ``` ## Introduction For an introduction, start here: https://support.google.com/a/answer/9105393 This API is in beta, most things seem to work although the filter queries don't all work, in particular those that select alertId and feedbackId. To use these commands you must update your gam project and service account authorization. ``` gam update project gam user user@domain.com update serviceaccount ``` ## Manage alerts ``` gam delete alert gam undelete alert ``` ## Display alerts ``` gam info alert [formatjson] gam show alerts [filter ] [orderby createtime [ascending|descending]] [formatjson] ``` By default, Gam displays the information as an indented list of keys and values. * `formatjson` - Display the fields in JSON format. ``` gam print alerts [todrive *] [filter ] [orderby createtime [ascending|descending]] [formatjson [quotechar ]] ``` By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format, * `formatjson` - Display the fields in JSON format. By default, when writing CSV files, Gam uses a quote character of double quote `"`. The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the `formatjson` option, double quotes are used extensively in the data resulting in hard to read/process output. The `quotechar ` option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. `quotechar` defaults to `gam.cfg/csv_output_quote_char`. When uploading CSV files to Google, double quote `"` should be used. ### Eliminate unwanted fields You can use [CSV Print Filtering](CSV-Print-Filtering) to reduce the amount of output. This command will drop all of the data.messages columns. ``` gam config csv_output_header_drop_filter "^data.messages" redirect csv alerts.csv print alerts ``` ## Manage alert feedback ``` gam create alertfeedback not_useful|somewhat_useful|very_useful ``` ## Display alert feedback ``` gam show alertfeedback [alert ] [filter ] [orderby createtime [ascending|descending]] [formatjson] ``` By default, Gam displays feedback for all alerts. * `alert ` - Display feedback for the selected alert * `filter ` - Display feebback for the filtered alerts By default, Gam displays the information as an indented list of keys and values. * `formatjson` - Display the fields in JSON format. ``` gam print alertfeedback [todrive *] [alert ] [filter ] [orderby createtime [ascending|descending]] [formatjson [quotechar ]] ``` By default, Gam displays feedback for all alerts. * `alert ` - Display feedback for the selected alert * `filter ` - Display feebback for the filtered alerts By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format, * `formatjson` - Display the fields in JSON format. By default, when writing CSV files, Gam uses a quote character of double quote `"`. The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the `formatjson` option, double quotes are used extensively in the data resulting in hard to read/process output. The `quotechar ` option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. `quotechar` defaults to `gam.cfg/csv_output_quote_char`. When uploading CSV files to Google, double quote `"` should be used. ## Configuring settings Alert Center can be configured to send notifications to a Google Cloud Pub/Sub topic, but it first requires configuration. * See https://developers.google.com/workspace/admin/alertcenter/guides/notifications for information. Gam can be used to display or modify the settings: ``` gam show alertsettings gam update alertsettings gam clear alertsettings ``` --- ## File: wiki/Aliases.md # Aliases - [API documentation](#api-documentation) - [Query documentation](#query-documentation) - [Python Regular Expressions](Python-Regular-Expressions) Match function - [Definitions](#definitions) - [Create an alias for a target](#create-an-alias-for-a-target) - [Update an alias to point to a new target](#update-an-alias-to-point-to-a-new-target) - [Delete an alias regardless of the target](#delete-an-alias-regardless-of-the-target) - [Remove aliases from a specified target](#remove-aliases-from-a-specified-target) - [Delete all of a user's aliases](#delete-all-of-a-users-aliases) - [Display aliases](#display-aliases) - [Bulk delete aliases](#bulk-delete-aliases) - [Bulk reassign aliases](#bulk-reassign-aliases) - [Determine if an address is a user, user alias, group or group alias](#determine-if-an-address-is-a-user-user-alias-group-or-group-alias) ## API documentation * [Directory API - User Aliases](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users.aliases) * [Directory API - Group Aliases](https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups.aliases) ## Query documentation * [Search Users](https://developers.google.com/admin-sdk/directory/v1/guides/search-users) ## Definitions See [Collections of Items](Collections-of-Items) ``` ::= (.)+ ::= "(,)*" ::= | | ::= @ ::= "(,)*" ::= | | | See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= id: ::= See: https://docs.python.org/3/library/re.html ::= ::= ::= > ``` ## Create an alias for a target ``` gam create alias|aliases user|group|target | [verifynotinvitable] ``` `` are the aliases, `` is the target. The `verifynotinvitable` option causes GAM to verify that the alias email address being created is not that of an unmanaged account; if it is, the command is not performed. ### Example To allow Robert to also receive mail as Bob: ``` gam create alias bob[@yourdomain.com] user robert[@yourdomain.com] ``` ## Update an alias to point to a new target The existing alias is deleted and a new alias is created. ``` gam update alias|aliases user|group|target | [notargetverify] [waitafterdelete ] ``` `` are the aliases, `` is the target. By default, GAM makes additional API calls to verify that the target email address exists before updating the alias; if you know that the target exists, you can suppress the verification with `notargetverify. GAM updates an alias to point to a new target by deleting the alias and then recreates the alias pointing to the new target. Unfortunately, if these commands are executed back-to-back; Google generates the `Update Failed: Duplicate` error. Now, GAM waits 2 seconds between the delete and the insert which seems to eliminate the problem. If the problem persists, use the option `waitafterdelete ` to increase the wait time to a maximum of 10 seconds. ## Delete an alias regardless of the target ``` gam delete alias|aliases [user|group|target] ``` `` are the aliases. ## Remove aliases from a specified target ``` gam remove alias|aliases user|group ``` `` is the target, `` are the aliases. ## Delete all of a user's aliases ``` gam delete aliases ``` ## Display aliases Display a specific alias. ``` gam info alias|aliases ``` Display selected aliases. ``` gam print aliases [todrive *] ([domain|domains ] [(query )|(queries )] [limittoou ]) [user|users ] [group|groups ] [select ] [issuspended ] [isarchived ] [aliasmatchpattern ] [shownoneditable] [nogroups] [nousers] [onerowpertarget] [delimiter ] [suppressnoaliasrows] (addcsvdata )* ``` By default, group and user aliases in all domains in the account are selected; these options allow selection of subsets of aliases: * `domain|domains ` - Limit aliases to those in the domains specified by `` * You can predefine this list with the `print_agu_domains` variable in `gam.cfg`. * `(query )|(queries )` - Print aliases for users/groups that match a query; each query is run against each domain * `limittoou ` - Print aliases for users in the specified `` * `user|users ` - Print aliases for users in `` - Print aliases for users in `` * `group|groups ` - Print aliases for groups in `` - Limit users based on their status * `isarchived ` - Limit users based on their status * `aliasmatchpattern ` - Print aliases that match a pattern * `nogroups` - Print only user aliases * `nousers` - Print only group aliases By default, the CSV output has three columns: `Alias,Target,TargetType`; if a target has multiple aliases, there will be multiple rows, one per alias. Use `shownoneditable` to list non-editable alias email addresses; these are typically outside of the account's primary domain or subdomains. This adds the column `NonEditableAlias`. Specifying `onerowpertarget` changes the three columns to: `Target,TargetType,Aliases`; all aliases for the target are listed in the `Aliases` column. If `shownoneditable` is specified, there will be a fourth column `NonEditableAliases` with a list of non-editable aliases. By default, the aliases in a list are separated by the `csv_output_field_delimiter' from `gam.cfg`. * `delimiter ` - Separate aliases in a list with `` Specifying both `onerowpertarget` and `suppressnoaliasrows` causes GAM to not display any targets that have no aliases. Add additional columns of data from the command line to the output * `addcsvdata ` When multiple domains are specified and a query/queries are specified, an API call is made for each domain/query combination. ``` $ gam print aliases domains school.org,students.school.org queries "'email:admin*','email:test*'" Getting all Users that match query (domain=school.org, query="email:admin*"), may take some time on a large Google Workspace Account... Got 3 Users: admin@school.org - admindirector@school.org Getting all Users that match query (domain=school.org, query="email:test*"), may take some time on a large Google Workspace Account... Got 20 Users: testusera@school.org - testuserx@school.org Getting all Users that match query (domain=students.school.org, query="email:admin*"), may take some time on a large Google Workspace Account... Got 1 User: admin@students.school.org - admin@students.school.org Getting all Users that match query (domain=students.school.org, query="email:test*"), may take some time on a large Google Workspace Account... Got 1 User: testuser1@students.school.org - testuser1@students.school.org Alias,Target,TargetType ... ``` ## Bulk delete aliases You can bulk delete aliases by using `gam print aliases` to list the aliases to be deleted and then deleting them. ``` gam redirect csv ./Aliases.csv print aliases domain olddomain.com onerowpertarget suppressnoaliasrows gam redirect csv ./Aliases.csv print aliases aliasmatchpattern ".*@olddomain.com" onerowpertarget suppressnoaliasrows gam redirect stdout ./DeleteAliases.txt multiprocess redirect stderr stdout csv ./Aliases.csv gam remove aliases "~Target" "~TargetType" "~Aliases" ``` ## Bulk reassign aliases You can bulk reassign aliases as follows. Make a CSV file ReassignAliases.csv with two columns: OldTarget,NewTarget. From this CSV file, all of the aliases for the users in the OldTarget column will be listed with an additional column showing the NewTarget. ``` gam redirect stdout ./GetAliases.txt multiprocess redirect stderr stdout redirect csv ./ReassignAliases.csv gam print aliases user "~OldTarget" addcsvdata NewTarget "~NewTarget" ``` If an OldTarget's aliases are to be reassigned to more than the one NewTarget, edit ReassignAliases.csv and make changes as required. ``` gam redirect stdout ./ReassignAliases.txt multiprocess redirect stderr stdout csv ReassignAliases.csv gam update alias "~Alias" user "~NewTarget" ``` ## Determine if an address is a user, user alias, group or group alias ``` gam whatis [noinfo] [noinvitablecheck] ``` The first line of output is: `: ` There is additional output based on ``: * User - `gam info user ` * Group - `gam info group ` * User Alias - `gam info alias ` * Group Alias - `gam info alias ` * User Invitation - `gam info userinvitation ` The `noinfo` argument suppresses the additional output. The `noinvitablecheck` argument suppresses the user invitation check to avoid exceeding quota limits when checking a large number of addresses. The return code is set based on ``: * User - 20 * User Alias - 21 * Group - 22 * Group Alias - 23 * User Invitation - 24 * Unknown - 59 --- ## File: wiki/Authorization.md # Authorization - [Introduction](#introduction) - [Headless computers and Cloud Shells](#headless-computers-and-cloud-shells) - [API documentation](#api-documentation) - [Python Regular Expressions](Python-Regular-Expressions) - [Definitions](#definitions) - [Manage Projects](#manage-projects) - [Authorize a user to create projects](#authorize-a-user-to-create-projects) - [Authorize Service Account Key Uploads](#authorize-service-account-key-uploads) - [Authorize GAM to create projects](#authorize-gam-to-create-projects) - [Create a new GCP project folder](#create-a-new-gcp-project-folder) - [Create a new project for GAM authorization](#create-a-new-project-for-gam-authorization) - [Use an existing project for GAM authorization](#use-an-existing-project-for-gam-authorization) - [Update an existing project for GAM authorization](#update-an-existing-project-for-gam-authorization) - [Delete an existing project for GAM authorization](#delete-an-existing-project-for-gam-authorization) - [Display projects](#display-projects) - [Manage Client credentials](#manage-client-credentials) - [Create Client credentials](#create-client-credentials) - [Refresh Client credentials](#refresh-client-credentials) - [Update Client credentials](#update-client-credentials) - [Delete Client credentials](#delete-client-credentials) - [Verify Client credentials](#verify-client-credentials) - [Export Client credentials](#export-client-credentials) - [Manage Service Accounts](#manage-service-accounts) - [Add Service Accounts to projects](#add-service-accounts-to-projects) - [Delete Service Accounts from projects](#delete-service-accounts-from-projects) - [Display Service Accounts for projects](#display-service-accounts-for-projects) - [Manage Service Account keys](#manage-service-account-keys) - [Create a new Service Account key](#create-a-new-service-account-key) - [Update an existing Service Account key](#update-an-existing-service-account-key) - [Replace all existing Service Account keys](#replace-all-existing-service-account-keys) - [Delete Service Account keys](#delete-service-account-keys) - [Display Service Account keys](#display-service-account-keys) - [Upload a Service Account key to a service account without a valid private key](#upload-a-service-account-key-to-a-service-account-without-a-valid-private-key) - [Manage Service Account access](#manage-service-account-access) - [Full Service Account access](#full-service-account-access) - [Selective Service Account access](#selective-service-account-access) - [Configure Limited access](#configure-limited-access) - [Limited Client access](#limited-client-access) - [No Client access](#no-client-access) - [Limited Service Account access](#limited-service-account-access) - [todrive Service Account access](#todrive-service-account-access) - [No Service Account access possible](#no-service-account-access-possible) - [Test Client and Service Account access on your computer](#test-client-and-service-account-access-on-your-computer) - [Install GAM on the limited users computer](#install-gam-on-the-limited-users-computer) - [Test Client and Service Account access on the non-administrator computer](#test-client-and-service-account-access-on-the-non-administrator-computer) - [Unselect limited section on your computer.](#unselect-limited-section-on-your-computer) - [Delete old versions of GAM from Configured Apps](#delete-old-versions-of-gam-from-configured-apps) ## Introduction GAM requires authorization to perform tasks on your domain; the tasks break down into two categories: * Client - Manipulate objects in the domain; the Client acts on its own behalf to perform the tasks. Examples: add a user, update a group, delete a class, share a printer. * Service Account - Manipulate objects that belong to users; the Service Account acts on behalf of the user to perform the tasks. Examples: view user files, calendars. You create projects that define these authorizations. Verify the following steps: * See https://support.google.com/a/answer/9197205?hl=en * Access the admin console and go to Apps -> Additional Google Services * Look for the service "Google Cloud Platform", click it * Expand "Service status" * Select the OU in the left that contains the super admin you'll be using * Make sure that "Service status" is ON * If groups are used to authenticate access, make sure the super admin is in one of the groups * Collapse "Service status" * Expand "Cloud Resource Manager API settings" * Select the OU in the left that contains the super admin you'll be using * Make sure that "Allow users to create projects" is checked Verify that all scopes are available: * Access the admin console and go to Apps -> Additional Google Services * If this line is present: `Access to additional services without individual control for all organizational units is turned Off` * Click "CHANGE" * Select "ON for everyone" * Click "SAVE" If you run a Google Workspace Education SKU, verify that Classroom API is enabled if required. * Access the admin console and go to Apps -> Google Workspace - Classroom * Expand "Data access" * Check "Users can authorize apps to access their Google Classroom data." * Click "SAVE" If you run a Google Workspace Education SKU, verify that the super admin you'll be using is in an OU where "All users are 18 or older". * Access the admin console and go to Accounts -> Account settings * Expand "Age based access settings" * Select the OU containing the super admin * Choose "All users are 18 or older" * Click "SAVE" Based on your domain policies, you may have to mark GAM as a trusted app. These steps are performed after a project is created. * Access the admin console and go to Security -> Access and data control -> API controls * Click Manage third-party app access * Click Configure new app * Paste client_id value from client_secrets.json in Search for app * Click Search * Click the line referencing GAM * Keep the default scope All in domain.com (all users) or select an org unit that includes your GAM admin * Click Continue * Click Trusted: App can request access to all Google data * Click Continue * Click Finish * Press Confirm if Confirm parental consent pops up Verify whether the super admin you'll be using is in an OU where reauthentication is required. * Access the admin console and go to Security -> Overview * Scroll down and open Google Cloud session control section * Select the OU containing the super admin * If Require reauthentication is selected, you'll need either: * uncheck Google Cloud Storage and any other GCP APIs that you selected on `gam oauth create` (reauth is only necessary for GCP APIs) * enable "Exempt Trusted apps" * rerun `gam oauth create` at whatever frequency is specified Additional steps may be required if errors are encountered. * [Authorize a user to create projects](#authorize-a-user-to-create-projects) * [Authorize Service Account Key Uploads](#authorize-service-account-key-uploads) * [Authorize GAM to create projects](#authorize-gam-to-create-projects) ## Headless computers and Cloud Shells With many thanks to Jay, `gam oauth create` now uses a new client access authentication flow as required by Google for headless computers/cloud shells; this is required as of February 28, 2022. * See: https://developers.googleblog.com/2022/02/making-oauth-flows-safer.html * OAuth out-of-band (oob) flow will be deprecated ## API documentation * https://cloud.google.com/resource-manager/docs/creating-managing-organization#adding_an_organization_administrator * https://cloud.google.com/service-usage/docs/reference/rest * https://cloud.google.com/resource-manager/reference/rest/v3/projects/create * https://cloud.google.com/resource-manager/reference/rest/v3/projects/list * https://cloud.google.com/resource-manager/reference/rest/v3/projects/getIamPolicy * https://cloud.google.com/iam/docs/understanding-service-accounts * https://developers.google.com/identity/protocols/oauth2 * https://developers.google.com/identity/protocols/googlescopes * https://developers.google.com/admin-sdk/directory/v1/guides/delegation * https://support.google.com/a/answer/7281227?hl=en#zippy=%2Cmanage-access-to-apps-trusted-limited-or-blocked ## Definitions ``` ::= ::= "(,)*" ::= Must match this Python Regular Expression: [a-z][a-z0-9-]{4,28}[a-z0-9] ::= "(,)*" ::= current | gam | | (filter ) | (select | | ) See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= Must match this Python Regular Expression: [a-zA-Z0-9 '"!-]{4,30} ::= Must match this Python Regular Expression: [a-z][a-z0-9-]{4,28}[a-z0-9] ::= Maximum of 100 characters ::= Maximum of 256 characters ::= @.iam.gserviceaccount.com ::= ::= ``` ## Manage Projects In all of the project commands, the Google Workspace admin/GCP project manager `` can be omitted; you will be prompted for a value. You must enter a full address, i.e., user@domain.com; you will be required to authenticate. For `print|show projects`, you can eliminate the password prompt and authentication requirement by specifying the super admin emailaddress used in `gam oauth create`. ``` gam print projects admin admin@domain.com ``` ## Authorize a user to create projects If you try to create a project and get an error saying that the user you specified is not authorized to create projects, perform these steps and then retry the create project command. * Login as an existing super admin at console.cloud.google.com * In the upper left click the three lines to the left of Google Cloud and select IAM & Admin * Under IAM & Admin select IAM * Click in the box to the right of Google Cloud * Click the three dots at the right and select IAM/Permissions * Now you should be at "Permissions for organization ..." * Click on Grant Access * Enter the new admin address in Principals * Click in the Select a role box * Type project creator in the Filter box * Click Project Creator * Click Save ## Authorize Service Account Key Uploads *IMPORTANT:* Google best practice is to NOT use service account keys. Rather than overriding Google's default policy please consider [Running GAM7 securely on a Google Compute Engine](https://github.com/GAM-team/GAM/wiki/Running-GAM7-securely-on-a-Google-Compute-Engine) (if running in Google Cloud) or [Workload Identity Federation](https://github.com/GAM-team/GAM/wiki/Using-GAM7-with-keyless-authentication-Workload-Identity-Federation) (if running outside Google Cloud) so that service account keys are not necessary. If you try to create a project and get an error saying that Constraint `constraints/iam.disableServiceAccountKeyUpload violated for service account projects/gam-project-xxxxx`, perform these steps and then you should be able to authorize and use your project. * Login as an existing super admin at console.cloud.google.com * In the upper left click the three lines to the left of Google Cloud and select IAM & Admin * Under IAM & Admin select IAM * Click in the box to the right of Google Cloud * Click the three dots at the right and select IAM/Permissions * Now you should be at "Permissions for organization ..." * Click on Grant Access * Enter the new admin address in Principals * Click in the Select a role box * Type orgpolicy.policyAdmin in the Filter box * Click Organization Policy Administrator * Click Save * In the upper left click the three lines to the left of Google Cloud and select IAM & Admin * Under IAM & Admin select IAM * Click in the box to the right of Google Cloud * Click the three dots at the right and select Manage Resources * Click the three dots at the end of the line for the GAM project just created * Click Settings * Click Organization Policies in the left column * Now you should be at "Policies for Gam Project" * Click in the Filter box * Enter iam.managed.disableServiceAccountKeyUpload * Click the three dots at the end of the Disable service account key upload/iam.managed.disableServiceAccountKeyUpload line * Choose Edit policy * Click Override parent's policy * Click Add A Rule * Select Enforcement/Off * Click Done * Click Set Policy * Click the three dots at the end of the Disable Service Account Key Upload/iam.disableServiceAccountKeyUpload line * Choose Edit policy * Click Override parent's policy * Click Add A Rule * Select Enforcement/Off * Click Done * Click Set Policy Wait a couple of minutes for the policy updates to complete and then do the following to upload the service account key: ``` gam upload sakey [admin ] ``` ## Authorize GAM to create projects If you try to create a project and get an error saying "This app has been blocked on your domain for either being insecure or non-edutational"; you'll have to mark the GAM Project Creation app as trusted. Perform these steps and then retry the create project command. * Access the admin console and go to Security -> Access and data control -> API controls * Click **Manage third-party app access** * Click Add app and select **OAuth App Name Or Client ID** * Paste 297408095146-fug707qsjv4ikron0hugpevbrjhkmsk7.apps.googleusercontent.com * Click Search * Click Select at right end of line referencing GAM Project Creation * Check box to the left of the line with GAM Project Creation client ID * Click Select * Keep the default scope domain.com (all users) or select an org unit that includes your GAM admin * Click Next/Continue * Click Trusted: App can request access to all Google data * Click Next/Continue * Click Finish/Confirm ## Create a new GCP project folder This folder can be used in a subsequent `gam create project parent ` command. ``` gam create gcpfolder gam create gcpfolder [admin ``` ## Create a new project for GAM authorization Create a new project to create and download two files: `client_secrets.json` for the Client and `oauth2service.json` for the Service Account. On-screen instructions lead you through the process. An existing project, `GAM Project Creation`, is used to create your GAM project. The initial instructions tell you how to enable this project as a trusted app as your workspace may not allow untrusted third-party apps. This is recommended but not mandatory unless your workspace has "Google Cloud" service restricted: * https://support.google.com/a/answer/7281227?hl=en#zippy=%2Crestrict-or-unrestrict-google-services If it is restricted and you complete this step it may take an hour or so to take full affect and allow you to approve GAM project creation. The final instructions tell you how to enable your new GAM project as a trusted app as your workspace may not allow untrusted third-party apps. You can skip these steps if you know that untrusted third-party apps are allowed. ### Default values * `` - "GAM" * `` - "gam-project-a1b2c" where "a1b2c" are randomly generated * `` - "GAM Project" * `` - `` * `` - `` * `` - `` ### Basic Create Create a project with default values for the project and service account. ``` gam create project [] [] ``` * `` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address * `` - A new Google project ID; if omitted, a default value will be used ### Advanced Create Create a project with user-specified values for the project and service account. ``` gam create project [admin ] [project ] [appname ] [supportemail ] [projectname ] [parent ] [saname ] [sadisplayname ] [sadescription ] [(algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)| (localkeysize 1024|2048|4096 [validityhours ])| (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber )| nokey} ``` * `admin ` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address * `appname ` - Application name, defaults to `GAM` * `supportemail ` - Administrator to contact about GAM authentication, defaults to `admin ` * `project ` - A new Google project ID; if omitted, a default value will be used * `projectname ` - Google project name, defaults to "GAM Project" * `parent ` - A Resource Manager folder name * `saname ` - Service account name; combined with `` to form `` * `sadisplayname ` - Service account display name * `sadescription ` - Service account description You can optionally specify the type of service account key with `algorithm|localkeysize|yubikey`: [Manage Service Account keys](#manage-service-account-keys) Use `nokey` if you do not want a service account key created for the project. ## Use an existing project for GAM authorization To use the same GAM project on multiple computers, see: [GAM Configuration](Multiple-Computers) Use an existing project to create and download two files: `client_secrets.json` for the Client and `oauth2service.json` for the Service Account. ### Default values * `` - `` * `` - `` * `` - `` ### Basic Use Use an existing uninitialized/uncredentialed project and configure it to be a GAM project; this typically used when the GCP administrators have created a basic project because project creation is not available for most users. See Jay's notes about how to do this: https://github.com/GAM-team/GAM/wiki/GAM-with-minimal-GCP-rights ``` gam use project [] [project ] ``` * `` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address * `` - An existing Google project ID; if omitted, you will be prompted for the ID ### Advanced Use Use an existing project with user-specified values for the service account. If the project is already a GAM project you must use `saname ` as the existing service account information can not be re-downloaded. ``` gam use project [admin ] [project ] [appname ] [supportemail ] [saname ] [sadisplayname ] [sadescription ] [(algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)| (localkeysize 1024|2048|4096 [validityhours ])| (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber )] ``` * `admin ` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address * `project ` - An existing Google project ID; if omitted, you will be prompted for the ID * `saname ` - Service account name; combined with `` to form `` * `sadisplayname ` - Service account display name * `sadescription ` - Service account description You can optionally specify the type of service account key with `algorithm|localkeysize|yubikey`: [Manage Service Account keys](#manage-service-account-keys) ## Update an existing project for GAM authorization This command is used when GAM has added new capabilities that require additional APIs to be added to your project. ``` gam update project [[admin] ] [] ``` * `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address Use these options to select projects. * `current` - The project referenced in `client_secrets.json`; this is the default * `gam` - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with `gam-project-` * `` - A Google API project ID * `filter ` - A filter to select projects accessible by the administrator; see the API documentation ## Delete an existing project for GAM authorization ``` gam delete project [[admin] ] [] ``` * `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address Use these options to select projects. * `current` - The project referenced in `client_secrets.json`; this is the default * `gam` - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with `gam-project-` * `` - A Google API project ID * `filter ` - A filter to select projects accessible by the administrator; see the API documentation ## Display projects Display the current Project ID. ``` gam info currentprojectid ``` Display Google API projects as an indented list of keys and values. ``` gam show projects [[admin] ] [all|] [states all|active|deleterequested] [showiampolicies 0|1|3] ``` * `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address Use these options to select projects. * `all` - All projects accessible by the administrator * `current` - The project referenced in `client_secrets.json` * `gam` - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with `gam-project-`; this is the default * `` - A Google API project ID * `filter ` - A filter to select projects accessible by the administrator; see the API documentation * `states all|active|deleterequested` - Limit display to projects based on state; the default is `active` Use the `showiampolicies 0|1|3` option to display IAM policy information for the project. Display Google API projects as columns of fields. ``` gam print projects [[admin] ] [all|] [todrive *] [states all|active|deleterequested] [showiampolicies 0|1|3 [onememberperrow]] [delimiter ]] [[formatjson [quotechar ]] ``` * `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address Use these options to select projects. * `all` - All projects accessible by the administrator * `current` - The project referenced in `client_secrets.json` * `gam` - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with `gam-project-`; this is the default * `` - A Google API project ID * `filter ` - A filter to select projects accessible by the administrator; see the API documentation * `states all|active|deleterequested` - Limit display to projects based on state; the default is `active` Use the `showiampolicies 0|1|3` option to display IAM policy information for the project. Each role in the policy will be displayed on a separate row; by default, all members will be shown on that row. By default, the members are separated by the `csv_output_field_delimiter` from `gam.cfg`. * `delimiter ` - Separate list items with `` Use the `onememberperrow` option to show separate rows for each role/member combination. By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format, * `formatjson` - Display the fields in JSON format. By default, when writing CSV files, Gam uses a quote character of double quote `"`. The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the `formatjson` option, double quotes are used extensively in the data resulting in hard to read/process output. The `quotechar ` option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. `quotechar` defaults to `gam.cfg/csv_output_quote_char`. When uploading CSV files to Google, double quote `"` should be used. ## Manage Client credentials ## Create Client credentials ``` gam oauth|oauth2 create|request [] gam oauth|oauth2 create|request [admin ] [scopes ] ``` * `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address * `scopes ` - A set of specific scopes; if omitted, you will be prompted to select your desired scopes. You select a list of scopes, GAM uses a browser to get final authorization from Google for these scopes and writes the credentials into the file oauth2.txt. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Update Client credentials ``` gam oauth update [] gam oauth update [admin ] ``` * `` - A Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address Read API scopes from any version of `oauth2.txt` and select a list of APIs; GAM uses a browser to get final authorization from Google for these APIs and writes the credentials into the file `oauth2.txt`. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` If you have multiple sections in `gam.cfg` that reference different `oauth2.txt` files, perform an update on each section: ``` gam select aaa oauth update gam select bbb oauth update ... ``` ## Refresh Client credentials Refresh the expiration time in `oauth2.txt`. ``` gam oauth refresh ``` If you have multiple sections in `gam.cfg` that reference different `oauth2.txt` files, perform a refresh on each section: ``` gam select aaa oauth refresh gam select bbb oauth refresh ... ``` ## Delete Client credentials ``` gam oauth|oauth2 delete|revoke ``` Revoke the credentials in the file `oauth2.txt` and then delete the file. ## Verify Client credentials ``` ::= ::= gam oauth|oauth2 info|verify [showsecret] [accesstoken idtoken ] [showdetails] ``` The Client Secret is not shown by default, user `showsecret` to have it displayed. These options are used for debugging: `accesstoken idtoken showdetails`. ## Export Client credentials Export `oauth2.txt` in JSON form. ``` gam oauth|oauth2 export [] ``` * If `` is omitted, the JSON data is written to `oauth2.txt`. * If `` is `-`, the JSON data is written to stdout. ## Manage Service Accounts In all of the service account commands, the Google Workspace admin/GCP project manager `` can be omitted; you will be prompted for a value. You must enter a full address, i.e., user@domain.com; you will be required to enter the password. ## Add Service Accounts to projects You can add additional service accounts to a project and assign it specific access APIs. This command creates a new `oauth2service.json` file; it will not overwrite an existing file so you must rename the existing file or define a new section in `gam.cfg` that references a different `oauth2service_json` or `config_dir`. ### Default values * `` - "gam-svcacct-abc-def-jki" where "abc-def-ghi" are randomly generated * `` - `` * `` - `` ``` gam create|add svcacct [[admin] ] [] [saname ] [sadisplayname ] [sadescription ] [(algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)| (localkeysize 1024|2048|4096 [validityhours ])| (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber )] ``` * `` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address Use these options to select projects. * `current` - The project referenced in `client_secrets.json`; this is the default * `gam` - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with `gam-project-` * `` - A Google API project ID * `filter ` - A filter to select projects accessible by the administrator; see the API documentation Use these options to select user-specified values.. * `saname ` - Service account name; combined with `` to form `` * `sadisplayname ` - Service account display name * `sadescription ` - Service account description You can optionally specify the type of service account key with `algorithm|localkeysize|yubikey`: [Manage Service Account keys](#manage-service-account-keys) After adding an additional service account, you can select specific access APIs for it. [Selective Service Account access](#selective-service-account-access) ## Delete Service Accounts from projects ``` gam delete svcacct [[admin] ] [] (saemail )|(saname )|(sauniqueid ) ``` * `` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address Use these options to select projects. * `current` - The project referenced in `client_secrets.json`; this is the default * `gam` - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with `gam-project-` * `` - A Google API project ID * `filter ` - A filter to select projects accessible by the administrator; see the API documentation ## Display Service Accounts for projects Display Service Accounts as an indented list of keys and values. ``` gam show svcaccts [[admin] ] [all|] [showsakeys all|system|user] ``` Display Service Accounts as columns of fields. ``` gam print svcaccts [[admin] ] [all|] [showsakeys all|system|user] [todrive *] [formatjson [quotechar ]] ``` * `` - Google Workspace admin/GCP project manager; if omitted, you will be prompted for the address Use these options to select projects. * `all` - All projects accessible by the administrator; this is the default * `current` - The project referenced in `client_secrets.json` * `gam` - Projects accessible by the administrator that were created by Gam, i.e, their project ID begins with `gam-project-` * `` - A Google API project ID * `filter ` - A filter to select projects accessible by the administrator; see the API documentation By default, no Service Account key information is displayed, use the following options to display keys. * `showsakeys all` - Display system and user keys; this is the default when keys are displayed * `showsakeys system` - Display system keys * `showsakeys user` - Display user keys ## Manage Service Account keys The `oauth2service.json` file contains a private key that is used to authenticate Service Account access. This private key will be referred to as the `current` private key. Each Service Account in a project typically has one private key but it can have multiple keys; this might be the case if you have several users with Gam access where they will all access the same Service Account but with different keys. You will distribute different `oauth2service.json` files to each user, each with its own private key. There are several methods for generating private keys: * `algorithm KEY_ALG_RSA_1024` - Google generates a 1024 bit key; not recommended * `algorithm KEY_ALG_RSA_2048` - Google generates a 2048 bit key * `localkeysize 1024` - Gam generates a 1024 bit key; this is not recommended * `localkeysize 2048` - Gam generates a 2048 bit key; this is the default * `localkeysize 4096` - Gam generates a 4096 bit key * `yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber )]` - [Using GAM7 with a YubiKey](Using-GAM7-with-a-YubiKey) When `localkeysize` is specified, the optional argument `validityhours ` sets the length of time during which the key will be valid and should be used when the [GCP constraints/iam.serviceAccountKeyExpiryHours organization policy](https://cloud.google.com/resource-manager/docs/organization-policy/restricting-service-accounts#limit_key_expiry) is in use. Note that in order to account for system clock skew, GAM sets the key to be valid two minutes earlier than the current system time and thus it will also expire two minutes earlier. Here are some sample values: ``` 1 hour 8 hours 24 hours ( 1 day) 168 hours ( 7 days) 336 hours (14 days) 720 hours (30 days) 1440 hours (60 days) 2160 hours (90 days) ``` ## Create a new Service Account key Create a new Service Account private key; all existing private keys remain valid. The `oauth2service.json` file is updated with the new private key. This command requires that the current Service Account private key is valid, if you get the following error: ``` ERROR: 401: authError - Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project. ``` see: [Upload a Service Account key to a service account without a valid private key](#upload-a-service-account-key-to-a-service-account-without-a-valid-private-key) Keep a good record of where each Service Account key is used as the keys themselves do not record this information. The two forms of the command are equivalent; the second form is used by Legacy GAM. ``` gam create sakey (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)| (localkeysize 1024|2048|4096 [validityhours ])| (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber ) gam rotate sakey retain_existing (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)| (localkeysize 1024|2048|4096 [validityhours ])| (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber ) ``` To distribute `oauth2service.json` files with unique private keys perform the following steps: ``` copy oauth2service.json to oauth2service.save repeat gam create sakeys retain_existing distribute updated oauth2service.json file copy oauth2service.save to oauth2service.json ``` ## Update an existing Service Account key Revoke the current Service Account key and replace it with a new private key; all other private keys remain valid. The `oauth2service.json` file is updated with the new private key. If you had previously distributed this `oauth2service.json` file to other users, you must redistribute the updated file as the private key in the distributed copies has been revoked. This command requires that the current Service Account private key is valid, if you get the following error: ``` ERROR: 401: authError - Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project. ``` see: [Upload a Service Account key to a service account without a valid private key](#upload-a-service-account-key-to-a-service-account-without-a-valid-private-key) The two forms of the command are equivalent; the second form is used by Legacy GAM. ``` gam update sakey (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)| (localkeysize 1024|2048|4096 [validityhours ])| (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber ) gam rotate sakey replace_current (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)| (localkeysize 1024|2048|4096 [validityhours ])| (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber ) ``` ## Replace all existing Service Account keys Create a new Service Account private key; all existing private keys are revoked. The `oauth2service.json` file is updated with the new private key. If you had previously distributed any `oauth2service.json` file to other users, you must redistribute the updated file as the private key in the distributed copies has been revoked. This command can be used if your Service Account keys have been compromised; all existing private keys are revoked. This command requires that the current Service Account private key is valid, if you get the following error: ``` ERROR: 401: authError - Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project. ``` see: [Upload a Service Account key to a service account without a valid private key](#upload-a-service-account-key-to-a-service-account-without-a-valid-private-key) The two forms of the command are equivalent; the second form is used by Legacy GAM. ``` gam replace sakeys (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)| (localkeysize 1024|2048|4096 [validityhours ])| (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber ) gam rotate sakeys retain_none (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)| (localkeysize 1024|2048|4096 [validityhours ])| (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber ) ``` ## Delete Service Account keys You can delete Service Accounts keys thus revoking access for that key. Generally, you will delete a service account key for a distributed copy of an `oauth2service.json` file to disable that user's service account access. This command requires that the current Service Account private key is valid, if you get the following error: ``` ERROR: 401: authError - Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project. ``` see: [Upload a Service Account key to a service account without a valid private key](#upload-a-service-account-key-to-a-service-account-without-a-valid-private-key) You can disable your current Service Account key if you specify the `doit` argument. This is your acknowledgement that you will have to manually create a new Service Account key in the Developer's Console or upload a new key with the `gam upload sakey` command. ``` gam delete sakeys + [doit] ``` ## Display Service Account keys There are system keys and user keys; user keys are what Gam uses; GCP uses system keys. Display Service Account keys as an indented list of keys and values. ``` gam show sakeys [all|system|user] ``` * `all` - Display system and user keys; this is the default * `system` - Display system keys * `user` - Display user keys The private key currently being used in `oauth2service.json` will be marked as `usedToAuthenticateThisRequest: True`. ## Upload a Service Account key to a service account without a valid private key There are two cases where you will use this command: * Your workspace is configured to disable service account private key uploads and you are creating a project. * All of your service account keys have been deleted, either manually or with the `gam delete sakeys` command. The `oauth2service.json` file is updated with the new private key. If you had previously distributed any `oauth2service.json` file to other users, you must redistribute the updated file with the new key. ``` gam upload sakey [admin ] (algorithm KEY_ALG_RSA_1024|KEY_ALG_RSA_2048)| (localkeysize 1024|2048|4096 [validityhours ])| (yubikey yubikey_pin yubikey_slot AUTHENTICATION|SIGNATURE yubikey_serialnumber ) ``` ## Manage Service Account access ## Full Service Account access Verify that the Service Account credentials have been authorized. If they have not, you will be given instructions as to how to perform the authorization. By default, the following scopes are verified: ``` https://mail.google.com/ https://sites.google.com/feeds https://www.googleapis.com/auth/analytics.readonly https://www.googleapis.com/auth/apps.alerts https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/chat.delete https://www.googleapis.com/auth/chat.memberships https://www.googleapis.com/auth/chat.messages https://www.googleapis.com/auth/chat.spaces https://www.googleapis.com/auth/classroom.announcements https://www.googleapis.com/auth/classroom.coursework.students https://www.googleapis.com/auth/classroom.courseworkmaterials https://www.googleapis.com/auth/classroom.profile.emails https://www.googleapis.com/auth/classroom.profile.photos https://www.googleapis.com/auth/classroom.rosters https://www.googleapis.com/auth/classroom.topics https://www.googleapis.com/auth/cloud-identity https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/contacts https://www.googleapis.com/auth/contacts.other.readonly https://www.googleapis.com/auth/datastudio https://www.googleapis.com/auth/directory.readonly https://www.googleapis.com/auth/documents https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/drive.activity https://www.googleapis.com/auth/drive.admin.labels https://www.googleapis.com/auth/drive.labels https://www.googleapis.com/auth/gmail.modify https://www.googleapis.com/auth/gmail.settings.basic https://www.googleapis.com/auth/gmail.settings.sharing https://www.googleapis.com/auth/keep https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/tasks https://www.googleapis.com/auth/userinfo.profile ``` This scope is verified when `user_service_account_access_only = true` in `gam.cfg`. ``` https://www.googleapis.com/auth/apps.groups.migration ``` Verify/enable service account access for the default list of APIs. The two forms of the command are equivalent. ``` gam check svcacct (scope|scopes )* gam check serviceaccount (scope|scopes )* ``` * `` - Typically `user `, a non-Google Workspace administrator. * `scopes ` - Verify/enable service account access for a set of specific scopes rather than the default list. ## Selective Service Account access Verify/enable service account access for a selected list of APIs rather than the default list. The two forms of the command are equivalent. If `scopes ` is not specified, you will be prompted to select a list of scopes. ``` gam update svcacct (scope|scopes )* gam update serviceaccount (scope|scopes )* ``` * `` - Typically `user `, a non-Google Workspace administrator. * `scopes ` - Verify/enable service account access for a set of specific scopes rather than selecting the scopes. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Configure Limited access You can configure GAM to allow users limited access to your domain via GAM. You can limit both client and service account access. You can repeat these steps if you want to configure multiple limited users; substitute a unique value for `limited` in each of the steps. In the Admin console, define a new Admin role with the desired privileges, assign it to the limited user and indicate whether it is for all Org Units or a specific Org Unit. On your computer, perform these initial steps: Make a subdirectory `limited` under the directory specified in `gam.cfg config_dir` Create a new section at the end of your `gam.cfg` file. ``` [limited] config_dir = limited ``` Copy `client_secrets.json` to the `limited` subdirectory Select the `limited` section ``` gam select limited save ``` ## Limited Client access Perform these steps to allow limited client access: Configure `todrive` to allow uploading of files to the limited user's Google Drive. ``` gam config todrive_user limited@domain.com save ``` If it is not possible to allow the limited user any service account access (this is not common), perform the following command so that the user can upload files with `todrive` using client access. ``` gam config todrive_clientaccess true save ``` Authorize the desired client access APIs; this will create `oauth2.txt`. If it is not possible to allow the limited user any service account access, login as the limited user; you must have assigned Admin API Privileges to the limited user in the Admin console under Admin roles, If the limited user will have service account access, login as a Google admin. ``` gam oauth create ``` ## No Client access Perform these steps to allow no client access: Configure `todrive` to allow uploading of files to the limited user's Google Drive. ``` gam config todrive_user limited@domain.com todrive_clientaccess false save ``` Configure for service account access only. ``` gam config user_service_account_access_only true save ``` Make a `oauth2.txt` file in the `limited` subdirectory with a single line as follows: ``` {} ``` This will prevent the limited user from having any client access. ## Limited Service Account access Perform these steps: Create a a new service account in your project that will be used for the limited user; this will create `oauth2service.json`. ``` gam add svcacct saname "gam-limited" sadisplayname "GAM Limited" ``` Authorize the desired APIs; this will update `oauth2service.json` with the list of authorized APIs. Follow the directions to authorize the APIs; remember, you will login to the Admin console as a current Google administrator. ``` gam user limited@domain.com update serviceaccount ``` If you disable a scope that was previously enabled, all of the remaining APIs will pass. However, you should still go to the Admin console and update the client so that only the APIs you've enabled are authorized. ## todrive Service Account access If the limited user is going to use `todrive`, authorize these APIs: ``` Drive API - todrive Gmail API - Send Messages - including todrive Sheets API - todrive ``` These APIs are only used to process `todrive`, they do not grant access to other user's files/sheets. If the limited user is allowed access to other user's files/sheets, authorize these APIs: ``` Drive API (supports readonly) Sheets API (supports readonly) ``` ## No Service Account access possible If it is not possible to allow the limited user any service account access (this is not common), perform these steps: Make a `oauth2service.json` file in the `limited` subdirectory with a single line as follows: ``` {} ``` ## Test Client and Service Account access on your computer Issue various Gam commands to verify that the limited user has only the desired access. Repeat previous steps as required. Once testing is complete, perform the following step to prevent the limited user from creating/updating `oauth2.txt`. Edit the `client_secrets.json` file in the `limited` subdirectory to have a single line as follows: ``` {} ``` ## Install GAM on the limited users computer Install GAM on the limited user's computer; it can be a different OS than your computer; if asked by the installer, indicate: * that you do not want to set up a project * that you are performing an update Make the necessary directories. * Make the GAM configuration directory; this can be different than on your computer. * Set the GAMCFGDIR environment variable to point to the GAM configuration directory. * Make a subdirectory `gamcache` under the GAM configuration directory. * Make a subdirectory `limited` under the GAM configuration directory. Copy `gam.cfg` from your computer to the GAM configuration directory on the limited user's computer. Edit `gam.cfg` * Remove any sections other than `[DEFAULT]` and `[limited]` * If the GAM configuration directory on the limited users computer is different than that on yours, update these values in the [DEFAULT] section: * cache_dir * config_dir * You may also want to update the GAM downloads directory: * drive_dir Copy `client_secrets.json`, `oauth2.txt` and `oauth2service.json` from the `limited` subdirectory on your computer to the `limited` subdirectory on the limited user's computer. ## Test Client and Service Account access on the non-administrator computer Issue various Gam commands to verify that the limited user has only the desired access. If you need to make changes, make them on your computer and then re-copy `client_secrets.json`, `oauth2.txt` and `oauth2service.json` to the limited user's computer. ## Unselect limited section on your computer. Once you have finished setting up authorizations for the limited user, you need to reset your `gam.cfg` to point to your default section or another section. ``` gam select default save gam select
save ``` ## Delete old versions of GAM from Configured Apps ``` In the Admin console, go to Security/Access and Data Control/API Controls/MANAGE APP ACCESS Click Download list Select Comma-separated values (.csv) Click Download Click Download CSV The CSV file will be named: owl_apps.csv Remove the rows of apps you want to keep. Edit the column Access to UNCONFIGURED for those rows you want to remove. Click Bulk update list Click Attach CSV file Locate owl_apps.csv Click Upload Click Upload Click Confirm ``` --- ## File: wiki/Basic-Items.md # Basic Items - [Primitives](#primitives) - [Items built from primitives](#items-built-from-primitives) - [Named items](#named-items) - [List Items](List-Items) ## Primitives ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Items built from primitives ``` ::= | ::= [m|k|b] ::= .../ ::= ::= ::= ::= ::= ::= ::= ::= -- | (+|-)(d|w|y) | never| today ::= --(|T): | (+|-)(m|h|d|w|y) | never| now|today