[Design Proposal] Agent Manager - Permission Model

[lashinijay]

Problem

Agent Manager enables teams to build, deploy, and govern AI agents within an organization. Without a well-defined permission model, the platform risks two failure modes:

1. Over-exposure — sensitive operations (deleting agents, modifying production guardrails, promoting deployments) become available to users who should not have them.
2. Under-restriction — any developer can modify production resources or impact another team's agents, undermining governance and compliance.

The platform has two distinct access dimensions:

• Platform access — who manages resources inside the Agent Manager console
• Agent access — who invokes a deployed agent at runtime

This proposal addresses the platform access layer.

---

Goals

• Define a permission model that maps cleanly to the four organizational personas (Admin, Developer, AI Lead, Platform Engineer).
• Enforce least-privilege access on every platform API.
• Allow administrators to compose custom roles for restricted variants.
• Keep the architecture compatible with external Identity Providers (Azure AD, Okta, Auth0) in future phases without rework.

Non-Goals

• Agent runtime access control (who can invoke a deployed agent).
• Project-scoped role assignments — Phase 1 supports organization scope only.
• Multi-IDP support — Phase 1 uses Thunder exclusively.

---

User Stories

Administrator

• Invite and remove members; assign and revoke roles.
• Configure the Identity Provider; manage service accounts.
• Modify organization settings; full CRUD on projects, environments, LLM APIs, and MCP servers.
• Define custom roles by composing individual permissions.

Developer

• Full CRUD on agents, including configurations, secrets, and API security settings.
• Trigger builds and deploy to non-production environments (blocked from production).
• Connect agents to approved LLM APIs and MCP servers.
• View traces, logs, CPU/memory utilization, and LLM cost/token metrics.

AI Lead

• Full CRUD on LLM APIs and MCP servers in the resource hub.
• Configure guardrails, rate limits, and budgets; define production-readiness checks.
• View organization-wide observability (traces, LLM cost/token metrics, guardrail metrics).
• Cannot create agents or manage deployments.

Platform Engineer

• Full CRUD on environments.
• Deploy, promote, rollback, and suspend agents across all environments including production.
• Initiate builds; configure infrastructure-level guardrails and budgets.
• View deployment observability (logs, CPU/memory, guardrail metrics).
• Cannot modify agent logic.

Custom Roles

• Administrators compose custom roles from individual permissions for restricted variants (e.g., a Deploy-Only role that triggers deployments without modifying agent configuration).
• All authenticated users receive baseline read access to organization details, environments, projects, resources, and agents.

---

Proposed Solution

Agent Manager will use Thunder as the Identity Provider, with Agent Manager's permissions modeled as a resource server inside Thunder. The design is structured so that future external IDP integration is a contained change rather than a system-wide refactor.

Key Design Decisions

1. Thunder as the Identity Provider. Thunder owns users and permission assignments. Authentication and token issuance are delegated to Thunder.

2. Permissions modeled as a Thunder resource server. Agent Manager registers as a resource server in Thunder. Scopes (e.g., amp:agent:deploy_prod, amp:org:member_role_assign) and roles (Admin, Developer, AI Lead, Platform Engineer, custom) are defined as Thunder resource-server constructs.

3. Identity Provider runtime contract = scopes. Runtime authorization relies entirely on IDP-issued scopes carried in the access token. The backend enforces the required scope on every API call.

4. Agent Manager owns the permission management UI. User, role, and permission management screens live in the Agent Manager console. The console communicates only with the Agent Manager backend, never directly with Thunder.

5. Backend as authorization broker, with an IDP adapter seam. All IDP-specific calls live behind an IDPAdapter interface. ThunderAdapter is the only implementation in Phase 1; future IDPs implement the same interface.

UI and Pluggability Strategy

• Phase 1 (Thunder): Permission management is performed entirely through the Agent Manager console.
• Future pluggable IDPs: If a customer brings a non-compatible external IDP — one that does not expose write APIs for users and roles, or whose role model cannot be mapped to Agent Manager scopes — the Agent Manager permission management UI must be disabled for that deployment. In that mode, all user and permission management is performed in the external IDP's own admin console; Agent Manager only consumes the resulting tokens and enforces scopes at runtime.
• A configuration flag (permissionManagementUI: enabled | disabled) controls this behavior, set per deployment based on the configured IDP's capabilities.

Forward-Compatibility Principles

• IDP-agnostic backend contracts (domain code depends on the adapter interface, not Thunder SDKs).
• Internal user and role model decoupled from Thunder identifiers (Thunder IDs treated as external references).
• Scope-based authorization using Agent Manager scope strings; future adapters map IDP-native constructs to these scopes.
• Token validation abstracted behind the adapter (OIDC, SAML, opaque token, or JWT variants plug in later).
• Configuration-driven IDP selection (idp.provider config flag; only thunder accepted today).

---

Architecture

