Skip to content

Add tutorial: OpenAI Workload Identity integration with Agent ID #6281

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sajitha-tj wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add tutorial: OpenAI Workload Identity integration with Agent ID #6281

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
152a428
Add agent ID openAI WIF integration docs
sajitha-tj Jul 20, 2026
654e963
fix api_base_path in IS docs
sajitha-tj Jul 20, 2026
12a8ba8
Fix markdownLint issues
sajitha-tj Jul 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions en/asgardeo/docs/tutorials/agent-id-openai-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{% set product_name = "Asgardeo" %}
{% set api_base_path = "https://api.asgardeo.io/t/{organization_name}" %}

Check warning on line 2 in en/asgardeo/docs/tutorials/agent-id-openai-authentication.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'api_base_path'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'api_base_path'?", "location": {"path": "en/asgardeo/docs/tutorials/agent-id-openai-authentication.md", "range": {"start": {"line": 2, "column": 8}}}, "severity": "WARNING"}

{% include "../../../includes/tutorials/agent-id-openai-authentication.md" %}
1 change: 1 addition & 0 deletions en/asgardeo/docs/tutorials/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ See the topics listed below for end-to-end tutorials on how to use WSO2 Identity
- [Integrate WSO2 Identity Platform with SMART on FHIR healthcare apps]({{base_path}}/tutorials/smart-on-fhir/)
- [Secure Agentic AI Systems with WSO2 Identity Platform]({{base_path}}/tutorials/secure-agentic-ai-systems/)
- [Authenticate AI Agents to the Claude API with WSO2 Agent ID]({{base_path}}/tutorials/agent-id-claude-authentication/)
- [Authenticate AI Agents to the OpenAI API with WSO2 Agent ID]({{base_path}}/tutorials/agent-id-openai-authentication/)
- [Integrating WSO2 Identity Platform With WSO2 AI Gateway for Agent Identity-Aware Access Control]({{base_path}}/tutorials/wso2-ai-gateway-with-agent-identity-aware-access-control/)
- [Integrating WSO2 Identity Platform With Kong AI Gateway for Agent Identity-Aware Access Control]({{base_path}}/tutorials/kong-ai-gateway-with-agent-identity-aware-access-control/)
- [Secure MCP servers with WSO2 Identity Platform and integrate them with n8n agentic flows]({{base_path}}/tutorials/secure-mcp-servers-and-integrate-them-with-n8n-agentic-flows/)
1 change: 1 addition & 0 deletions en/asgardeo/mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -786,6 +786,7 @@ nav:
- Secure Agentic AI Systems with WSO2 Identity Platform: tutorials/secure-agentic-ai-systems.md
- Access Control for Ambient Agents: tutorials/ciba-for-ai-agents.md
- Authenticate AI Agents to the Claude API with WSO2 Agent ID: tutorials/agent-id-claude-authentication.md
- Authenticate AI Agents to the OpenAI API with WSO2 Agent ID: tutorials/agent-id-openai-authentication.md
- Implement End-to-End Authorization for MCP servers: tutorials/end-to-end-mcp-authorization-with-asgardeo.md
- Integrating WSO2 Identity Platform With WSO2 AI Gateway for Agent Identity-Aware Access Control: tutorials/wso2-ai-gateway-with-agent-identity-aware-access-control.md
- Integrating WSO2 Identity Platform With Kong AI Gateway for Agent Identity-Aware Access Control: tutorials/kong-ai-gateway-with-agent-identity-aware-access-control.md
Expand Down
2 changes: 1 addition & 1 deletion en/identity-server/7.2.0/docs/tutorials/agent-id-claude-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{% set product_name = "WSO2 Identity Server" %}
{% set api_base_path = "https://localhost:9443" %}
{% set api_base_path = "<your-domain>" %}

Check warning on line 2 in en/identity-server/7.2.0/docs/tutorials/agent-id-claude-authentication.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'api_base_path'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'api_base_path'?", "location": {"path": "en/identity-server/7.2.0/docs/tutorials/agent-id-claude-authentication.md", "range": {"start": {"line": 2, "column": 8}}}, "severity": "WARNING"}

@coderabbitai coderabbitai Bot Jul 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Use a complete HTTPS URL for api_base_path.

The shared tutorial uses this value for Python base_url and OAuth/JWKS endpoint construction. The current hostname-only placeholder generates invalid URLs; use https://<your-domain> in every Identity Server wrapper.

  • en/identity-server/7.2.0/docs/tutorials/agent-id-claude-authentication.md#L2-L2: change the placeholder to https://<your-domain>.
  • en/identity-server/7.3.0/docs/tutorials/agent-id-claude-authentication.md#L2-L2: change the placeholder to https://<your-domain>.
  • en/identity-server/next/docs/tutorials/agent-id-claude-authentication.md#L2-L2: change the placeholder to https://<your-domain>.
