GCP IAM Groups and Roles

Welcome to the GCP Security and Networking Fundamentals course! We are excited to begin this journey together. In this first lesson, we will explore one of the foundational concepts of Google Cloud security: IAM identities, groups, and roles. Understanding how to organize users and manage their permissions effectively is critical for maintaining secure and well-structured GCP environments. By the end of this lesson, you will be comfortable assigning IAM roles to Google Groups, managing group memberships, and analyzing permissions programmatically using Python and the google-api-python-client library.

Before we start writing code, let's establish a clear understanding of what users, groups, and roles are in Google Cloud, and why they matter. In GCP Identity and Access Management (IAM), a user is typically a Google account (such as a Gmail or Workspace account). Each user has a unique identity and can be granted specific permissions. Managing permissions for each user individually can become challenging as organizations grow. This is where Google Groups come into play. A Google Group is a collection of users (and potentially other groups) who share common permission requirements. Instead of assigning roles to each user separately, you grant IAM roles to the group, and all members automatically inherit those permissions. This approach simplifies permission management, reduces errors, and ensures consistency across teams.

Groups serve as an organizational layer that makes permission management both efficient and scalable in GCP. For example, consider a development team where multiple engineers need similar access to GCP resources: they might need read access to Compute Engine instances, the ability to list Cloud Storage buckets, or permission to view logging data. Without groups, you would need to grant the same roles to each developer individually, which is time-consuming and error-prone. If you need to update permissions later, you would have to modify each user's roles separately. With Google Groups, you define the permissions once at the group level, add users to the group, and any permission changes automatically apply to all members. This pattern follows the principle of least privilege while maintaining operational efficiency. Groups also help with compliance and auditing, as you can quickly identify which users have which permissions by examining group memberships and IAM role bindings.

Throughout this unit, we use a mock GCP environment for practice. To keep the code consistent, all examples use:

• os.environ.get('GCP_DISCOVERY_URL') to retrieve the discovery URL
• credentials=None when building API clients

Why is credentials=None valid here? In the mock environment, requests are sent to a local practice service rather than real Google Cloud APIs, so real authentication is not required. In production code, you would usually rely on Application Default Credentials (ADC) instead of passing credentials=None.

Google Groups are managed outside of GCP, typically via the Google Groups interface or the Cloud Identity API. For most organizations, groups are created and managed by administrators. In this lesson, we will assume you have access to create and manage groups via the Cloud Identity API.

Below is an example of how to create a Google Group programmatically using the google-api-python-client:

from googleapiclient.discovery import build
import os

GCP_DISCOVERY_URL = os.environ.get('GCP_DISCOVERY_URL')

# Connect to the mock GCP service for practice
cloudidentity = build(
    'cloudidentity',
    'v1',
    discoveryServiceUrl=GCP_DISCOVERY_URL,
    credentials=None
)

def create_google_group(display_name, group_email):
    """Create a Google Group"""
    group_body = {
        "groupKey": {"id": group_email},
        "displayName": display_name,
        "labels": {"cloudidentity.googleapis.com/groups.discussion_forum": ""}
    }
    request = cloudidentity.groups().create(body=group_body)
    response = request.execute()
    return response

# Example usage:
# group = create_google_group("Developers", "developers-123456@example.com")
# print(group)

This code creates a new Google Group with a specified display name and email address. The group can then be used to manage permissions in GCP.

In GCP, permissions are managed by granting IAM roles to identities (users or groups) at the project or resource level. To grant a role to a Google Group, you update the IAM policy for the resource (such as a project) to include a binding for the group.

Below is an example of how to grant the roles/viewer role to a Google Group for a specific project using the google-api-python-client:

from googleapiclient.discovery import build
import os

PROJECT_ID = 'your-gcp-project-id'
GROUP_EMAIL = 'developers-123456@example.com'
GCP_DISCOVERY_URL = os.environ.get('GCP_DISCOVERY_URL')

# Connect to the mock GCP service for practice
cloudresourcemanager = build(
    'cloudresourcemanager',
    'v1',
    discoveryServiceUrl=GCP_DISCOVERY_URL,
    credentials=None
)

def add_group_iam_binding(project_id, group_email, role):
    """Grant an IAM role to a Google Group for a project"""
    policy = cloudresourcemanager.projects().getIamPolicy(
        resource=project_id, body={}
    ).execute()

    binding = next((b for b in policy['bindings'] if b['role'] == role), None)
    member = f'group:{group_email}'

    if binding:
        if member not in binding['members']:
            binding['members'].append(member)
    else:
        policy['bindings'].append({'role': role, 'members': [member]})

    set_policy_request = {'policy': policy}
    updated_policy = cloudresourcemanager.projects().setIamPolicy(
        resource=project_id, body=set_policy_request
    ).execute()
    return updated_policy

# Example usage:
# add_group_iam_binding(PROJECT_ID, GROUP_EMAIL, 'roles/viewer')

This code retrieves the current IAM policy for the project, adds the group as a member for the specified role, and updates the policy.

