deepblue/GoogleDriveManagement
1
0
Fork 0
mirror of https://github.com/GAM-team/GAM.git synced 2025-07-07 05:03:34 +00:00
Code Issues Actions 11 Packages Projects Releases Wiki Activity
Files
d0a378413f874ebca045aaf56eb78dba1e355b6e
GoogleDriveManagement/docs/Cloud-Identity-Groups.md
Ross Scroggs 71777652cf Documentation updates
2023-08-22 09:55:20 -07:00

374 lines
20 KiB
Markdown
Raw Blame History

# Cloud Identity Groups
- [API documentation](#api-documentation)
- [Python Regular Expressions](Python-Regular-Expressions) Match function
- [Query documentation](#query-documentation)
- [Cloud Identity Group Documentation](#cloud-identity-group-documentation)
- [Security Group Documentation](#security-group-documentation)
- [Notes](#Notes)
- [Definitions](#definitions)
- [Manage groups](#manage-groups)
- [Display information about individual groups](#display-information-about-individual-groups)
- [Display information about multiple groups](#display-information-about-multiple-groups)
## API documentation
* https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups
* https://developers.google.com/admin-sdk/groups-settings/v1/reference/groups
* https://cloud.google.com/identity/docs/groups
* https://cloud.google.com/identity/docs/reference/rest/v1/groups
* https://support.google.com/a/answer/11192679
## Query documentation
* https://cloud.google.com/identity/docs/reference/rest/v1/groups#dynamicgroupquery
* https://cloud.google.com/identity/docs/reference/rest/v1/SecuritySettings#MemberRestriction
## Cloud Identity Group Documentation
* https://gsuiteupdates.googleblog.com/2020/08/new-api-cloud-identity-groups-google.html
## Security Group Documentation
* https://gsuiteupdates.googleblog.com/2020/09/security-groups-beta.html
## Notes
In the Admin Directory API a group has the following characteristics:
* `id` - The unique ID of a group
* `email` - The group's email address
* `name` - The group's display name
In the Cloud Indentity Groups API a group has the following characteristics:
* `name` - The unique ID of a group
* `groupKey.id` - The group's email address
* `displayName` - The group's display name
The Admin Directory API group characteristic names will be used.
Dynamic Groups require Cloud Identity Premium accounts.
* https://cloud.google.com/identity/docs/how-to/create-dynamic-groups
The `cimember <UserItem>` option of `gam print cigroups` requires a Google Workspace Enterprise Standard, Enterprise Plus, and Enterprise for Education;
and Cloud Identity Premium accounts. Unfortunately, even if you have the required account, the API call that supports the query doesn't work.
* https://cloud.google.com/identity/docs/reference/rest/v1/groups.memberships/searchTransitiveGroups
## Definitions
```
<DomainName> ::= <String>(.<String>)+
<EmailAddress> ::= <String>@<DomainName>
<UniqueID> ::= id:<String>
<GroupItem> ::= <EmailAddress>|<UniqueID>|<String>
<GroupList> ::= "<GroupItem>(,<GroupItem>)*"
<GroupEntity> ::=
<GroupList> | <FileSelector> | <CSVkmdSelector> | <CSVDataSelector>
See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items
<GroupRole> ::= owner|manager|member
<GroupRoleList> ::= "<GroupRole>(,<GroupRole>)*"
<CIGroupType> ::= customer|group|other|serviceaccount|user
<CIGroupTypeList> ::= "<CIGroupType>(,<CIGroupType>)*"
<QueryDynamicGroup> ::= <String>
See: https://cloud.google.com/identity/docs/reference/rest/v1/groups#dynamicgroupquery
<QueryMemberRestrictions> ::= <String>
See: https://cloud.google.com/identity/docs/reference/rest/v1/SecuritySettings#MemberRestriction
<JSONData> ::= (json [charset <Charset>] <String>) | (json file <FileName> [charset <Charset>]) |
<GroupSettingsAttribute> ::=
(allowexternalmembers <Boolean>)|
(allowwebposting <Boolean>)|
(archiveonly <Boolean>)|
(customfootertext <String>)|
(customreplyto <EmailAddress>)|
(defaultmessagedenynotificationtext <String>)|
(description <String>)|
(enablecollaborativeinbox|collaborative <Boolean>)|
(includeinglobaladdresslist|gal <Boolean>)|
(includecustomfooter <Boolean>)|
(isarchived <Boolean>)|
(memberscanpostasthegroup <Boolean>)|
(messagemoderationlevel moderate_all_messages|moderate_non_members|moderate_new_members|moderate_none)|
(name|displayname <String>)|
(primarylanguage <Language>)|
(replyto reply_to_custom|reply_to_sender|reply_to_list|reply_to_owner|reply_to_ignore|reply_to_managers)|
(sendmessagedenynotification <Boolean>)|
(spammoderationlevel allow|moderate|silently_moderate|reject)|
(whocanadd all_members_can_add|all_managers_can_add|all_owners_can_add|none_can_add)|
(whocancontactowner anyone_can_contact|all_in_domain_can_contact|all_members_can_contact|all_managers_can_contact)|
(whocanjoin anyone_can_join|all_in_domain_can_join|invited_can_join|can_request_to_join)|
(whocanleavegroup all_members_can_leave|all_managers_can_leave|all_owners_can_leave|none_can_leave)|
(whocanpostmessage none_can_post|all_managers_can_post|all_members_can_post|all_owners_can_post|all_in_domain_can_post|anyone_can_post)|
(whocanviewgroup anyone_can_view|all_in_domain_can_view|all_members_can_view|all_managers_can_view|all_owners_can_view)|
(whocanviewmembership all_in_domain_can_view|all_members_can_view|all_managers_can_view|all_owners_can_view)
<GroupWhoCanDiscoverGroupDeprecatedAttribute> ::=
(showingroupdirectory <Boolean>)
<GroupWhoCanAssistContentDeprecatedAttribute> ::=
(whocanassigntopics all_members|owners_and_managers|managers_only|owners_only|none)|
(whocanenterfreeformtags all_members|owners_and_managers|managers_only|owners_only|none)|
(whocanhideabuse all_members|owners_and_managers|managers_only|owners_only|none)|
(whocanmaketopicssticky all_members|owners_and_managers|managers_only|owners_only|none)|
(whocanmarkduplicate all_members|owners_and_managers|managers_only|owners_only|none)|
(whocanmarkfavoritereplyonanytopic all_members|owners_and_managers|managers_only|owners_only|none)|
(whocanmarknoresponseneeded all_members|owners_and_managers|managers_only|owners_only|none)|
(whocanmodifytagsandcategories all_members|owners_and_managers|managers_only|owners_only|none)|
(whocantaketopics all_members|owners_and_managers|managers_only|owners_only|none)|
(whocanunassigntopic all_members|owners_and_managers|managers_only|owners_only|none)|
(whocanunmarkfavoritereplyonanytopic all_members|owners_and_managers|managers_only|owners_only|none)
<GroupWhoCanModerateContentDeprecatedAttribute> ::=
(whocanapprovemessages all_members|owners_and_managers|owners_only|none)|
(whocandeleteanypost all_members|owners_and_managers|owners_only|none)|
(whocandeletetopics all_members|owners_and_managers|owners_only|none)|
(whocanlocktopics all_members|owners_and_managers|owners_only|none)|
(whocanmovetopicsin all_members|owners_and_managers|owners_only|none)|
(whocanmovetopicsout all_members|owners_and_managers|owners_only|none)|
(whocanpostannouncements all_members|owners_and_managers|owners_only|none)
<GroupWhoCanModerateMembersDeprecatedAttribute> ::=
(whocanadd all_members_can_add|all_managers_can_add|none_can_add)|
(whocanapprovemembers all_members_can_approve|all_managers_can_approve|all_owners_can_approve|none_can_approve)|
(whocanbanusers all_members|owners_and_managers|owners_only|none)|
(whocaninvite all_members_can_invite|all_managers_can_invite|all_owners_can_invite|none_can_invite)|
(whocanmodifymembers all_members|owners_and_managers|owners_only|none)
<GroupDeprecatedAttribute> ::=
(allowgooglecommunication <Boolean>)|
(favoriterepliesontop <Boolean>)|
(maxmessagebytes <ByteCount>)|
(messagedisplayfont default_font|fixed_width_font)|
(whocanaddreferences all_members|owners_and_managers|managers_only|owners_only|none)|
(whocanmarkfavoritereplyonowntopic all_members|owners_and_managers|managers_only|owners_only|none)
<GroupAttribute> ::=
<JSONData>|
<GroupSettingsAttribute>|
(whocandiscovergroup allmemberscandiscover|allindomaincandiscover|anyonecandiscover)|
(whocanassistcontent all_members|owners_and_managers|managers_only|owners_only|none)|
(whocanmoderatecontent all_members|owners_and_managers|owners_only|none)|
(whocanmoderatemembers all_members|owners_and_managers|owners_only|none)|
<GroupWhoCanDiscoverGroupDeprecatedAttribute>|
<GroupWhoCanAssistContentDeprecatedAttribute>|
<GroupWhoCanModerateContentDeprecatedAttribute>|
<GroupWhoCanModerateMembersDeprecatedAttribute>|
<GroupDeprecatedAttribute>
```
```
<GroupFieldName> ::=
admincreated|
aliases|
allowexternalmembers|
allowgooglecommunication|
allowwebposting|
archiveonly|
customfootertext|
customreplyto|
customrolesenabledforsettingstobemerged|
defaultmessagedenynotificationtext|
description|
directmemberscount|
email|
enablecollaborativeinbox|collaborative|
favoriterepliesontop|
id|
includecustomfooter|
includeinglobaladdresslist|gal|
isarchived|
maxmessagebytes|
memberscanpostasthegroup|
messagedisplayfont|
messagemoderationlevel|
name|
primarylanguage|
replyto|
sendmessagedenynotification|
showingroupdirectory|
spammoderationlevel|
whocanaddreferences|
whocanadd|
whocanapprovemessages|
whocanassigntopics|
whocanassistcontent|
whocancontactowner|
whocandeleteanypost|
whocandeletetopics|
whocandiscovergroup|
whocanenterfreeformtags|
whocanhideabuse|
whocaninvite|
whocanjoin|
whocanleavegroup|
whocanlocktopics|
whocanmaketopicssticky|
whocanmarkduplicate|
whocanmarkfavoritereplyonanytopic|
whocanmarkfavoritereplyonowntopic|
whocanmarknoresponseneeded|
whocanmoderatecontent|
whocanmodifytagsandcategories|
whocanmovetopicsin|
whocanmovetopicsout|
whocanpostannouncements|
whocanpostmessage|
whocantaketopics|
whocanunassigntopic|
whocanunmarkfavoritereplyonanytopic|
whocanviewgroup|
whocanviewmembership
<GroupFieldNameList> ::= "<GroupFieldName>(,<GroupFieldName>)*"
```
```
<CIGroupFieldName> ::=
additionalgroupkeys|
createtime|
description|
displayname|
dynamicgroupmetadata|
email|
groupkey|
id|
labels|
name|
parent|
updatetime
<CIGroupFieldNameList> ::= "<CIGroupFieldName>(,<CIGroupFieldName>)*"
```
## Manage groups
These commands allow you to create, update and delete groups. They use the Admin SDK Groups Settings API
to set `<GroupAttribute>`.
```
gam create cigroup <EmailAddress> [copyfrom <GroupItem>] <GroupAttribute>
[makeowner]
[alias|aliases <EmailAddressList>] [dynamic <QueryDynamicGroup>]
gam update cigroup <GroupEntity> [copyfrom <GroupItem>] <GroupAttribute>
[makesecuritygroup|security] [makedynamicsecuritygroup|dynamicsecurity] [dynamic <QueryDynamicGroup>]
[memberrestrictions <QueryMemberRestrictions>]
gam delete cigroups <GroupEntity>
```
The `copyfrom <GroupItem>` allows copying of group attributes from one group to another.
The following attributes are not copied: name, description, email, admincreated, aliases, noneditablealiases.
Any `<GroupAttribute>` specified will override the copied attributes.
You can update a non-dynamic group to a non-dynamic security group with the `makesecuritygroup` option. To update a dynamic group to a security group, use the `makedynamicsecuritygroup` option instead.
* Warning: A Security Group cannot be changed back to a Google Group.
You can update a group to restrict its membership with the `memberrestrictions <QueryMemberRestrictions>`option.
* https://cloud.google.com/identity/docs/reference/rest/v1/SecuritySettings#MemberRestriction
The `makeowner` option makes the administrator in `oauth2.txt` the initial owner of the group.
## Display information about individual groups
This command displays information as an indented list of keys and values.
```
gam info cigroups <GroupEntity>
[nousers|membertree] [quick] [noaliases]
[nosecurity|nosecuritysettings]
[allfields|<CIGroupFieldName>*|(fields <CIGroupFieldNameList>)]
[roles <GroupRoleList>] [members] [managers] [owners]
[types <CIGroupTypeList>]
[memberemaildisplaypattern|memberemailskippattern <RegularExpression>]
[formatjson]
```
By default, all direct members, managers and owners in the group are displayed; these options modify that behavior:
* `members` - Display members
* `managers` - Display managers
* `owners` - Display owners
* `nousers` or `quick` - Do not display any members, managers or owners
* `membertree` - Display all roles; expand all groups
By default, when displaying members from a group, all types of members (customer, group, serviceaccount, user) in the group are displayed; this option modifies that behavior:
* `types <CIGroupTypeList>` - Display specified types
Members that have met the above qualifications to be displayed can be further qualifed by their email address.
* `memberemaildisplaypattern <RegularExpression>` - Members with email addresses that match `<RegularExpression>` will be displayed; others will not be displayed
* `memberemailskippattern <RegularExpression>` - Members with email addresses that match `<RegularExpression>` will not be displayed; others will be displayed
By default, all group aliases are displayed, these options modify that behavior:
* `noaliases` or `quick` - Do not display group aliases
By default, GAM makes an additional API call to get the `SecuritySettings` for the group.
* `nosecuritysettings` - Do not make API and display `SecuritySettings`
* `allfields` - All Cloud Identity Group fields
* `<CIGroupFieldName>*` - Individual fields to display
* `fields <CIGroupFieldNameList>` - A comma separated list of fields to display
By default, Gam displays the information as an indented list of keys and values.
* `formatjson` - Display the output in JSON notation
## Display information about multiple groups
This command displays information in CSV format.
```
gam print cigroups [todrive <ToDriveAttribute>*]
[(cimember|showownedby <UserItem>)|(select <GroupEntity>)|(query <String>)]
[emailmatchpattern [not] <RegularExpression>] [namematchpattern [not] <RegularExpression>]
[descriptionmatchpattern [not] <RegularExpression>]
[basic|allfields|(<CIGroupFieldName>* [fields <CIGroupFieldNameList>])]
[roles <GroupRoleList>] [memberrestrictions]
[members|memberscount] [managers|managerscount] [owners|ownerscount] [totalcount] [countsonly]
[types <CIGroupTypeList>]
[memberemaildisplaypattern|memberemailskippattern <RegularExpression>]
[convertcrnl] [delimiter <Character>]
[formatjson [quotechar <Character>]]
```
By default, all groups in the account are displayed, these options allow selection of subsets of groups:
* `cimember <UserItem>` - Limit display to groups that contain `<UserItem>` as a member
* `showownedby <UserItem>` - Limit display to groups owned by `<UserItem>`
* `select <GroupEntity>` - Limit display to the groups specified in `<GroupEntity>`
* `query <String>` - Limit display to the groups that match the query
These options further limit the list of groups selected above:
* `emailmatchpattern <RegularExpression>` - Limit display to groups whose email address matches `<RegularExpression>`
* `emailmatchpattern not <RegularExpression>` - Limit display to groups whose email address does not match `<RegularExpression>`
* `namematchpattern <RegularExpression>` - Limit display to groups whose name matches `<RegularExpression>`
* `namematchpattern not <RegularExpression>` - Limit display to groups whose name does not match `<RegularExpression>`
* `descriptionmatchpattern <RegularExpression>` - Limit display to groups whose description matches `<RegularExpression>`
* `descriptionmatchpattern not <RegularExpression>` - Limit display to groups whose description does not match `<RegularExpression>`
By default, GAM does not make an additional API call todisplay the member restrictions from `SecuritySettings`.
* `memberrestrictions` - Make an additional API call and display the member restrictions from `SecuritySettings`
When retrieving lists of Google Groups from API, how many should be retrieved in each API call.
* `maxresults <Number>` - How many groups to retrieve in each API call; default is 500.
By default, only the group email address is displayed, these options specify what group fields to display:
* `basic` - Only Cloud Identity Group basic fields are displayed; no additional API calls are required
* `allfields|ciallfields` - All Cloud Identity Group fields are displayed; an additional API call per group is required
* `<GroupFieldName>*` - Individual fields to display
* `fields|cifields <CIGroupFieldNameList>` - A comma separated list of fields to display
As of 2020-12-24, a separate API call is required for each group to get the following fields:
`additionalgroupkeys,createtime,dynamicgroupmetadata,parent,updatetime`
Some text fields may contain carriage returns or line feeds, displaying fields containing these characters will make processing the CSV file with a script hard; this option converts those characters to a text form.
The default value is `csv_output_convert_cr_nl` from `gam.cfg`
* `convertcrnl` - Convert carriage return to \r and line feed to \n
When lists of items are displayed, the delimiter between items defaults to the `csv_output_column_delimiter` value in gam.cfg; you can specify a different delimiter:
* `delimiter <Character>` - Use `<Character>` as the list item delimiter, `<Character>` must be a single character after processing any escape character
By default, no members, managers or owners in the group are displayed; these options modify that behavior:
* `members` - Display list of members
* `memberscount` - Display count of members but not individual members
* `managers` - Display list of managers
* `managerscount` - Display count of managers but not individual managers
* `owners` - Display list of owners
* `ownerscount` - Display count of owners but not individual owners
* `countsonly` - Change any `members`, `managers` or `owners` options to `memberscount`, `managerscount` or `ownerscount`
* `totalcount` - Display sum of counts of members, managers, owners.
By default, when displaying members from a group, all types of members (customer, group, serviceaccount, user) in the group are displayed; this option modifies that behavior:
* `types <CIGroupTypeList>` - Display specified types
Members that have met the above qualifications to be displayed can be further qualifed by their email address.
* `memberemaildisplaypattern <RegularExpression>` - Members with email addresses that match `<RegularExpression>` will be displayed; others will not be displayed
* `memberemailskippattern <RegularExpression>` - Members with email addresses that match `<RegularExpression>` will not be displayed; others will be displayed
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.
### Display security groups
```
gam print cigroups query "'cloudidentity.googleapis.com/groups.security' in labels"
```
Reference in New Issue View Git Blame Copy Permalink