REST Resource: groups

Resource: Group

A group within the Cloud Identity Groups API.

A Group is a collection of entities, where each entity is either a user, another group, or a service account.

JSON representation 
{
  "name": string,
  "groupKey": {
    object (EntityKey)
  },
  "additionalGroupKeys": [
    {
      object (EntityKey)
    }
  ],
  "parent": string,
  "displayName": string,
  "description": string,
  "createTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  },
  "dynamicGroupMetadata": {
    object (DynamicGroupMetadata)
  },
  "posixGroups": [
    {
      object (PosixGroup)
    }
  ]
}
Fields
name

string

Output only. The resource name of the Group.

Shall be of the form groups/{groupId}.
groupKey

object (EntityKey)

Required. The EntityKey of the Group.
additionalGroupKeys[]

object (EntityKey)

Output only. Additional group keys associated with the Group.
parent

string

Required. Immutable. The resource name of the entity under which this Group resides in the Cloud Identity resource hierarchy.

Must be of the form identitysources/{identity_source} for external identity-mapped groups or customers/{customerId} for Google Groups. The customerId must begin with "C" (for example, 'C046psxkn'). Find your customer ID.
displayName

string

The display name of the Group.
description

string

An extended description to help users determine the purpose of a Group.

Must not be longer than 4,096 characters.
createTime

string (Timestamp format)

Output only. The time when the Group was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Output only. The time when the Group was last updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
labels

map (key: string, value: string)

Required. One or more label entries that apply to the Group. Currently supported labels contain a key with an empty value.

Google Groups are the default type of group and have a label with a key of cloudidentity.googleapis.com/groups.discussion_forum and an empty value.

Existing Google Groups can have an additional label with a key of cloudidentity.googleapis.com/groups.security and an empty value added to them. This is an immutable change and the security label cannot be removed once added.

Dynamic groups have a label with a key of cloudidentity.googleapis.com/groups.dynamic.

Identity-mapped groups for Cloud Search have a label with a key of system/groups/external and an empty value.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
dynamicGroupMetadata

object (DynamicGroupMetadata)

Optional. Dynamic group metadata like queries and status.
posixGroups[]

object (PosixGroup)

Optional. The POSIX groups associated with the Group.

DynamicGroupMetadata

Dynamic group metadata like queries and status.

JSON representation 
{
  "queries": [
    {
      object (DynamicGroupQuery)
    }
  ],
  "status": {
    object (DynamicGroupStatus)
  }
}
Fields
queries[]

object (DynamicGroupQuery)

Memberships will be the union of all queries. Only one entry with USER resource is currently supported. Customers can create up to 500 dynamic groups.
status

object (DynamicGroupStatus)

Output only. Status of the dynamic group.

DynamicGroupQuery

Defines a query on a resource.

JSON representation 
{
  "resourceType": enum (ResourceType),
  "query": string
}
Fields
resourceType

enum (ResourceType)
query

string

Query that determines the memberships of the dynamic group.

Examples: All users with at least one organizations.department of engineering.

user.organizations.exists(org, org.department=='engineering')

All users with at least one location that has area of foo and building_id of bar.

user.locations.exists(loc, loc.area=='foo' && loc.building_id=='bar')

All users with any variation of the name John Doe (case-insensitive queries add equalsIgnoreCase() to the value being queried).

user.name.value.equalsIgnoreCase('jOhn DoE')

ResourceType

Resources supported for dynamic groups.

Enums
RESOURCE_TYPE_UNSPECIFIED Default value (not valid)
USER For queries on User

DynamicGroupStatus

The current status of a dynamic group along with timestamp.

JSON representation 
{
  "status": enum (Status),
  "statusTime": string
}
Fields
status

enum (Status)

Status of the dynamic group.
statusTime

string (Timestamp format)

The latest time at which the dynamic group is guaranteed to be in the given status. If status is UP_TO_DATE, the latest time at which the dynamic group was confirmed to be up-to-date. If status is UPDATING_MEMBERSHIPS, the time at which dynamic group was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

Status

All possible statuses of a dynamic group.

Enums
STATUS_UNSPECIFIED Default.
UP_TO_DATE The dynamic group is up-to-date.
UPDATING_MEMBERSHIPS The dynamic group has just been created and memberships are being updated.
INVALID_QUERY Group is in an unrecoverable state and its memberships can't be updated.

PosixGroup

POSIX Group definition to represent a group in a POSIX compliant system. Caution: POSIX groups are deprecated. As of September 26, 2024, you can no longer create new POSIX groups. For more information, see https://cloud.google.com/identity/docs/deprecations/posix-groups

JSON representation 
{
  "name": string,
  "gid": string,
  "systemId": string
}
Fields
name

string

Name of the POSIX group.
gid

string

GID of the POSIX group.
systemId

string

System identifier for which group name and gid apply to. If not specified it will default to empty value.

Methods

create

 Creates a Group.

delete

 Deletes a Group.

get

 Retrieves a Group.

getSecuritySettings

 Get Security Settings

list

 Lists the Group resources under a customer or namespace.

lookup

 Looks up the resource name of a Group by its EntityKey.

patch

 Updates a Group.
Searches for Group resources matching a specified query.

updateSecuritySettings

 Update Security Settings