Role-Based Access Control (RBAC) for the Admin API

Overview

All administrative operations performed via the control plane endpoints (/admin/v1/*) are protected by a Role-Based Access Control (RBAC) system. This system ensures that authenticated principals can only perform actions for which they are authorized.

On every incoming request to the Admin API, the system resolves the caller's authenticated identity to one of three predefined roles. These roles determine the caller's access rights, from read-only observation to full administrative control. This document details the available roles, the resolution process, and the mechanisms for managing role assignments.

Roles

The platform defines three distinct roles. Roles are hierarchical; higher-privilege roles inherit all permissions of lower-privilege roles. For example, an admin can perform any action an operator or reader can.

How Role Resolution Works

When a request is received by the Admin API, it follows a strict, ordered sequence to map the caller's identity to a role. This deterministic process ensures a durable fallback path is always available, preventing lockouts due to misconfiguration or external service failures.

flowchart TD
    subgraph Admin API
        A[Request Received] --> B{Resolve Caller Role};
    end

    subgraph Role Resolution Steps
        B --> C{1. Direct In-App Bindings};
        C -- Found --> Z[Role Assigned];
        C -- Not Found --> D{2. Forwarded IdP Group Headers};
        D -- Found --> Z;
        D -- Not Found --> E{3. Directory Group Lookup};
        E -- Found --> Z;
        E -- Not Found --> F{4. Emergency Bootstrap Variables};
        F -- Found --> Z;
        F -- Not Found --> X[Access Denied];
    end

The resolution steps are executed in the following order:

1. Direct In-App Principal Bindings: The system first checks for a direct mapping of the user's email to a role within the platform's database (s2r_principal_role_binding table). These bindings are managed via the API and are independent of any external identity provider or directory service. This is the recommended and most durable method for managing permissions.

2. Forwarded IdP Group Headers: If no direct binding is found, the system inspects request headers (e.g., X-Goog-Authenticated-User-Groups) for group membership information forwarded by an identity-aware proxy. If present, it maps these groups to roles using the configured group-to-role bindings (s2r_role_binding table).

3. Directory Group Lookup: If group headers are not forwarded, the system can be configured to query the Cloud Identity Groups API to resolve the caller's group memberships. This requires the directory API to be enabled and the platform's service account to have the necessary read permissions. This lookup mechanism is off by default and must be enabled per environment.

4. Emergency Bootstrap Environment Variables: As a final fallback, the system checks for environment variables that map specific user emails to roles. This is a "break-glass" mechanism intended for initial system setup or emergency access if other methods fail.

The currently resolved identity and role for a caller can be retrieved by making a request to the GET /admin/v1/me endpoint.

Managing Role Assignments

Role assignments are managed through two types of bindings, both configured via the Admin API. Managing these bindings is a privileged operation restricted to users with the admin role. All changes to bindings are recorded in the audit trail.

API Endpoints

Example: Managing Direct User-to-Role Bindings

To grant a user the operator role, an administrator would use the API for direct principal bindings.

1. List current bindings: An admin can first inspect the existing bindings to prevent duplication.

   curl -X GET "https://<api_host>/admin/v1/permission-bindings" \
        -H "Authorization: Bearer <ADMIN_TOKEN>"
   

   The source does not specify the exact response payload.

2. Create a new binding: The admin then creates a new binding by sending a request that maps the user's email to the desired role.

   curl -X POST "https://<api_host>/admin/v1/permission-bindings" \
        -H "Authorization: Bearer <ADMIN_TOKEN>" \
        -H "Content-Type: application/json" \
        -d '{"email": "user@example.com", "role": "operator"}'
   

   NOTE

   The request body in the example above is illustrative. The source does not define the exact payload structure for this endpoint.

3. Verify the binding: The user can now make a request to GET /admin/v1/me to confirm their identity is resolved to the operator role.

Emergency Bootstrap Configuration

For initial setup or recovery scenarios, roles can be assigned via environment variables. This method should be used sparingly. For steady-state operations, migrate to direct in-app bindings or IdP group mappings.

Troubleshooting

• User cannot access the Admin API: Verify that the identity-aware proxy is configured to allow the user's identity through to the platform.
• User has wrong role or no role:
  1. Use the GET /admin/v1/me endpoint with the user's credentials to see how the system is currently resolving their role.
  2. Check the role resolution order described in How Role Resolution Works. An unintended binding at a higher-precedence step (e.g., a direct binding) may be overriding a desired binding at a lower step (e.g., a group binding).
  3. If using directory group lookups (step 3), ensure the feature is enabled for the environment and that the platform's service account has sufficient permissions on the Cloud Identity Groups API.
• Locked out of admin access: If all admin users lose access, use the S2R_ADMIN_BOOTSTRAP_EMAILS environment variable to grant emergency admin privileges to a designated recovery account. Once access is restored, use the Admin API to create durable in-app bindings and then remove the bootstrap configuration.

See Also

• Security Overview
• Authentication
• Audit Trail
• Admin API Reference

All SOAP-to-REST docs