flowchart TB
    User["End User (Browser)"]

    subgraph Console["Agent Manager Console"]
        ConsoleUI["• Permission management UI<br/>• Domain views<br/>• OIDC client"]
    end

    subgraph Backend["Agent Manager Backend"]
        AuthZ["Auth/AuthZ Module<br/>JWT validation · Scope checks · Org isolation"]
        UserRole["User & Role Service<br/>Member CRUD · Role assignment · Custom roles"]
        Domain["Domain APIs<br/>Agents · Projects · Deployments"]
        Adapter["IDP Adapter Interface"]
        Thunder["ThunderAdapter"]
    end

    subgraph ThunderIDP["Thunder (IDP)"]
        Identity["Identity Store<br/>Users"]
        ResourceServer["Resource Server: Agent Manager<br/>Scopes · Roles · Assignments"]
    end

    User -->|HTTPS| Console
    Console -->|REST + access token| Backend
    AuthZ --> Adapter
    UserRole --> Adapter
    Domain --> AuthZ
    Adapter --> Thunder
    Thunder -->|Thunder Admin / Token APIs| ThunderIDP

Loading

Request Flow (Developer deploys an agent)

1. User signs in via the console; Thunder authenticates and issues an access token containing the user's scopes.
2. Console calls POST /deployments on the backend with the bearer token.
3. The Auth/AuthZ module validates the token through the IDP adapter and checks for amp:agent:deploy_nonprod.
4. If authorized, the domain API executes the deployment; otherwise it returns 403.
5. Permission management actions (invite member, assign role, create custom role) flow: console → backend → IDP adapter → Thunder Admin API.

---

Current State

The following components are already in place in the codebase:

• Thunder integration — ThunderConfig and OAuth2 app provisioning via clients/thundersvc.
• JWT validation — middleware/jwtassertion validates tokens via JWKS with issuer and audience checks.
• Console authentication — console/ uses @asgardeo/react with the OIDC flow.

The following work is required to deliver the proposal:

• Full scope catalog and RBAC enforcement across all domain APIs.
• Tenant boundary enforcement on all org-scoped routes.
• Authorization-aware resource hierarchy (organization → project → agent → build/deployment/configuration).
• Backend user and role management APIs.
• Console permission management UI.
• IDP adapter interface extraction.
• Production-readiness checks.

---

Milestones

Phase 1 — Foundations (Thunder only, ~3-5 weeks)

ID	Milestone	Duration
M1	Scope catalog & RBAC enforcement	~3–4 days
M2	Backend User & Role Service	~4–5 days
M3	Console Permission Management UI	~5-8 days
M4	Phase 1 hardening & GA	~3–5 days

Phase 1 deliverable: Thunder-based permission model with full Agent Manager-managed UI, all four predefined roles enforced end-to-end, and custom role support.

Phase 2 — Pluggability Foundation (~4-5 days)

ID	Milestone	Duration
M6	IDP Adapter extraction	~2–3 days
M7	UI disable mechanism (permissionManagementUI flag)	~1 day

Phase 2 deliverable: clean adapter seam and configuration to support non-compatible IDP deployments. No new IDP integration.

Phase 3 — First External IDP (~5–6 weeks)

ID	Milestone	Duration
M8	Select first external IDP and document capability gap	~2–3 days
M9	First external adapter implementation	~4-5 days
M10	Multi-IDP onboarding documentation	~1-2 days

Phase 3 deliverable: Agent Manager runs on a customer-chosen external IDP using the same scope-based runtime contract. This will not be covered with this feature.

---

Risks

• Thunder Admin API completeness — gaps in custom role or service account APIs may delay M2/M3.
• Console auth client compatibility — @asgardeo/react may need replacement with a Thunder-native client during M3.
• External IDP capability variance — IDPs without write APIs for users/roles will require the UI-disabled mode and reduce Phase 3 functionality for those deployments.

---

Verification

• Each role's permitted and denied actions verified against the permission matrix via integration tests.
• End-to-end: provision a user in Thunder under each predefined role, log in via console, confirm allowed/disallowed actions return 200/403 as expected.
• Custom-role flow: create a Deploy-Only role via console, assign to a user, confirm the user can deploy but cannot modify agent configurations.
• Adapter seam: confirm zero Thunder-specific imports outside ThunderAdapter.

[ayshsandu]

How would the authorization check happen at the AM backend? Would these backend APIs be exposed over API GW?

[lashinijay]

Hi @ayshsandu ,

Every request to agent-manager-service goes through two layers:

1. JWT validation (JWTAuthMiddleware) - applied to the entire /api/v1/ sub-mux in app.go. This validates the token signature against Thunder's JWKS endpoint and rejects any request with a missing or invalid token with 401.
2. Permission check (RequirePermission) - applied per-route in the *_routes.go files. After the token is validated, each handler checks that the token's scope claim contains the required permission string(e.g. role:read, org:invite-member). If not, the request is rejected with 403. This is declared inline at route registration:

