Skip to content

Cloud Identity Groups

Jump to bottom
Ross Scroggs edited this page Dec 27, 2020 · 29 revisions

Cloud Identity Groups

API documentation

Query documentation

Cloud Identity Group Documentation

Security Group Documentation

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.

Definitions

<DomainName> ::= <String>(.<String>)+
<EmailAddress> ::= <String>@<DomainName>
<UniqueID> ::= uid:<String>
<GroupItem> ::= <EmailAddress>|<UniqueID>|<String>
<GroupList> ::= "<GroupItem>(,<GroupItem>)*"
<GroupEntity> ::= <GroupList> | <FileSelector> | <CSVkmdSelector> | <CSVDataSelector>
<GroupRole> ::= owner|manager|member
<GroupRoleList> ::= "<GroupRole>(,<GroupRole>)*"
<CIGroupType> ::= customer|group|serviceaccount|user
<CIGroupTypeList> ::= "<CIGroupType>(,<CIGroupType>)*"
<QueryDynamicGroup> ::= <String>
        See: https://cloud.google.com/identity/docs/reference/rest/v1beta1/groups#dynamicgroupquery

<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> ::=
        (json [charset <Charset>] <JSONData>)|(json file <FileName> [charset <Charset>])|
        <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 <AliasList>] [dynamic <QueryDynamicGroup>]
gam update cigroup <GroupEntity> [copyfrom <GroupItem>] <GroupAttribute>
        [makesecuritygroup|security]
        [alias|aliases <AliasList>] [dynamic <QueryDynamicGroup>]
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 group to a security group with the makesecuritygroup option.

  • Warning: A Security Group cannot be changed back to a Google Group.

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] [quick] [noaliases]
        [allfields|<CIGroupFieldName>*|(fields <CIGroupFieldNameList>)]
        [roles <GroupRoleList>] [members] [managers] [owners]
        [types <CIGroupTypeList>]
        [memberemaildisplaypattern|memberemailskippattern <RegularExpression>]
        [formatjson]

By default, all 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

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

These options specify what group fields to display:

  • 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 <UserItem>)|(select <GroupEntity>)]
        [showownedby <UserItem>]
        [emailmatchpattern [not] <RegularExpression>] [namematchpattern [not] <RegularExpression>]
        [descriptionmatchpattern [not] <RegularExpression>]
        [allfields|(<CIGroupFieldName>* [fields <CIGroupFieldNameList>])]
        [roles <GroupRoleList>]
        [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
  • select <GroupEntity> - Limit display to the groups specified in <GroupEntity>
  • showownedby <UserItem> - Limit display to groups owned by <UserItem>

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>

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:

  • allfields|ciallfields - All Cloud Identity Group fields are displayed
  • <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 ouput 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.

Need more help? Ask on the GAM Discussion Group

Update History

Installation

Configuration

Notes and Information

Definitions

Command Processing

Collections

Client Access

Special Service Account Access

Service Account Access

Clone this wiki locally