@@ -224,6 +224,8 @@ COUNT_N_EXCEEDS_MAX_TO_PROCESS_M = 'Count {0} exceeds maximum to {1} {2}'
CORRUPT_FILE='Corrupt file'
COULD_NOT_FIND_ANY_YUBIKEY='Could not find any YubiKey\n'
COULD_NOT_FIND_YUBIKEY_WITH_SERIAL='Could not find YubiKey with serial number {0}\n'
CREATE_DELEGATE_NOTIFY_MESSAGE='#user# has granted you #delegate# access to read, delete and send mail on their behalf.'
CREATE_DELEGATE_NOTIFY_SUBJECT='#user# mail delegation to #delegate#'
CREATE_USER_NOTIFY_MESSAGE='Hello #givenname# #familyname#,\n\nYou have a new account at #domain#\nAccount details:\nUsername: #user#\nPassword: #password#\nStart using your new account by signing in at\nhttps://www.google.com/accounts/AccountChooser?Email=#user#&continue=https://workspace.google.com/dashboard\n'
CREATE_USER_NOTIFY_SUBJECT='Welcome to #domain#'
CSV_DATA_ALREADY_SAVED='CSV data already saved'
@@ -353,6 +355,7 @@ LESS_THAN_1_SECOND = 'less than 1 second'
@@ -43,7 +43,7 @@ Even if you're not going to use GAM as a Chat Bot, you have to configure a Chat
* Uncheck "Build this Chat app as a Workspace add-on."
* Enter an App name and Description of your choosing.
* For the Avatar URL you can use `https://dummyimage.com/384x256/4d4d4d/0011ff.png&text=+GAM` or a public URL to an image of your own choosing.
* In Functionality, uncheck both "Receive 1:1 messages" and "Join spaces and group conversations"
* Inƒ Functionality, uncheck both "Receive 1:1 messages" and "Join spaces and group conversations" if present
* In Connection settings, choose "Cloud Pub/Sub" and enter `projects/<ProjectID>/topics/no-topic` for the Topic Name. Replace `<ProjectID>` with your GAM project ID. GAM doesn't yet listen to pub/sub so this option is not used.
* In Visibility, uncheck "Make this Chat app available to specific people and groups in Domain Workspace".
* [Chrome Management API - Count Active Devices](https://developers.google.com/chrome/management/reference/rest/v1/customers.reports/countActiveDevices)
* [Chrome Management API - Count Devices per Boot Type](https://developers.google.com/chrome/management/reference/rest/v1/customers.reports/countDevicesPerBootType)
* [Chrome Management API - Count Devices per Release Channel](https://developers.google.com/chrome/management/reference/rest/v1/customers.reports/countDevicesPerReleaseChannel)
## Notes
To use these features you must add the `Chrome Management API` to your project and authorize
the appropriate scope: `Chrome Management API - read only`.
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 <Character>` 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.
As of GAM version `6.67.00`, the new API function `batchChangeStatus` replaces the old API function `action`; ChromeOS devices are now processed in batches.
ChromeOS devices are now processed in batches.
The batch size defaults to 10, the `actionbatchsize <Integer>` option can be used to set a batch size between 10 and 250.
As deprovisioning ChromeOS devices is not reversible, you must enter `acknowledge_device_touch_requirement`
@@ -711,7 +711,9 @@ To retrieve the count with `showitemcountonly`:
By default, the `print course-counts` command displays participant counts about all courses.
To get participant counts for a specific set of courses, use the following option; it can be repeated to select multiple courses.
* `(course|class <CourseID>)*` - Display courses with the specified `<CourseID>`.
To get participant counts for courses based on their having a particular participant, use the following options. Both options can be specified.
* `teacher <UserItem>` - Display courses with the specified teacher.
* `student <UserItem>` - Display courses with the specified student.
To get participant counts for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
By default, all course states are selected.
* `states <CourseStateList>` - Display courses with any of the specified states.
By default, all count values are displayed, use `mincount <Integer>` to limit the display to those counts
greater that or equal to the specified `<Integer>`.
By default, Gam displays the counts 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 <Character>` 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.
### Example
For teachers in all active courses, print the number of classes for which they are a participant.
```
gam print coursecounts teachers states active
```
For teachers in all active courses, print the number of classes (if it is >= 5) for which they are a participant.
```
gam print coursecounts teachers states active mincount 5
* [Reseller API - Customers](https://developers.google.com/admin-sdk/reseller/v1/reference/customers)
* [Reseller API - Subscriptions](https://developers.google.com/admin-sdk/reseller/v1/reference/subscriptions)
## Notes
Updated handling of `seats` option in `gam create|update resoldsubscription` to properly assign
the API fields `numberOfSeats` and `maximumNumberOfSeats`.
Prior to version 6.50.00, this is how the `seats <NumberOfSeats> <MaximumNumberOfSeats>` option was processed:
* Plan name `ANNUAL_MONTHLY_PAY` or `ANNUAL_YEARLY_PAY`
*`seats <NumberOfSeats>` - `<NumberOfSeats>` was properly passed to the API
*`seats <NumberOfSeats> <MaximumNumberOfSeats>` - `<NumberOfSeats>` was properly passed to the API; `<MaximumNumberOfSeats>` was passed to the API which ignored it
* Plan name `FLEXIBLE` or `TRIAL`
*`seats <NumberOfSeats>` - `<NumberOfSeats>` was improperly passed to the API; an API error was generated
*`seats <NumberOfSeats> <MaximumNumberOfSeats>` - `<MaximumNumberOfSeats>` was properly passed to the API; `<NumberOfSeats>` was passed to the API which ignored it
Now, you can still use the above option which has been corrected or you can specify `seats <Number>` which will be properly passed in the correct form to the API based on plan name.
## Manage Multiple Domains
Thanks to Duncan Isaksen-Loxton for a script to help manage multiple domains.
for /f "delims=" %a in ('gam print oushareddrives showitemcountonly') do set count=%a
```
## Manage Shared Drive access
@@ -643,15 +659,23 @@ When deleting permissions from JSON data, permissions with role `owner` true are
These commands are used to transfer ACLs from one Shared Drive to another.
* `copy` - Copy all ACLs from the source Shared Drive to the target Shared Drive. The role of an existing ACL in the target Shared Drive will never be reduced.
* `sync` - Add/delete/update ACLs in the target Shared Drive to match those in the source Shared Drive.
* `<UserTypeEntity>` - Not Specified
* All Shared Drives must be in the same workspace as the admin in `oauth2.txt`.
* `<UserTypeEntity>` - Specified
* `adminaccess|asadmin` specified - All Shared Drives must be in the same workspace as `<UserTypeEntity>`.
* `adminaccess|asadmin` not specified - Shared Drives can be in separate workspaces if `<UserTypeEntity>` in a manager of all of them.
```
gam [<UserTypeEntity>] copy shareddriveacls <SharedDriveEntity> to <SharedDriveEntity>
@@ -659,8 +683,14 @@ When `excludepermissionsfromdomains <DomainNameList>` is specified, any ACL that
When `includepermissionsfromdomains <DomainNameList>` is specified, only ACLs that reference a domain in `<DomainNameList>` will be copied.
When `mappermissionsemail <EmailAddress> <EmailAddress>` is specifed, an ACL that references the first `<EmailAddress>` will be modified
to reference the second `<EmailAddress>` when copied; the original ACL is not modified. The option can be repeated if multiple email addresses are to be mapped.
Bulk permission email address mapping can be specified with `mappermissionsemailfile <CSVFileInput> endcsv`.
`<CSVFileInput>` must include these columns: `sourceEmail` and `destinationEmail`.
When `mappermissionsdomain <DomainName> <DomainName>` is specifed, any ACL that references the first `<DomainName>` will be modified
to reference the second `<DonainName>` when copied; the original ACL is not modified. The option can be repeated if multiple domain names are to me mapped.
to reference the second `<DomainName>` when copied; the original ACL is not modified. The option can be repeated if multiple domain names are to be mapped.
A groupchat space can be upgraded to a space by specifying `type space` and `displayname <String>`.
The `restricted|audience` options can not be combined with options `displayname,type,description,guidelines,history`.
You can manage permissions for chat spaces with the following options that are available with Developer Preview.
[managemembersandgroups managers|members]
[modifyspacedetails managers|members]
[togglehistory managers|members]
[useatmentionall managers|members]
[manageapps managers|members]
[managewebhooks managers|members]
[postmessages managers|members]
[replymessages managers|members]
By default, Gam displays the information about the created chatspace as an indented list of keys and values.
*`formatjson` - Display the fields in JSON format.
@@ -432,11 +422,20 @@ When using the `formatjson` option, double quotes are used extensively in the da
The `quotechar <Character>` 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.
@@ -226,8 +237,6 @@ When a file appears more that once in the copy, the first time the file is proce
If it is processed again (because of multiple parents within the source folder structure), a shortcut is created that points to the first copy.
### Shortcuts
In previous versions, copying shortcuts caused an error because shortcuts can't be copied, they must be re-created.
If a shortcut in the source structure points to a file/folder that is not in the source structure:
* The shortcut is re-created to point to the original file/folder.
@@ -263,7 +272,6 @@ When a folder is copied, its permissions are not copied; these options control c
of the form `option [<Boolean>]`; if `<Boolean>` is omitted, `true` is assumed.
When copied, a target folder inherits the permissions of its parent folder; these options control whether/how GAM copies the existing source folder permissions.
The default values of options introduced in version 6.14.00 are set to match the behavior of earlier versions.
When `mergewithparent` is `true`:
*`copymergewithparentfolderpermissions false` - The permissions of the source top folder are not not copied to the target folder; this is the default action.
@@ -316,8 +324,14 @@ When `excludepermissionsfromdomains <DomainNameList>` is specified, any ACL that
When `includepermissionsfromdomains <DomainNameList>` is specified, only ACLs that reference a domain in `<DomainNameList>` will be copied.
When `mappermissionsemail <EmailAddress> <EmailAddress>` is specifed, an ACL that references the first `<EmailAddress>` will be modified
to reference the second `<EmailAddress>` when copied; the original ACL is not modified. The option can be repeated if multiple email addresses are to be mapped.
Bulk permission email address mapping can be specified with `mappermissionsemailfile <CSVFileInput> endcsv`.
`<CSVFileInput>` must include these columns: `sourceEmail` and `destinationEmail`.
When `mappermissionsdomain <DomainName> <DomainName>` is specified, any ACL that references the first `<DomainName>` will be modified
to reference the second `<DomainName>` when copied; the original ACL is not modified. The option can be repeated if multiple domain names are to me mapped.
to reference the second `<DomainName>` when copied; the original ACL is not modified. The option can be repeated if multiple domain names are to be mapped.
When copying an ACL that references a non Google account, an error is generated unless an email is sent to the account;
by default, no email notifications are sent. The `sendemailifrequired` options instructs GAM to send an email notification in this case.
@@ -352,6 +366,8 @@ Linux/MacOS
fileId=$(gam user user@domain.com copy drivefile <DriveFileEntity> ... returnidonly)
### Copy content of a Shared Drive to another Shared Drive
Suppose you have a source Shared Drive called 0AC_1AB with multiple files and folders, and want to copy all of its content to the target Shared Drive 0AE_9ZX.
Suppose you have a source Shared Drive with ID 0AC_1AB with multiple files and folders, and want to copy all of its content to the target Shared Drive with ID 0AE_9ZX.
The following command will copy the content, files and folders inside the source drive recursively, and put them in the target drive.
### Copy content of a source Shared Drive to a target Shared Drive with parallel Processing
Suppose you have a source Shared Drive with ID 0AC_1AB with multiple files and folders, and want to copy all of its content to the target Shared Drive with ID 0AE_9ZX.
for /f "delims=" %a in ('gam user user@domain.com create drivefile mimetype gfolder teamdriveparentid 0AE-9ZX drivefilename "New Folder Name" returnidonly') do set taregtFolderId=%a
@@ -621,8 +683,14 @@ When `excludepermissionsfromdomains <DomainNameList>` is specified, any ACL that
When `includepermissionsfromdomains <DomainNameList>` is specified, only ACLs that reference a domain in `<DomainNameList>` will be copied.
When `mappermissionsemail <EmailAddress> <EmailAddress>` is specifed, an ACL that references the first `<EmailAddress>` will be modified
to reference the second `<EmailAddress>` when copied; the original ACL is not modified. The option can be repeated if multiple email addresses are to be mapped.
Bulk permission email address mapping can ge specified with `mappermissionsemailfile <CSVFileInput> endcsv`.
`<CSVFileInput>` must include these columns: `sourceEmail` and `destinationEmail`.
When `mappermissionsdomain <DomainName> <DomainName>` is specified, any ACL that references the first `<DomainName>` will be modified
to reference the second `<DomainName>` when copied; the original ACL is not modified. The option can be repeated if multiple domain names are to me mapped.
to reference the second `<DomainName>` when copied; the original ACL is not modified. The option can be repeated if multiple domain names are to be mapped.
When copying an ACL that references a non Google account, an error is generated unless an email is sent to the account;
by default, no email notifications are sent. The `sendemailifrequired` options instructs GAM to send an email notification in this case.
@@ -639,8 +707,14 @@ When `excludepermissionsfromdomains <DomainNameList>` is specified, any ACL that
When `includepermissionsfromdomains <DomainNameList>` is specified, any ACLs that references a domain not in `<DomainNameList>` will be removed.
When `mappermissionsemail <EmailAddress> <EmailAddress>` is specifed, an ACL that references the first `<EmailAddress>` will be removed;
a new ACL with the same properties referencing the second `<EmailAddess>` will be created. The option can be repeated if multiple domain names are to be mapped.
Bulk email address mapping can ge specified with `mappermissionsemailfile <CSVFileInput> endcsv`.
`<CSVFileInput>` must include these columns: `sourceEmail` and `destinationEmail`.
When `mappermissionsdomain <DomainName> <DomainName>` is specified, any ACL that references the first `<DomainName>` will be removed;
a new ACL with the same properties referencing the second `<DomainName>` will be created. The option can be repeated if multiple domain names are to me mapped.
a new ACL with the same properties referencing the second `<DomainName>` will be created. The option can be repeated if multiple domain names are to be mapped.
When creating an ACL that references a non Google account, an error is generated unless an email is sent to the account;
by default, no email notifications are sent. The `sendemailifrequired` options instructs GAM to send an email notification in this case.
Starting in version 6.27.02, you can get Drive label information without an extra API call
if you know the `<ClassificationLabelID>`s. Add `labelinfo` to your `fields` list and use `includelabels <ClassificationLabelIDList>`
to specify the Drive labels.
You can get Drive label information without an extra API call if you know the `<ClassificationLabelID>`s.
Add `labelinfo` to your `fields` list and use `includelabels <ClassificationLabelIDList>` to specify the Drive labels.
```
gam user user@domain.com show fileinfo <DriveFileEntity> fields id,name,mimetype,labelinfo includelabels "mRoha85IbwCRl490E00xGLvBsSbkwIiuZ6PRNNEbbFcb"
```
@@ -504,7 +503,7 @@ gam user user@domain.com show fileinfo <DriveFileEntity> fields id,name,mimetype
The `stripcrsfromname` option strips nulls, carriage returns and linefeeds from drive file names.
Use this option if you discover filenames containing these special characters; it is not common.
Starting in version 6.80.10, the option `followshortcuts [<Boolean>]` that when true and `<DriveFileEntity` is a shortcut,
The option `followshortcuts [<Boolean>]` that when true and `<DriveFileEntity` is a shortcut,
causes GAM to display information about the target of the shortcut rather than the shortcut itself.
By default, Gam displays the information as an indented list of keys and values.
@@ -540,7 +539,7 @@ Use this option if you discover filenames containing these special characters; i
By default, when printing file paths, all paths for a file are displayed on the same row; use `oneitemperrow` to
have each file path displayed on a separate row.
Starting in version 6.80.10, the option `followshortcuts [<Boolean>]` that when true and `<DriveFileEntity` is a shortcut,
The option `followshortcuts [<Boolean>]` that when true and `<DriveFileEntity` is a shortcut,
causes GAM to display path information for the target of the shortcut rather than the shortcut itself.
## Select files for Display file counts, list, tree
@@ -1197,7 +1196,7 @@ These options can be used instead of the query options to select a specific fold
* `select <DriveFileEntity>` - All files in the selected folder and below are shown.
* To select the root folder of My Drive, use its `<DriveFolderID>` obtained by `gam user <UserItem> show fileinfo root id`
* `select <IDfrom Above>`
* Starting in version 6.22.14, you can select the root folder of My Drive with `rootid`.
* You can select the root folder of My Drive with `rootid`.
* `select rootid`
* `selectsubquery <QueryDriveFile>` - Only the files in the selected folder that match the query are shown.
@@ -1669,7 +1668,7 @@ There is a final row detailing files and folders in the trash; it is omitted if
* `depth` - Always -1
* `path` - Trash
GAM version `6.71.17` added the `depth` column that can be used to filter the depth of the folders displayed.
The `depth` column that can be used to filter the depth of the folders displayed.
Depth `-1` is the top level folder, depth `0` are its immediate children, depth `2` are the children of depth `1` and so forth.
For example to limit the display to the top folder and its immediate children, use `config csv_output_row_filter depth:count<1`.
@@ -39,11 +57,61 @@ The `convertalias` option causes GAM to make an extra API call per user in `<Use
to convert aliases to primary email addresses. If you know that all of the email addresses
in `<UserEntity>` are primary, you can omit `convertalias` and avoid the extra API calls.
## Delegation Notification
When creating a delegate, you can send a message to the delegate.
```
[notify [<Boolean>]
[subject <String>]
[from <EmailAaddress>] [mailbox <EmailAddress>]
[replyto <EmailAddress>]
[<NotifyMessageContent>] [html [<Boolean>]]
]
```
*`notify [<Boolean>]` - Should notification be sent
In the subject and message, these strings will be replaced with the specified values:
*`#user#` - user's email address
*`#delegate#` - delegate's email address
If subject is not specified, the following value will be used:
*`#user# mail delegation to #delegate#`
`<NotifyMessageContent>` is the message, there are four ways to specify it:
*`message|textmessage|htmlmessage <String>` - Use `<String>` as the message
*`file|htmlfile <FileName> [charset <Charset>]` - Read the message from `<FileName>`
*`gdoc|ghtml <UserGoogleDoc>` - Read the message from `<UserGoogleDoc>`
*`gcsdoc|gcshtml <StorageBucketObjectName>` - Read the message from the Google Cloud Storage file `<StorageBucketObjectName>`
If `<NotifyMessageContent>`is not specified, the following value will be used:
*`#user# has granted you #delegate# access to read, delete and send mail on their behalf.`
Unless specified in `<NotifyMessageContent>`, messages are sent as plain text,
use `html` or `html true` to indicate that the message is HTML.
Use `\n` in `message <String>` to indicate a line break; no other special characters are recognized.
By default, the email is sent from the admin user identified in oauth2.txt, `gam oauth info` will show the value.
Use `from <EmailAddress>` to specify an alternate from address.
Use `mailbox <EmailAddress>` if `from <EmailAddress>` specifies a group; GAM has to login as a user to be able to send a message.
Gam gets no indication as to the status of the message delivery; the from user will get a non-delivery receipt if the message could not be sent to the delegate.
@@ -692,6 +693,7 @@ The `dateheaderconverttimezone [<Boolean>]>` option converts `<SMTPDateHeader>`
## Print only options
These options are valid with `print`.
*`convertcrnl` - In the message body, convert carriage returns to `\r` and newlines to `\n`; the default value is `csv_output_convert_cr_nl` from `gam.cfg`.
*`addcsvdata <FieldName> <String>` - Add additional columns of data from the command line to the output
By default, message attachment information is not displayed.
*`showattachments` - Display attachment filename, MIME type and size
teamDriveId=$(gam user user@domain.com create shareddrive ... returnidonly)
Windows PowerShell
$teamDriveId = & gam user user@domain.com create shareddrive ... returnidonly
Windows Command Prompt
for /f "delims=" %a in ('gam user user@domain.com create shareddrive ... returnidonly') do set teamDriveId=%a
```
## Bulk Create Shared Drives
@@ -425,9 +438,11 @@ The `Getting` and `Got` messages are written to stderr, the count is writtem to
To retrieve the count with `showitemcountonly`:
```
Linux/MacOS
count=$(gam user user@domain.com print shareddrives showitemcountonly)
count=$(gam user user@domain.com print shareddrives ... showitemcountonly)
Windows PowerShell
count = & gam user user@domain.com print shareddrives showitemcountonly
$count = & gam user user@domain.com print shareddrives ... showitemcountonly
Windows Command Prompt
for /f "delims=" %a in ('gam user user@domain.com print shareddrives ... showitemcountonly') do set count=%a
```
## Display Shared Drive Organizers
The following command can be used instead of the `GetTeamDriveOrganizers.py` script.
@@ -512,6 +527,40 @@ When adding permissions from JSON data, permissions with `deleted` true are neve
When deleting permissions from JSON data, permissions with role `owner` true are never processed.
## Transfer Shared Drive access
These commands are used to transfer ACLs from one Shared Drive to another.
*`copy` - Copy all ACLs from the source Shared Drive to the target Shared Drive. The role of an existing ACL in the target Shared Drive will never be reduced.
*`sync` - Add/delete/update ACLs in the target Shared Drive to match those in the source Shared Drive.
*`adminaccess|asadmin` specified - All Shared Drives must be in the same workspace as `<UserTypeEntity>`.
*`adminaccess|asadmin` not specified - Shared Drives can be in separate workspaces if `<UserTypeEntity>` in a manager of all of them.
```
gam <UserTypeEntity> copy shareddriveacls <SharedDriveEntity> to <SharedDriveEntity>
When `excludepermissionsfromdomains <DomainNameList>` is specified, any ACL that references a domain in `<DomainNameList>` will not be copied.
When `includepermissionsfromdomains <DomainNameList>` is specified, only ACLs that reference a domain in `<DomainNameList>` will be copied.
When `mappermissionsemail <EmailAddress> <EmailAddress>` is specifed, an ACL that references the first `<EmailAddress>` will be modified
to reference the second `<EmailAddress>` when copied; the original ACL is not modified. The option can be repeated if multiple email addresses are to be mapped.
Bulk permission email address mapping can be specified with `mappermissionsemailfile <CSVFileInput> endcsv`.
`<CSVFileInput>` must include these columns: `sourceEmail` and `destinationEmail`.
When `mappermissionsdomain <DomainName> <DomainName>` is specifed, any ACL that references the first `<DomainName>` will be modified
to reference the second `<DomainName>` when copied; the original ACL is not modified. The option can be repeated if multiple domain names are to be mapped.
## Display Shared Drive access
These commands are used to display the ACLs on Shared Drives themselves, not the files/folders on the Shared Drives.
@@ -419,6 +418,15 @@ this might be the user's secondary email address or their recovery email address
*`notify <EmailAddressList>` - Specify recipients
*`notifyrecoveryemail` - Use the user's recovery email address (if defined) as a recipient
In the subject and message, these strings will be replaced with the specified values:
*`#givenname#` - first/given name
*`#familyname#` - last/family name
*`#email#` - user's email address
*`#user#` - user's email address
*`#username#` - portion of user's email address before @
*`#domain#` - portion of user's email after after @
*`#password#` - password
If subject is not specified, the following value will be used:
* create - `Welcome to #domain#`
* update - `Account #user# password has been changed`
@@ -434,14 +442,8 @@ If `<NotifyMessageContent>`is not specified, the following value will be used:
Start using your new account by signing in at\nhttps://www.google.com/accounts/AccountChooser?Email=#user#&continue=https://workspace.google.com/dashboard\n`
* update - `The account password for #givenname# #familyname#, #user# has been changed to: #password#\n`
In the subject and message, these strings will be replaced with the specified values:
* `#givenname#` - first/given name
* `#familyname#` - last/family name
* `#email#` - user's email address
* `#user#` - user's email address
* `#username#` - portion of user's email address before @
* `#domain#` - portion of user's email after after @
* `#password#` - password
Unless specified in `<NotifyMessageContent>`, messages are sent as plain text,
use `html` or `html true` to indicate that the message is HTML.
Use `\n` in `message <String>` to indicate a line break; no other special characters are recognized.
@@ -464,8 +466,6 @@ Use `from <EmailAddress>` to specify an alternate from address.
Use `mailbox <EmailAddress>` if `from <EmailAddress>` specifies a group; GAM has to login as a user to be able to send a message.
Gam gets no indication as to the status of the message delivery; the from user will get a non-delivery receipt if the message could not be sent to the `notify <EmailAddressList>`.
By default, messages are sent as plain text, use `html` or `html true` to indicate that the message is HTML.
## Define schema fields
You can set custom schema field values for users; schema fields can be scalar, a single value, or can be multivalued.
@@ -996,11 +993,9 @@ gam <UserTypeEntity> info users
For `info users`, unlike all other GAM commands, a `<UserTypeEntity>` value of `all users` is actually `all users_ns_susp` not `all users_ns`.
This is a backwards compatibility issue.
Starting in version `5.23.01`, the variable `quick_info_user` was added to `gam.cfg` to control how much information requiring additional API calls is displayed.
(Prior to version `5.23.01`, assume `quick_info_user = False`.)
The variable `quick_info_user` was added to `gam.cfg` controls how much information requiring additional API calls is displayed.
`quick_info_user = False`: Gam makes additional API calls to get more information; you can selectively eliminate these calls to improve performance.
* `noaliases` - Do not get alias information
* `nobuildingnames` - Do not get building names for locations
* `nogroups` - Do not get group membership information
@@ -1344,8 +1339,11 @@ To retrieve the count with `showitemcountonly`:
**Alternative Approach**: For enhanced security and simplified operations when running GAM outside Google Cloud, consider [Workload Identity Federation](https://github.com/GAM-team/GAM/wiki/Using-GAM7-with-keyless-authentication-Workload-Identity-Federation) - Google's recommended keyless authentication method that eliminates the need for managing any long-lived credentials. If running GAM in Google Cloud, use [attached service accounts on GCE](https://github.com/GAM-team/GAM/wiki/Running-GAM7-securely-on-a-Google-Compute-Engine) instead.
## Thanks
Thanks to Jay Lee for the original version of this document.
## Introduction
GAM7 supports using a [YubiKey](https://www.yubico.com/products/yubikey-5-overview/) to generate and store the service account's private RSA key. Private keys generated by the YubiKey cannot be exported even to the computer running GAM7. When compared to the plain text oauth2service.json file with the private key stored in text, the YubiKey offers a more secure option that prevents digital theft and copying of the private key. Instead of reading the private key from the oauth2service.json file and signing requests itself, GAM7 will simply send signing requests to the YubiKey and get back the signature.
GAM7 version 6.50.01 or higher is required. Best practice is to always use the [latest version of GAM7](https://github.com/GAM-team/GAM/wiki/How-to-Update-Advanced-GAM).
## FAQs
### Can I use a Google Titan or other brand security key?
No, while Titan keys are great as security keys / U2F / 2SV, that is not the protocol being used by GAM7 here. GAM7 uses the PIV app of YubiKeys to work with service accounts. You need to use [a genuine Yubikey.](https://yubico.com/genuine/).
@@ -36,23 +29,32 @@ No, because the YubiKey generated the private key it cannot be digitally exporte
When using domain-wide delegation with GAM7, the service account and anyone possessing the service account private key oauth2service.json file has access to the Gmail, Drive and Calendar data of ALL Workspace users in your domain. For this reason, whether using a YubiKey or not, you should take strong measures to protect the service account private key.
## Setup Steps
1. Upgrade to at least GAM7 6.50.01.
2.**If you are using a new YubiKey or don't care about the PIV app data on the YubiKey**
1. Tell GAM7 to reset and configure the PIV app data on the YubiKey. This wipes all existing keys and configuration and then configures a private key and PIN for GAM7.
1.Upgrade to the [latest version of GAM7](https://github.com/GAM-team/GAM/wiki/How-to-Update-GAM7).
2. If you are using a new YubiKey or don't care about the PIV app data on the YubiKey:
a. Tell GAM7 to reset and configure the PIV app data on the YubiKey. This wipes all existing keys and configuration and then configures a private key and PIN for GAM7.
* Use `9a` for the `AUTHENTICATION` slot, `9c` for the `SIGNATURE` slot
5. Now that you have a private key on your YubiKey, tell GAM7 to use that instead of the private_key stored in oauth2service.json. We can do that by rotating the key:
4. Now that you have a private key on your YubiKey, tell GAM7 to use that instead of the private_key stored in oauth2service.json. We can do that by rotating the key:
@@ -65,10 +67,10 @@ copy oauth2service.json to oauth2service.yk
copy oauth2service.save to oauth2service.json
```
6. Now you should be able to run GAM7 commands like:
5. Now you should be able to run GAM7 commands like:
```
gam user admin@example.com check serviceaccount
```
and see the YubiKey lights flash as the YubiKey interacts with GAM7 to sign the GAM7 authentication requests. If you look at the oauth2service.json file, you'll see it contains some new fields like yubikey_serial and yubikey_pin but no longer contains the private_key field where GAM7 would normally store the private key data.
7. As a last step, since YubiKey-stored private keys do not need to be and should not be rotated, you can remove the service account's permissions to change it's own key. Navigate to the [Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts) select the correct project and service account and on the Permissions tab, edit and remove the "Service Account Key Admin" permission that the service account has to itself.
6. As a last step, since YubiKey-stored private keys do not need to be and should not be rotated, you can remove the service account's permissions to change it's own key. Navigate to the [Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts) select the correct project and service account and on the Permissions tab, edit and remove the "Service Account Key Admin" permission that the service account has to itself.
@@ -24,7 +24,7 @@ Not all Google Admin APIs work with DASA right no:
* GAM7 support for DASA is still experimental and some things may fail. Please report your findings to the [GAM group](https://groups.google.com/g/google-apps-manager).
## Setup Steps
1. Upgrade to at least GAM7 6.50.00. Best practice is to always use the [latest version of GAM7](https://github.com/GAM-team/GAM/wiki/How-to-Update-Advanced-GAM).
1. Upgrade to the [latest version of GAM7](https://github.com/GAM-team/GAM/wiki/How-to-Update-GAM7).
2. Follow the steps in `gam create project` up to the point where you are presented with a URL to the Cloud console to create a Client ID and secret. You don’t need to enter anything those, just press CTRL+C to quit the project creation.
Why would you want to download files one by one when GAM can download all Cloud Storage objects in one go? Because all of the files combined **might** take up a lot of space (think Terabytes in case of a Drive export of many years) whereas individually, each file will be in a much more manageable ~10 Gigabyte range.
## Copy Vault Exports
Many thanks to Jay for this command and documentation.
The `shownames` argument controls whether org unit and shared drive names are displayed in queries; additional API calls are required to get the names.
## Takeout
Many thanks to Jay for these commands and documentation.
GAM 6.42.00 and newer support copying and downloading Google Cloud Storage (GCS) buckets generated by [organization-wide Takeout](https://support.google.com/a/answer/100458?hl=en).
GAM supports copying and downloading Google Cloud Storage (GCS) buckets generated by [organization-wide Takeout](https://support.google.com/a/answer/100458?hl=en).
Once the Takeout completes you need to copy the name of the GCS bucket and provide it to GAM.
@@ -813,6 +817,26 @@ Edit `gam.cfg` on the other computer
* config_dir
* drive_dir
## Separate Staff-Student Domains
Suppose you have a single workspace with separate staff and student domains; e.g., school.org and students.school.org.
You can simplifiy typing email addresses by making two sections.
```
[DEFAULT]
customer_id = C1234567
[staff]
domain = school.org
[students]
domain = students.school.org
```
To issue commands about staff users, do: `gam config staff save`
Subsequent commands can omit `@school.org` from email addresses, GAM will supply `@school.org`.
To issue commands about student users, do: `gam config students save`
Subsequent commands can omit `@students.school.org` from email addresses, GAM will supply `@students.school.org`.
You can always type a complete email address if desired.
## Multiple Customers and Domains
There are four arguments to GAM that should simplify how you use GAM with multiple clients/domains.
Each client/domain will have a section in gam.cfg that sets the values specific to it.
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