middleware.HandleFuncWithValidationAndAuthz(mux, "DELETE /orgs/{orgName}/identities/roles/{roleID}",
rbac.RoleDelete, // ← permission checked here
ctrl.DeleteRole)

So there is no separate authz service call on the request path - it's a local JWT scope check.

Would these backend APIs be exposed over API GW?

Not currently. The identity management APIs (/api/v1/orgs/{orgName}/identities/...) are only exposed directly through the amp-api service via a standard Kubernetes Ingress (deployments/helm-charts/wso2-agent-manager/templates/ingress.yaml). They are intended to be called by the AMP console, amctl, and MCP - all of which hold a user/service-account JWT from Thunder.

The API GW (OpenChoreo's gateway) is used for agent runtime endpoints - routing inference traffic to deployed agents, managing agent tokens, etc. - not for AMP's own management plane APIs.
Routing management plane APIs through the API GW would add latency and an unnecessary hop for what is essentially an internal control plane.

That said, if there's a requirement to expose the identity APIs to external consumers (e.g. third-party tooling calling GET /identities/users), they could be published through the API GW with the same Thunder-issued JWT as the auth mechanism. The authorization model wouldn't change - the JWT scope check at the AM backend would still be the enforcement point.

Hope this clears your question.

cc: @menakaj

[jhivandb]

I'm unclear how service accounts fit here. We're building MCP and CLI as first-class
interfaces, and the plan for autonomous login is client_credentials (I want device code too, but that doesn't exist in thunder yet AFAIR?).
A few questions:

• Who provisions the OAuth app (for client_credential, in pkce auth-code this isn't an issue)? When a developer sets up amctl or connects an MCP client, something needs to create an OAuth app and issue credentials. Is that Thunder? Agent-manager?
  Who owns that lifecycle?
• How do we scope it narrowly? A CLI client should get manage_agent (create, build, deploy)
  but only for dev. The scope model makes sense, how do these get bound to a specific oauth app
  How does a client_credentials token end up with the right set?
• Does OuId survive? Agent-manager relies on OuId for org isolation. A client_credentials
  token doesn't go through user auth — will Thunder embed OuId in machine tokens?
  How will we isolate tenants?

Also — have we considered using OpenChoreo's existing Casbin-backed authz? otherwise we have two authz frameworks,
one respected upto the AM_SVC, but the AM_SVC invokes openchoreo apis, what happens there?

[lashinijay]

Hi @jhivandb ,

Who provisions the OAuth app (for client_credential, in pkce auth-code this isn't an issue)? When a developer sets up amctl or connects an MCP client, something needs to create an OAuth app and issue credentials. Is that Thunder? Agent-manager?
Who owns that lifecycle?

The RBAC proposal covers permission enforcement on existing authenticated sessions. How OAuth apps are created and
credentials distributed to amctl/MCP clients is a separate service account management feature. We have OrgManageServiceAccount already defined as a permission, and EnsurePublisherApp in the Thunder client
establishes the pattern (agent-manager provisions the app in Thunder using its system token), but the full lifecycle design deserves its own discussion.

How do we scope it narrowly? A CLI client should get manage_agent (create, build, deploy)
but only for dev.

The current permission model is org-scoped, not resource-scoped. A token either carries agent:deploy:non-production or it doesn't - there's no environment binding in the scope string today.

Two options:

1. Role-per-environment - create a dev-deployer role with only agent:deploy:non-production, assign it to the service account's OAuth app. This works today with no changes.
2. Parameterized scopes - e.g. agent:deploy:env:. This would need Thunder to support issuing claims scoped to a specific resource instance, which is non-trivial.

Option 1 is achievable now and covers the stated use case. Option 2 is a Thunder capability question.

The scope model makes sense, how do these get bound to a specific oauth app. How does a client_credentials token end up with the right set?

The OAuth app needs to be assigned a role in Thunder (same as a user). When agent-manager provisions a service account app, it creates the app bound to the org OU, and the user then assigns the appropriate role. Thunder then includes those role's permissions in the scope claim of the machine token. Same mechanism as user tokens - no special path for machine clients. However we need to have a discussion on how we are bringing this support to AMP first class.

Does OuId survive? Agent-manager relies on OuId for org isolation. A client_credentials
token doesn't go through user auth - will Thunder embed OuId in machine tokens?
How will we isolate tenants?
I feel this might need a separate discussion as bringing RBAC for application is not handled through this feature.

Also — have we considered using OpenChoreo's existing Casbin-backed authz? otherwise we have two authz frameworks,
one respected upto the AM_SVC, but the AM_SVC invokes openchoreo apis, what happens there?

These are two separate authz planes and the separation is intentional:

• AMP RBAC (JWT scopes) answers: can this principal use this AMP feature? (POST /agents, DELETE /roles, etc.)
• OpenChoreo Casbin answers: can this workload be deployed to this namespace / does this component have the right infra bindings?

Hope this clear your questions.