[Design Proposal] OAuth Support for Agent API Interfaces

[AnoshanJ]

Problem

Currently, when users create an Agent with an API interface, there is no built-in way to secure that interface using OAuth. APIs exposed by Agents cannot be protected using standardized token-based authentication through the platform.

This creates several limitations:
• Agent API interfaces cannot enforce OAuth authentication.
• Users cannot enable or disable OAuth per Agent API.
• API consumers cannot easily obtain credentials and tokens to securely invoke Agent APIs.
• Authentication configuration must be handled externally, outside the platform.

Since the platform already includes Thunder as the identity provider and the API Platform Gateway for policy enforcement, OAuth support should be integrated directly into the Agent lifecycle.

This proposal introduces configurable OAuth support for Agent API interfaces. When OAuth is enabled, API requests will require a valid JWT token issued by the platform’s Thunder instance and validated by the API Platform gateway.

User Stories

• As an Agent developer, I want to enable OAuth for my Agent API so that consumers must authenticate before invoking it.
• As an API consumer, I want to generate credentials and obtain tokens so that I can securely call the Agent API.

Existing Solutions

Within the platform ecosystem, API security is typically handled through:
• API Platform Gateway policies that enforce authentication at the gateway layer.
• Thunder Identity Provider which acts as the OAuth key manager and token issuer.
• JWT validation policies configured in the gateway.

Currently, Agent APIs do not automatically integrate with these components.

Current workaround

Users must manually configure authentication outside the platform or expose APIs without built-in OAuth protection. This leads to inconsistent security practices and makes it harder to securely expose Agent APIs.

Proposed Solution

Overview

Introduce OAuth configuration for Agent API interfaces using the platform’s Thunder identity provider as the default token issuer.

When OAuth is enabled:

• The Agent API will be routed through the API Platform Gateway

• A JWT authentication policy will be attached to the API

• A corresponding OAuth application will be created in Thunder

• API consumers will obtain tokens using the client_credentials grant

Initially, OAuth support will be available only for Custom API Agents.

---

Design

Gateway Integration

The API Platform Gateway will be configured to recognize Thunder as a key manager.

The gateway will validate JWT tokens using Thunder’s JWKS endpoint.

When OAuth is enabled for an Agent API:

• The API will be routed through the API Platform Gateway

• A jwt-auth policy will enforce token validation

---

API Configuration Trait

OAuth enforcement will be implemented through the api-configuration trait attached to the Agent API component.

The trait will configure:

• API routing through the API Platform gateway

• JWT authentication policy

• Thunder as the token issuer

Example configuration includes:

• API context

• upstream service port

• JWT authentication policy with Thunder issuer

---

OAuth Application Provisioning

Each Agent environment will have a corresponding OAuth application created in Thunder.

Client ID format:

agent-<org>-<project>-<agent>-<environment>

The application will support the client_credentials grant type.

Credentials generated:

• client_id

• client_secret

These credentials allow API consumers to request access tokens from Thunder.

---

OAuth Lifecycle Management

The backend service will manage the OAuth lifecycle.

Responsibilities include:

• Creating OAuth applications in Thunder

• Attaching API authentication policies

• Generating test tokens

• Persisting OAuth configuration

• Deleting OAuth applications when OAuth is disabled

---

Deployment Flow

OAuth configuration will be evaluated during Agent deployment.

When OAuth is enabled:

1. Create OAuth application in Thunder

2. Attach API configuration trait with JWT policy

3. Persist OAuth configuration

When OAuth is disabled:

1. Remove JWT policy from API configuration trait

2. Delete Thunder OAuth application

3. Remove stored OAuth credentials

---

UI Support

OAuth configuration will appear in multiple parts of the console UI.

---

Agent Deployment Configuration

Users will be able to enable OAuth when configuring an Agent deployment.

Example UI section:

Endpoint Authentication

• Security Scheme: OAuth2

• Security Header: Authorization

---

Agent Testing

The testing page will allow users to generate a test token and invoke the API.

Features include:

• Display invoke URL

• Generate test token

• Automatically inject Authorization header

---

Agent Consumption

API consumers will be able to generate credentials and obtain tokens.

Capabilities include:

• Create OAuth application

• View consumer key and secret

• Generate test tokens

• Access token endpoints

Data Persistence

OAuth configuration metadata will be stored in the platform database.

Stored fields include:

• OAuth enabled flag

• OAuth client ID

• Thunder application ID

Sensitive credentials such as client secrets will be stored securely in OpenBAO.

---

Out of Scope

The initial implementation does not include:

• Authorization Code grant flow

• User login flows

• Multiple identity providers

• Advanced authorization (scopes or RBAC)

• Developer portal or subscription workflows

The first version focuses only on machine-to-machine API access using client_credentials.

---

Alternatives Considered

No response

Open Questions

• Should OAuth applications be managed per agent/ per environment?

• Should OAuth Test app be created by default for Custom API Agents?

• Do we need a developer portal style application subscription model, or should OAuth applications be managed directly within the Agent UI for the initial release?

Milestones

Phase	Scope	Target
1	Migrate ingress gateway to API Platform gateway	Done
2	Introduce api-configuration trait with JWT policy support	Done
3	Implement Thunder client for OAuth application generation	WIP
4	Integrate OAuth provisioning into Agent deployment flow	WIP
5	Persist OAuth configuration in DB and OpenBAO	WIP
6	Add UI support for OAuth enablement, testing, and credential generation	TBD

Dependencies:

• API Platform Gateway JWT validation support

• Thunder identity provider integration

• Trait support for API configuration

• Secret storage through OpenBAO