Operator Authentication via Identity-Aware Proxy (IAP)

Explains how the platform authenticates operators using an Identity-Aware Proxy (IAP) with OIDC or SAML, and the trusted headers it uses to establish

Overview

This document describes how the platform authenticates operators for access to administrative services. Authentication determines who is making a request. This process is distinct from authorization, which determines what an authenticated user is permitted to do and is handled by the Role-Based Access Control (RBAC) system.

The platform does not implement its own user login functionality. Instead, it delegates operator authentication to an Identity-Aware Proxy (IAP). The IAP integrates with your organization's existing identity provider (IdP). When an operator accesses the admin services, the IAP authenticates them and then forwards the request to the admin API, adding trusted HTTP headers that contain the operator's verified identity. The admin API consumes these headers to identify the user for the session.

This IAP model allows the platform to leverage robust, enterprise-grade identity systems without needing to manage user credentials directly.

How it Works

All administrative access flows through an IAP that is deployed on an internal load balancer in front of the admin services. The security of this model relies on the admin services having internal-only ingress, which ensures that requests can only reach them after passing through the trusted IAP. This prevents any unauthenticated actor from directly accessing the admin API or forging the identity headers.

The authentication sequence is as follows:

An operator attempts to access an administrative API endpoint (e.g., via a UI or CLI).
The request is intercepted by the IAP.
The IAP redirects the operator to your configured Identity Provider (e.g., Google, Azure AD) for login.
After successful authentication, the IdP provides an identity assertion (e.g., via OIDC or SAML) back to the IAP.
The IAP validates the assertion and forwards the operator's original request to the internal admin API. It adds specific HTTP headers containing the authenticated user's email and group memberships.
The admin API receives the request, reads the identity from the trusted headers, and establishes the operator's session.
The operator's identity is then passed to the RBAC system to determine their permissions.

The following diagram illustrates this data flow:

sequenceDiagram
    participant Operator
    participant IAP
    participant Identity Provider
    participant Admin API

    Operator->>+IAP: Access admin service
    IAP->>+Identity Provider: Redirect for authentication
    Identity Provider-->>-IAP: Provides identity assertion (e.g., OIDC/SAML)
    IAP->>+Admin API: Forward request with identity headers
    Admin API-->>-IAP: Service response
    IAP-->>-Operator: Service response

Identity Headers

The admin API relies on specific HTTP headers, set by the trusted IAP, to determine the caller's identity.

Header Name	Description	Notes
`X-Goog-Authenticated-User-Email`	The authenticated user's email address.	Used by Google Cloud IAP.
`X-Goog-Authenticated-User-Groups`	A comma-separated list of the user's group memberships.	Used by Google Cloud IAP.
`X-User-Email`	The authenticated user's email address.	Compatibility header for local development and non-production use.
`X-User-Groups`	A comma-separated list of the user's group memberships.	Compatibility header for local development and non-production use.

WARNING

The X-User-Email and X-User-Groups headers are intended for local development and initial system bring-up only. They must not be relied upon in a production environment where a proper IAP is in place.

Supported Identity Providers

The platform supports integration with identity providers through a compatible IAP.

Supported at GA

Google IAP: The primary, fully-exercised path for GCP-native deployments.
Azure AD: For installations fronted by Azure's identity-aware access capabilities.
Standard SAML / OIDC: For organizations using an IAP that supports standard federation protocols and can be configured to emit the required identity headers.

On the Roadmap

The following integrations are planned for future releases:

Additional identity providers including Okta and Keycloak.
Custom SAML profiles.

Fallback and Bootstrap Configurations

Two fallback modes exist for use in controlled situations, such as initial setup, where a full identity provider integration is not yet available.

Open Mode

If no identity provider is configured in the platform, it enters "open mode." In this mode, every call to an /admin/v1/* endpoint is treated as being made by an unrestricted administrator. This allows for the initial configuration of a fresh installation.

CAUTION

Open mode is a major security risk and is not a valid steady-state configuration. You must configure an identity provider before the platform is exposed to any users or network traffic.

Bootstrap Principals

For environments where an IAP is configured but does not forward group membership headers, you can use bootstrap environment variables to map specific user emails directly to roles. This is a fallback mechanism. For more details, see the documentation on how roles are resolved in RBAC.

Operator vs. Runtime Authentication

The authentication mechanisms described on this page apply only to operators (administrators) accessing the platform's control plane.

Authentication for the data plane (the REST↔SOAP conversion path) is handled separately. Inbound calls to the runtime are governed by your own network's access controls. Outbound calls from the runtime to backend services are authenticated using the encrypted backend credentials configured for each service.