Retrieving and listing POSIX groups

Caution: POSIX groups are deprecated. As of September 26, 2024, you can no longer create new POSIX groups. For more information, see POSIX groups deprecation.

This document explains how to retrieve and list POSIX groups.

Preview

This product is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Note: You must use the beta version of the Cloud Identity Groups API to retrieve and list POSIX groups.

Retrieving members of POSIX groups

You can retrieve group information using the Google group name, POSIX group name, POSIX group ID, or email.

Retrieving a POSIX group by group name

The following sample shows how to retrieve a POSIX group using the group name:

REST

To retrieve a POSIX group by name, call the groups.get() method with the resource name of the group.

GET "https://cloudidentity.googleapis.com/v1beta1/groups/GROUP_RESOURCE_NAME"

Replace the following:

• GROUP_RESOURCE_NAME: the resource name of the Google group. To find a group's resource name, run the gcloud identity groups describe command

Python

The following example shows how to retrieve a POSIX group by name using the Python client library:

def get_posix_group_by_name(name):
  service = build_service()
  response = service.groups().get(name=name).execute()
  return response

Retrieving a POSIX group by POSIX group name

The following sample shows how to retrieve group information the POSIX group name:

REST

To search for a POSIX group by POSIX group name, call the groups.search() method with the following query string:

query=parent=='customers/CUSTOMER_ID' && 'cloudidentity.googleapis.com/groups.posix' in labels && posix_groups.exists(pg, pg.name=='POSIX_NAME')

Replace POSIX_NAME with the name you want to assign to the POSIX group.

The following is a GET request using the query:

GET "https://cloudidentity.googleapis.com/v1beta1/groups:search?query=parent=='customers/CUSTOMER_ID'%26%26'cloudidentity.googleapis.com/groups.posix'%20in%20labels%26%26posix_groups.exists(pg,pg.name=='POSIX_GROUP_NAME')&view=VIEW"

Replace the following:

• CUSTOMER_ID: the customer ID for your organization. To find the customer ID run the gcloud organizations list command
• POSIX_NAME: the name you want to assign to the POSIX group
• VIEW: either FULL or BASIC

Python

The following example shows how to retrieve a POSIX group by POSIX group name using the Python client library:

