LFX 2026 Term 1 Project - Establishing AgentCube's Authentication and Authorization Capabilities

[mahil-2040]

Establishing AgentCube's Authentication and Authorization Capabilities

V=volcano-sh/agentcube: Establish authentication and authorization (2026 Term 1)*

AgentCube currently lacks a unified authentication and authorization model. This issue tracks the implementation of:

• Internal workload identity using X.509 mTLS between Router, WorkloadManager, and PicoD (SPIRE recommended, file-based certs also supported).
• Hybrid Sandbox Authentication using Application-layer JWTs for latency-critical code interpreters.
• External user authentication using Keycloak (OIDC/OAuth2) at the Router.
• Role-based authorization using Keycloak's built-in RBAC.
• Resource-Level Access Control (RLAC) for strict tenant isolation.
• Cloud provider federation via Keycloak identity brokering (stretch goal).

Design proposal: auth-proposal.md

Checkpoints

Internal Workload Authentication (X.509 mTLS & JWT)

• 1. Auth design proposal
  Publish the design document covering X.509 mTLS (with SPIRE and file-based certificate modes), Keycloak authentication, Keycloak RBAC authorization, and cloud provider federation.

• 2. SPIRE infrastructure deployment
  Add SPIRE Server (StatefulSet), Agent (DaemonSet), and Controller Manager (Deployment) manifests to agentcube-system. Create ServiceAccounts, RBAC, ConfigMaps for server/agent configuration, and ClusterSPIFFEID CRDs for declarative workload registration. SPIFFE IDs follow the Istio convention (spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>).

• 3. Certificate source abstraction and dynamic reloading
  Add --mtls-cert-file, --mtls-key-file, and --mtls-ca-file flags to Router, WorkloadManager, and PicoD. Implement a unified TLS configuration loader using Go's standard crypto/tls package. Configure GetCertificate and GetClientCertificate callbacks for dynamic zero-downtime certificate reloading. For SPIRE mode, the spiffe-helper sidecar writes SVIDs to disk as PEM files, consumed by the same code path. Unit tests for the configuration loader.

• 4. mTLS: Router → WorkloadManager
  Wrap the Router's HTTP client (in session_manager.go) with mTLS using the certificate source abstraction. Add mTLS server config to WorkloadManager that accepts only Router connections. Gate behind --enable-mtls flag. Unit tests for both sides.

• 5. mTLS: Router → PicoD
  Add mTLS client config in the Router for proxying to PicoD sandboxes. Add mTLS server config to PicoD accepting only Router. For SPIRE mode, mount the spiffe-helper sidecar and SPIRE Agent socket into sandbox pods via WorkloadManager's pod builder. For file-based mode, mount cert files from K8s Secrets. Unit tests included.

• 6. Hybrid Router → PicoD Authentication Modes
  Refactor the existing PicoD-Plain-Authentication code into a new, latency-optimized JWT mode. Add a --picod-auth-mode flag accepting mtls (default) or jwt. The jwt mode bypasses TLS handshake overhead by using an application-layer Authorization: Bearer header, specifically designed for Code Interpreters and agentic RL scenarios targeting ~100ms bootstrap latency. Unit tests for mode-based toggling.

External Authentication & Authorization (Keycloak)

• 7. Keycloak deployment and realm setup
  Add Keycloak Deployment and Service manifests to agentcube-system. Configure agentcube realm with agentcube-sdk, agentcube-router, and workloadmanager clients. Ensure AgentCube components support dynamic realm configuration via CLI flags (--keycloak-realm) to natively support multi-tenant isolation. Create sandbox:invoke, sandbox:manage, admin realm roles with inheritance.

• 8. Router JWT verification and Role-based Authorization
  Focus solely on edge validation. Add Keycloak JWT validation middleware to Router: periodic JWKS key fetching, local caching, and token signature verification. Extract realm_access.roles claims and add authorization middleware mapping Router endpoints to required Keycloak roles (e.g., sandbox:invoke). Return 403 Forbidden for insufficient permissions. Gate behind --enable-external-auth flag. Unit tests for validation and role enforcement.

• 9. User Identity Propagation (Token Exchange)
  Focus on internal identity propagation. Add Token Exchange logic (grant_type=urn:ietf:params:oauth:grant-type:token-exchange) to swap the validated incoming SDK token for a downstream token scoped to WorkloadManager and PicoD audiences. Forward the exchanged JWT in the Authorization: Bearer header over the internal channels. Update WorkloadManager and PicoD to validate the exchanged JWT using local JWKS fetchers. Unit tests for token exchange and validation.

• 10. Resource-Level Access Control (RLAC)
  Focus on tenant isolation. Update WorkloadManager to read the sub claim from the exchanged JWT (representing the end user) and apply it as an agentcube.io/owner label when provisioning sandbox CRDs and Pods. Update Router to query the target sandbox's labels before proxying traffic, ensuring the caller's sub matches the sandbox's owner label. Return 403 Forbidden for unauthorized sandbox access. Unit tests for resource tenant isolation.

• 11. Python SDK authentication support
  Add ServiceAccountAuth and TokenAuth classes to the Python SDK. ServiceAccountAuth handles automatic token acquisition via client_credentials grant and re-authentication on expiry. TokenAuth accepts a pre-obtained token as-is. Attach Authorization: Bearer header to all requests when auth is configured. Unit tests included.

Stretch Goal

• 12. Cloud provider identity federation
  Configure Keycloak identity brokering for AWS IAM (OIDC), Google Cloud Identity (OAuth2), and Azure AD (SAML/OIDC). No AgentCube code changes - Keycloak admin configuration and documentation only.

Testing and Documentation

• 13. E2E tests
  End-to-end tests covering: mTLS between internal components, Keycloak token issuance and Router validation, role enforcement, RLAC ownership isolation, Token Exchange, and the Hybrid mtls/jwt PicoD auth modes.

• 14. User guide and developer documentation
  Document setup instructions for SPIRE and file-based certificate modes, Keycloak configuration, multi-tenant realm configuration, SDK usage, role management, RLAC validation, and cloud provider federation. Add to docs/.

[hzxuzhonghu]

@YaoZengzeng @acsoto please review

[acsoto]

This topic looks promising, but it may help to separate internal auth and external auth because implementation and testing together could become quite heavy.

[acsoto]

Since there is already an existing auth flow in the project, it would be helpful to explain the migration path from the current model to the new one.

[acsoto]

I think a design doc should come first, especially to clarify the responsibilities of Router, WorkloadManager, and PicoD.

[acsoto]

The Python SDK part may also be worth making a separate phase, otherwise the overall scope could keep growing.

[acsoto]

For Router -> WorkloadManager, should WorkloadManager fully trust Router identity, or will it still keep its own layer of validation?

[acsoto]

For Router -> PicoD, is the plan to fully replace the current JWT/plain-auth path, or keep it as a fallback for some time?

[mahil-2040]

@acsoto , Thank for review, i have already made a pull request for the design doc, you can check it out #241. And i will update this issue once that design is accepted. You can review the PR #241 and suggest changes on that. I think from that doc most of your queries will be answered.