From 924d15a100acee9eb81c32cc065c8d58d0b84d04 Mon Sep 17 00:00:00 2001 From: alvinkam2001 Date: Mon, 27 Apr 2026 11:57:46 -0700 Subject: [PATCH 1/2] add service account id to auth cache Co-Authored-By: Claude Opus 4.7 (1M context) --- agentex/docs/docs/configuration.md | 34 +++++++++++++++++-------- agentex/src/api/authentication_cache.py | 10 +++++++- 2 files changed, 33 insertions(+), 11 deletions(-) diff --git a/agentex/docs/docs/configuration.md b/agentex/docs/docs/configuration.md index 61f296ce..783e3ce2 100644 --- a/agentex/docs/docs/configuration.md +++ b/agentex/docs/docs/configuration.md @@ -300,26 +300,40 @@ kubernetes: - Keep under 63 characters (Kubernetes limit) #### Auth Principal Configuration + +The `principal` block identifies the calling identity used for authorization on +agent registration. **Set exactly one of `user_id` or `service_account_id`** — +they're mutually exclusive. + +For a human user identity: +```yaml +auth: + principal: + user_id: "my-dev-cluster-user-id" # SGP user UUID + account_id: "my-dev-cluster-account-id" # Account/tenant ID the agent registers into +``` + +For a service-account identity (machine identity created via the IAM dashboard): ```yaml auth: principal: - user_id: "my-dev-cluster-user-id" # Unique identifier for the user who is deploying the agent - account_id: "my-dev-cluster-account-id" # Account/tenant identifier + service_account_id: "my-service-account-uuid" # SGP service account UUID + account_id: "my-account-id" # Account where the SA has manager/admin role ``` **Auth Principal Purpose:** -- **User Identification**: Identifies the user/service account deploying the agent -- **Deployment Authorization**: Controls who can deploy agents to specific environments -- **Account/Tenant Isolation**: Associates deployments with specific accounts or tenants -- **Audit Trail**: Tracks who deployed which agents and when +- **Identity selection**: Tells the registration call who is acting — a user or a service account. +- **Deployment Authorization**: Controls who can register agents on a given account. +- **Account/Tenant Isolation**: Associates the registered agent with a specific account/tenant. +- **Audit Trail**: Tracks who registered which agents and when. **Best Practices:** -- **Unique per environment**: Use different user_id for dev vs prod deployment contexts -- **Environment-specific**: `my-dev-cluster-user-id` vs `my-prod-cluster-user-id` -- **Consistent format**: Use same naming pattern across your organization -- **Proper identifiers**: user_id should identify the deploying user/service, account_id should identify the account_id that the agent should be created in. +- **Pick one ID type**: never set both `user_id` and `service_account_id`. The platform rejects requests carrying both. +- **For automated/non-interactive deploys**, prefer `service_account_id` — it's a long-lived machine identity that can outlive any individual user. +- **Match the role on the target account**: whichever identity you reference must have `manager` or `admin` role on `account_id` for registration to succeed. +- **Environment-specific**: Use different IDs for dev vs prod deployment contexts. #### Helm Overrides ```yaml diff --git a/agentex/src/api/authentication_cache.py b/agentex/src/api/authentication_cache.py index 2bd4d81c..12a4bbe0 100644 --- a/agentex/src/api/authentication_cache.py +++ b/agentex/src/api/authentication_cache.py @@ -251,7 +251,15 @@ def _create_authorization_cache_key( context_dict = {"value": str(principal_context)} # Extract key fields that identify the principal - for key in ["user_id", "account_id", "agent_id", "id", "sub", "email"]: + for key in [ + "user_id", + "service_account_id", + "account_id", + "agent_id", + "id", + "sub", + "email", + ]: if key in context_dict: principal_key_data[key] = context_dict[key] From 8ce8b651f9c7f282136600a00a56c51dfec34684 Mon Sep 17 00:00:00 2001 From: alvinkam2001 Date: Thu, 30 Apr 2026 00:23:36 -0700 Subject: [PATCH 2/2] remove SGP-specific comments --- agentex/docs/docs/configuration.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/agentex/docs/docs/configuration.md b/agentex/docs/docs/configuration.md index 783e3ce2..449ca79b 100644 --- a/agentex/docs/docs/configuration.md +++ b/agentex/docs/docs/configuration.md @@ -309,16 +309,16 @@ For a human user identity: ```yaml auth: principal: - user_id: "my-dev-cluster-user-id" # SGP user UUID - account_id: "my-dev-cluster-account-id" # Account/tenant ID the agent registers into + user_id: "my-dev-cluster-user-id" # Unique identifier for the user who is deploying the agent + account_id: "my-dev-cluster-account-id" # Account/tenant identifier ``` -For a service-account identity (machine identity created via the IAM dashboard): +For a service-account identity (a machine identity intended for automated/non-interactive deploys): ```yaml auth: principal: - service_account_id: "my-service-account-uuid" # SGP service account UUID - account_id: "my-account-id" # Account where the SA has manager/admin role + service_account_id: "my-service-account-uuid" # Unique identifier for the service account that is deploying the agent + account_id: "my-account-id" # Account/tenant identifier ``` **Auth Principal Purpose:** @@ -332,7 +332,7 @@ auth: - **Pick one ID type**: never set both `user_id` and `service_account_id`. The platform rejects requests carrying both. - **For automated/non-interactive deploys**, prefer `service_account_id` — it's a long-lived machine identity that can outlive any individual user. -- **Match the role on the target account**: whichever identity you reference must have `manager` or `admin` role on `account_id` for registration to succeed. +- **Match permissions on the target account**: whichever identity you reference must have permissions on `account_id` sufficient to register agents. - **Environment-specific**: Use different IDs for dev vs prod deployment contexts. #### Helm Overrides