def get_posix_group_by_posix_name((service, customer_id, posix_group_name, page_size, view):
  # Set the label to search for a POSIX group
  searchQuery = ("&query=parent=='customers/{customer_id}' "
         "&& 'cloudidentity.googleapis.com/groups.posix' in labels "
         "&& posix_groups.exists(pg, pg.name=='{posix_group_name}')"
         "?pageSize={page_size}&view={view}".format(
             customer_id=customer_id, posix_group_name=posix_group_name,
             page_size=page_size, view=view))
  try:
    searchGroupsRequest = service.groups().search()
    searchGroupsRequest.uri += searchQuery
    response = searchGroupsRequest.execute()
    print response
  except Exception as e:
    print e

Retrieving a POSIX group by POSIX group ID

The following sample shows how to retrieve group information using the group ID:

REST

To search for a POSIX group by ID, call the groups.search() method with the following query string:

query=parent=='customers/CUSTOMER_ID' && 'cloudidentity.googleapis.com/groups.posix' in labels && posix_groups.exists(pg, pg.gid==GIDu)

Replace the following:

• CUSTOMER_ID: the customer ID for your organization. To find the customer ID run the gcloud organizations list command
• GROUP_ID: the group ID (GID) you want to assign to the POSIX group

The following is a GET request using the query:

GET "https://cloudidentity.googleapis.com/v1beta1/groups:search?query=parent=='customers/CUSTOMER_ID'%26%26'cloudidentity.googleapis.com/groups.posix'%20in%20labels%26%26posix_groups.exists(pg,pg.gid==GROUP_IDu)&view=VIEW"

Replace the following:

• CUSTOMER_ID: the customer ID for your organization. To find the customer ID run the gcloud organizations list command
• GROUP_ID: the group ID (GID) you want to assign to the POSIX group
• VIEW: either FULL or BASIC

Python

The following example shows how to retrieve a POSIX group by group ID using the Python client library:

def get_posix_group_by_gid(service, customer_id, posix_group_id, page_size, view):
  # Set the label to search for a POSIX group
  searchQuery = ("&query=parent=='customers/{customer_id}' "
         "&& 'cloudidentity.googleapis.com/groups.posix' in labels "
         "&& posix_groups.exists(pg, pg.gid=={posix_group_id}u)"
         "?pageSize={page_size}&view={view}".format(
             customer_id=customer_id, posix_group_id=posix_group_id,
             page_size=page_size, view=view))
  try:
    searchGroupsRequest = service.groups().search()
    searchGroupsRequest.uri += searchQuery
    response = searchGroupsRequest.execute()
    print response
  except Exception as e:
    print e

Retrieving a POSIX group by email

The following sample shows how to retrieve group information using the group email:

gcloud

Use the gcloud beta identity groups describe command to list all POSIX groups in an organization:

gcloud beta identity groups describe EMAIL_ADDRESS

Replace EMAIL_ADDRESS with the email address of the group being searched.

REST

To retrieve a POSIX group by email do the following:

1. Call the groups.lookup() method with the group email address:

   GET "https://cloudidentity.googleapis.com/v1beta1/groups:lookup?groupKey.id=EMAIL_ADDRESS"
   

   Note the resource name of the group returned.

2. Call the groups.get() method with the resource name of the group:

   GET "https://cloudidentity.googleapis.com/v1beta1/groups/GROUP_RESOURCE_NAME"
   

Python

The following example shows how to retrieve a POSIX group by email using the Python client library:

def get_posix_group_by_email(email):
  service = build_service()

  # First we use the email to get the groups name calling lookup()
  lookup_group_name_request = service.groups().lookup()
  param = "&groupKey.id=" + email
  lookup_group_name_request.uri += param
  lookup_group_name_response = lookup_group_name_request.execute()
  name = lookup_group_name_response.get("name")

  # Then we can call get() by passing in the group's name
  response = service.groups().get(name=name).execute()
  return response

Listing POSIX groups

The following examples show how to list all POSIX groups in your organization:

gcloud

Use the gcloud identity groups search command to list all POSIX groups in an organization:

gcloud identity groups search \
    --labels=cloudidentity.googleapis.com/groups.posix \
    --organization=ORGANIZATION

Replace ORGANIZATION with the organization ID for the group being searched.

REST

To search for all POSIX groups, call the groups.search() method with the following query string:

query=parent=='customers/CUSTOMER_ID' && 'cloudidentity.googleapis.com/groups.posix' in labels

Replace CUSTOMER_ID with the customer ID for your organization. To find the customer ID run the gcloud organizations list command.

The following is a GET request using the query:

GET "https://cloudidentity.googleapis.com/v1beta1/groups:search?query=parent=='customers/CUSTOMER_ID'%26%26'cloudidentity.googleapis.com/groups.posix'%20in%20labels&view=VIEW"

Replace the following:

• CUSTOMER_ID: the customer ID for your organization. To find the customer ID run the gcloud organizations list command
• GROUP_ID: the group ID (GID) you want to assign to the POSIX group
• VIEW: either FULL or BASIC

Python

The following example shows a helper function to search for POSIX groups using the Python client library:

def search_posix_groups(service, customer_id, page_size, view):
  # Set the label to search for all POSIX groups
  searchQuery = ("&query=parent=='customers/{customer_id}' "
         "&& 'cloudidentity.googleapis.com/groups.posix' in labels "
         "?pageSize={page_size}&view={view}".format(
             customer_id=customer_id, page_size=page_size, view=view))
  try:
    searchGroupsRequest = service.groups().search()
    searchGroupsRequest.uri += searchQuery
    response = searchGroupsRequest.execute()
    print response
  except Exception as e:
    print e