• The broad roles and permissions shown above are for demonstration and fast iteration in this lesson and practice tasks.
• In production, prefer custom roles (define once, assign to many, version and audit centrally) and follow least privilege: grant only the exact permissions on the exact resources required, often with conditions.
• Avoid using overly broad predefined roles (such as roles/editor or roles/owner) where possible. Instead, use predefined roles that match your needs (such as roles/storage.objectViewer for read-only access to Cloud Storage), or create custom roles with only the permissions required.

Least-privilege example: Custom role for read-only access to a specific Cloud Storage bucket

# Define a custom role using the gcloud CLI (outside Python for clarity)
# gcloud iam roles create StorageReadLogs --project=your-gcp-project-id \
#   --title="Read Logs" \
#   --permissions=storage.buckets.get,storage.objects.list,storage.objects.get \
#   --stage=GA

# Then assign it to a group as shown in the previous section
add_group_iam_binding(PROJECT_ID, GROUP_EMAIL, 'projects/your-gcp-project-id/roles/StorageReadLogs')

Best practice: Grant only the permissions required for the group's tasks, and regularly review group memberships and IAM role assignments.

To manage access efficiently, you add users (Google accounts) to a Google Group. This can be done via the Google Groups web interface or programmatically using the Cloud Identity API.

Below is an example of how to add a user to a Google Group using the API:

def add_member_to_group(group_email, member_email):
    """Add a user to a Google Group"""
    group_name = f'groups/{group_email}'
    membership_body = {
        "preferredMemberKey": {"id": member_email},
        "roles": [{"name": "MEMBER"}]
    }
    request = cloudidentity.groups().memberships().create(
        parent=group_name, body=membership_body
    )
    response = request.execute()
    return response

# Example usage:
# add_member_to_group("developers-123456@example.com", "alice@example.com")

Here, "roles": [{"name": "MEMBER"}] means the new user is being added as a standard group member. This is a Google Group membership role, not a GCP IAM role. In other words:

• MEMBER means the user belongs to the group and inherits any IAM access assigned to that group
• Other possible group membership roles can include elevated management roles depending on the API and configuration
• This does not mean the user directly gets an IAM role like roles/viewer; instead, they inherit whatever IAM roles the group already has

Once a user is added to the group, they automatically inherit all IAM roles assigned to that group for any GCP resource.

To verify group membership or audit who has access to certain permissions, you can list all members of a Google Group using the Cloud Identity API:

def list_group_members(group_email):
    """List all members of a Google Group"""
    group_name = f'groups/{group_email}'
    request = cloudidentity.groups().memberships().list(parent=group_name)
    response = request.execute()
    members = []
    for membership in response.get('memberships', []):
        member_id = membership['preferredMemberKey']['id']
        role = membership['roles'][0]['name']
        members.append({'email': member_id, 'role': role})
    return members

# Example usage:
# members = list_group_members("developers-123456@example.com")
# print(members)

To understand what access a group provides, you need to examine the IAM roles assigned to the group for a project or resource. You can list all IAM bindings for a project and filter for the group:

def list_group_roles(project_id, group_email):
    """List all IAM roles assigned to a Google Group for a project"""
    policy = cloudresourcemanager.projects().getIamPolicy(
        resource=project_id, body={}
    ).execute()
    group_member = f'group:{group_email}'
    roles = []
    for binding in policy['bindings']:
        if group_member in binding['members']:
            roles.append(binding['role'])
    return roles

# Example usage:
# roles = list_group_roles(PROJECT_ID, "developers-123456@example.com")
# print(roles)

To inspect the permissions included in a role, you can use the GCP IAM documentation or the gcloud iam roles describe command.

Let's execute our complete workflow and observe how all these functions work together to create a fully functional group-based permission system in GCP.

if __name__ == "__main__":
    # Create group
    group = create_google_group("Developers", "developers-123456@example.com")
    print(f"Group created: {group}\n")
    
    # Add users to group
    user1 = add_member_to_group("developers-123456@example.com", "alice@example.com")
    print(f"User 1 added: {user1}\n")
    
    user2 = add_member_to_group("developers-123456@example.com", "bob@example.com")
    print(f"User 2 added: {user2}\n")
    
    # Assign IAM role to group
    updated_policy = add_group_iam_binding(PROJECT_ID, "developers-123456@example.com", "roles/viewer")
    print(f"IAM policy updated: {updated_policy}\n")
    
    # List group members
    members = list_group_members("developers-123456@example.com")
    print(f"Group members: {members}\n")
    
    # List group roles
    roles = list_group_roles(PROJECT_ID, "developers-123456@example.com")
    print(f"Group roles: {roles}\n")

We've explored the fundamental concepts of GCP IAM identities, groups, and roles, learning how to create groups, assign roles, manage group memberships, and analyze permissions programmatically. In this unit's mock environment, we consistently use os.environ.get('GCP_DISCOVERY_URL') and credentials=None when building API clients. Remember: the broad roles used in demos are for learning clarity. In production, move to custom roles and least-privilege scopes with specific permissions and resources. Regularly review group memberships and IAM role assignments to maintain a secure and compliant environment.

In the next lessons, we will dive deeper into GCP IAM, explore service accounts, and learn how to manage permissions for more complex scenarios.