# google directory

SureCloud connects to the Google Workspace Admin SDK Directory API to enumerate all user accounts in your domain, track two-step verification (2SV) enrolment at the per-user level, audit administrator role assignments for excessive privilege, and map group memberships. SureCloud also reads organisational unit structure to contextualise user and device records. This provides continuous evidence that your identity posture meets your access control requirements — covering MFA coverage, admin account hygiene, and group access governance.

## Endpoints

| API Call                                                        | Use Case                                                                            |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `GET /admin/directory/v1/users?domain={domain}`                 | Enumerate all user accounts; detect suspended, archived, and admin-flagged accounts |
| `GET /admin/directory/v1/users/{userKey}`                       | Retrieve full user record including `isEnrolledIn2Sv` and `isEnforcedIn2Sv`         |
| `GET /admin/directory/v1/groups?domain={domain}`                | List all groups in the domain                                                       |
| `GET /admin/directory/v1/groups/{groupKey}/members`             | Enumerate members of each group; detect external members                            |
| `GET /admin/directory/v1/customer/{customerId}/roles`           | List all admin roles defined in the domain (built-in and custom)                    |
| `GET /admin/directory/v1/customer/{customerId}/roleassignments` | Enumerate all admin role assignments; detect users with Super Admin                 |
| `GET /admin/directory/v1/customer/{customerId}/orgunits`        | Read the organisational unit hierarchy                                              |

## Pagination

The Directory API uses a `nextPageToken` field for paginated responses. SureCloud passes the token as the `pageToken` query parameter in successive requests until no token is returned.

```json
{
  "kind": "admin#directory#users",
  "users": [
    { "primaryEmail": "alice@yourcompany.com", "isEnrolledIn2Sv": true, ... }
  ],
  "nextPageToken": "CgkIARIECgIIAA=="
}
```

{% hint style="info" %}
SureCloud reads the `isEnrolledIn2Sv` and `isEnforcedIn2Sv` fields per user to distinguish between users who have voluntarily enrolled in 2SV and users for whom 2SV is enforced via an Admin Console policy. Both fields are included in the standard `users.list` and `users.get` responses — no additional API calls are needed for MFA status.
{% endhint %}

## Required permissions

The service account must have domain-wide delegation granted for the following scopes:

| OAuth scope                                                               | Purpose                                     |
| ------------------------------------------------------------------------- | ------------------------------------------- |
| `https://www.googleapis.com/auth/admin.directory.user.readonly`           | Read user accounts and 2SV enrolment status |
| `https://www.googleapis.com/auth/admin.directory.group.readonly`          | Read groups and group memberships           |
| `https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly` | Read admin roles and role assignments       |
| `https://www.googleapis.com/auth/admin.directory.orgunit.readonly`        | Read organisational unit hierarchy          |

The impersonated admin account must have at least the **User Management** admin privilege to read user records, and the **Services** privilege to read role assignments.

## Troubleshooting

<details>

<summary>2SV enrolment status shows as false for users who have 2SV enabled</summary>

The `isEnrolledIn2Sv` field reflects whether the user has completed the 2SV enrolment flow and has at least one 2SV method active. If a user enrolled recently, the field will be updated on the next 24-hour polling cycle.

If the field consistently shows `false` for enrolled users, confirm the impersonated admin account has the **User Management** privilege — this is required to read the 2SV fields in the user record.

</details>

<details>

<summary>Admin role assignments are returning an empty list</summary>

The `rolemanagement.readonly` scope and the `admin.directory.rolemanagement.readonly` delegation must both be present. In addition, the impersonated admin must hold a role that includes the **Admin Roles** privilege.

In the Admin Console, confirm **Security → Access and data controls → API controls → Manage domain-wide delegation** includes `https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly` in the scope list for the SureCloud service account.

</details>

<details>

<summary>External group members are not being flagged</summary>

SureCloud evaluates the `type` field in each group membership record. Members with `type: EXTERNAL` are users outside the domain. If external members are not being flagged, confirm the `admin.directory.group.readonly` scope is granted and that the groups in question are not restricted to internal membership only (which would prevent external members from existing).

</details>


---

# Agent Instructions: 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://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/google-workspace/google-directory.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.