Proposed fix 
-{% set api_base_path = "<your-domain>" %}
+{% set api_base_path = "https://<your-domain>" %}
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
{% set api_base_path = "<your-domain>" %}
{% set api_base_path = "https://<your-domain>" %}
📍 Affects 3 files
  • en/identity-server/7.2.0/docs/tutorials/agent-id-claude-authentication.md#L2-L2 (this comment)
  • en/identity-server/7.3.0/docs/tutorials/agent-id-claude-authentication.md#L2-L2
  • en/identity-server/next/docs/tutorials/agent-id-claude-authentication.md#L2-L2
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@en/identity-server/7.2.0/docs/tutorials/agent-id-claude-authentication.md` at
line 2, Update api_base_path in
en/identity-server/7.2.0/docs/tutorials/agent-id-claude-authentication.md:2,
en/identity-server/7.3.0/docs/tutorials/agent-id-claude-authentication.md:2, and
en/identity-server/next/docs/tutorials/agent-id-claude-authentication.md:2 to
use the complete HTTPS placeholder https://&lt;your-domain&gt;.


{% include "../../../../includes/tutorials/agent-id-claude-authentication.md" %}
4 changes: 4 additions & 0 deletions en/identity-server/7.2.0/docs/tutorials/agent-id-openai-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{% set product_name = "WSO2 Identity Server" %}
{% set api_base_path = "https://localhost:9443" %}

Check warning on line 2 in en/identity-server/7.2.0/docs/tutorials/agent-id-openai-authentication.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'api_base_path'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'api_base_path'?", "location": {"path": "en/identity-server/7.2.0/docs/tutorials/agent-id-openai-authentication.md", "range": {"start": {"line": 2, "column": 8}}}, "severity": "WARNING"}

{% include "../../../../includes/tutorials/agent-id-openai-authentication.md" %}
1 change: 1 addition & 0 deletions en/identity-server/7.2.0/docs/tutorials/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,4 @@
- [Integrating WSO2 Identity Server With Kong AI Gateway for Agent Identity-Aware Access Control]({{base_path}}/tutorials/kong-ai-gateway-with-agent-identity-aware-access-control/)
- [Secure MCP servers with WSO2 Identity Server and integrate them with n8n agentic flows]({{base_path}}/tutorials/secure-mcp-servers-and-integrate-them-with-n8n-agentic-flows/)
- [Authenticate Agents with their own Agent ID to Claude API Using Workload Identity Federation]({{base_path}}/tutorials/agent-id-claude-authentication/)
- [Authenticate Agents with their own Agent ID to OpenAI API Using Workload Identity Federation]({{base_path}}/tutorials/agent-id-openai-authentication/)

Check failure on line 15 in en/identity-server/7.2.0/docs/tutorials/index.md

View workflow job for this annotation

GitHub Actions / lint

Files should end with a single newline character 

en/identity-server/7.2.0/docs/tutorials/index.md:15:153 MD047/single-trailing-newline Files should end with a single newline character https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md047.md
1 change: 1 addition & 0 deletions en/identity-server/7.2.0/mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -959,6 +959,7 @@ nav:
- Build your own push authenticator app: references/tutorials/build-your-own-push-authenticator-app.md
- Secure Agentic AI Systems with WSO2 Identity Server: tutorials/secure-agentic-ai-systems.md
- Authenticate Agents with their own Agent ID to Claude API Using Workload Identity Federation: tutorials/agent-id-claude-authentication.md
- Authenticate Agents with their own Agent ID to OpenAI API Using Workload Identity Federation: tutorials/agent-id-openai-authentication.md
- Integrating WSO2 Identity Server With WSO2 AI Gateway for Agent Identity-Aware Access Control: tutorials/wso2-ai-gateway-with-agent-identity-aware-access-control.md
- Integrating WSO2 Identity Server With Kong AI Gateway for Agent Identity-Aware Access Control: tutorials/kong-ai-gateway-with-agent-identity-aware-access-control.md
- Secure MCP servers with WSO2 Identity Server and integrate them with n8n agentic flows: tutorials/secure-mcp-servers-and-integrate-them-with-n8n-agentic-flows.md
Expand Down
2 changes: 1 addition & 1 deletion en/identity-server/7.3.0/docs/tutorials/agent-id-claude-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{% set product_name = "WSO2 Identity Server" %}
{% set api_base_path = "https://localhost:9443" %}
{% set api_base_path = "<your-domain>" %}

Check warning on line 2 in en/identity-server/7.3.0/docs/tutorials/agent-id-claude-authentication.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'api_base_path'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'api_base_path'?", "location": {"path": "en/identity-server/7.3.0/docs/tutorials/agent-id-claude-authentication.md", "range": {"start": {"line": 2, "column": 8}}}, "severity": "WARNING"}

{% include "../../../../includes/tutorials/agent-id-claude-authentication.md" %}
4 changes: 4 additions & 0 deletions en/identity-server/7.3.0/docs/tutorials/agent-id-openai-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{% set product_name = "WSO2 Identity Server" %}
{% set api_base_path = "https://localhost:9443" %}

Check warning on line 2 in en/identity-server/7.3.0/docs/tutorials/agent-id-openai-authentication.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'api_base_path'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'api_base_path'?", "location": {"path": "en/identity-server/7.3.0/docs/tutorials/agent-id-openai-authentication.md", "range": {"start": {"line": 2, "column": 8}}}, "severity": "WARNING"}

{% include "../../../../includes/tutorials/agent-id-openai-authentication.md" %}
1 change: 1 addition & 0 deletions en/identity-server/7.3.0/docs/tutorials/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,4 @@ See the topics listed below for end-to-end tutorials on how to use WSO2 Identity
- [Integrating WSO2 Identity Server With Kong AI Gateway for Agent Identity-Aware Access Control]({{base_path}}/tutorials/kong-ai-gateway-with-agent-identity-aware-access-control/)
- [Secure MCP servers with WSO2 Identity Server and integrate them with n8n agentic flows]({{base_path}}/tutorials/secure-mcp-servers-and-integrate-them-with-n8n-agentic-flows/)
- [Authenticate Agents with their own Agent ID to Claude API Using Workload Identity Federation]({{base_path}}/tutorials/agent-id-claude-authentication/)
- [Authenticate Agents with their own Agent ID to OpenAI API Using Workload Identity Federation]({{base_path}}/tutorials/agent-id-openai-authentication/)
1 change: 1 addition & 0 deletions en/identity-server/7.3.0/mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1001,6 +1001,7 @@ nav:
- Secure Agentic AI Systems with WSO2 Identity Server: tutorials/secure-agentic-ai-systems.md
- Access Control for Ambient Agents: tutorials/ciba-for-ai-agents.md
- Authenticate AI Agents to the Claude API with WSO2 Agent ID: tutorials/agent-id-claude-authentication.md
- Authenticate AI Agents to the OpenAI API with WSO2 Agent ID: tutorials/agent-id-openai-authentication.md
- Setup:
- Install:
- Install: deploy/get-started/install.md
Expand Down
2 changes: 1 addition & 1 deletion en/identity-server/next/docs/tutorials/agent-id-claude-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{% set product_name = "WSO2 Identity Server" %}
{% set api_base_path = "https://localhost:9443" %}
{% set api_base_path = "<your-domain>" %}

Check warning on line 2 in en/identity-server/next/docs/tutorials/agent-id-claude-authentication.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'api_base_path'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'api_base_path'?", "location": {"path": "en/identity-server/next/docs/tutorials/agent-id-claude-authentication.md", "range": {"start": {"line": 2, "column": 8}}}, "severity": "WARNING"}

{% include "../../../../includes/tutorials/agent-id-claude-authentication.md" %}
4 changes: 4 additions & 0 deletions en/identity-server/next/docs/tutorials/agent-id-openai-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{% set product_name = "WSO2 Identity Server" %}
{% set api_base_path = "https://localhost:9443" %}

Check warning on line 2 in en/identity-server/next/docs/tutorials/agent-id-openai-authentication.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'api_base_path'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'api_base_path'?", "location": {"path": "en/identity-server/next/docs/tutorials/agent-id-openai-authentication.md", "range": {"start": {"line": 2, "column": 8}}}, "severity": "WARNING"}

{% include "../../../../includes/tutorials/agent-id-openai-authentication.md" %}
1 change: 1 addition & 0 deletions en/identity-server/next/docs/tutorials/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,4 @@
- [Integrating WSO2 Identity Server With Kong AI Gateway for Agent Identity-Aware Access Control]({{base_path}}/tutorials/kong-ai-gateway-with-agent-identity-aware-access-control/)
- [Secure MCP servers with WSO2 Identity Server and integrate them with n8n agentic flows]({{base_path}}/tutorials/secure-mcp-servers-and-integrate-them-with-n8n-agentic-flows/)
- [Authenticate Agents with their own Agent ID to Claude API Using Workload Identity Federation]({{base_path}}/tutorials/agent-id-claude-authentication/)
- [Authenticate Agents with their own Agent ID to OpenAI API Using Workload Identity Federation]({{base_path}}/tutorials/agent-id-openai-authentication/)

Check failure on line 16 in en/identity-server/next/docs/tutorials/index.md

View workflow job for this annotation

GitHub Actions / lint

Files should end with a single newline character 

en/identity-server/next/docs/tutorials/index.md:16:153 MD047/single-trailing-newline Files should end with a single newline character https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md047.md
1 change: 1 addition & 0 deletions en/identity-server/next/mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1016,6 +1016,7 @@ nav:
- Integrating WSO2 Identity Server With Kong AI Gateway for Agent Identity-Aware Access Control: tutorials/kong-ai-gateway-with-agent-identity-aware-access-control.md
- Secure MCP servers with WSO2 Identity Server and integrate them with n8n agentic flows: tutorials/secure-mcp-servers-and-integrate-them-with-n8n-agentic-flows.md
- Authenticate AI Agents to the Claude API with WSO2 Agent ID: tutorials/agent-id-claude-authentication.md
- Authenticate AI Agents to the OpenAI API with WSO2 Agent ID: tutorials/agent-id-openai-authentication.md

- Setup:
- Install:
Expand Down
19 changes: 14 additions & 5 deletions en/includes/tutorials/agent-id-claude-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,17 @@ The authentication flow works as follows:
Before you begin, ensure you have the following:

- An [Anthropic](https://console.anthropic.com/) account with access to the Claude Console.
{% if product_name == "WSO2 Identity Server" %}
- A deployed instance of {{product_name}} that is accessible via a public URL `{{api_base_path}}`.
{% endif %}
- `curl` and `jq` installed on your machine (for the shell-based approach).
- Python 3.9+ (for the SDK-based approach).

{% if product_name == "WSO2 Identity Server" %}
!!! note
To configure Anthropic to work with {{product_name}}, your {{product_name}} instance must be publicly accessible over HTTPS and serve traffic on port 443. Anthropic retrieves the JWKS endpoint only from a publicly accessible HTTPS endpoint.
{% endif %}

## Step 1: Register an Agent in {{product_name}}

This is what replaces the shared static API key. Each agent gets its own Agent ID and Secret, so it's a distinct principal your security model can reason about, not just a possessor of a key.
Expand Down Expand Up @@ -159,9 +167,10 @@ from asgardeo_ai import AgentAuthManager, AgentConfig
from anthropic import Anthropic, WorkloadIdentityCredentials

# {{product_name}} configuration
config = AgentIDConfig(
config = AsgardeoConfig(
base_url="{{ api_base_path }}",
client_id="<your-client-id>",
client_secret="<your-client-secret>",
redirect_uri="<your-redirect-uri>",
)

Expand All @@ -181,8 +190,8 @@ class AgentIDTokenProvider:

EXPIRY_BUFFER_SECONDS = 60

def __init__(self, {{product_name}}_config, agent_cfg, scopes=None):
self.{{product_name}}_config = {{product_name}}_config
def __init__(self, identity_provider_config, agent_cfg, scopes=None):
self.identity_provider_config = identity_provider_config
self.agent_cfg = agent_cfg
self.scopes = scopes or ["openid", "profile"]
self._cached_token = None
Expand All @@ -202,7 +211,7 @@ class AgentIDTokenProvider:

async def _refresh_token(self):
async with AgentAuthManager(
self.{{product_name}}_config, self.agent_cfg
self.identity_provider_config, self.agent_cfg
) as auth_manager:
agent_token = await auth_manager.get_agent_token(
self.scopes
Expand Down Expand Up @@ -235,7 +244,7 @@ message = client.messages.create(
print(message.content[0].text)
```

The `AsgardeoTokenProvider` handles token caching and refresh with a 60-second buffer before expiry. The Anthropic SDK's `WorkloadIdentityCredentials` manages the Claude access token lifecycle independently, calling the provider whenever it needs a fresh identity token for the WIF exchange. Together, they allow long-running agents to operate continuously without manual token management.
The `AgentIDTokenProvider` handles token caching and refresh with a 60-second buffer before expiry. The Anthropic SDK's `WorkloadIdentityCredentials` manages the Claude access token lifecycle independently, calling the provider whenever it needs a fresh identity token for the WIF exchange. Together, they allow long-running agents to operate continuously without manual token management.

## What's Next

Expand Down
Loading
Loading