OpenID Connect (OIDC) + OAuth for AI Agents

2 hours ago 1

Standardized authentication for autonomous AI agents

A specialized OAuth 2.1 authorization server designed for autonomous AI agents. Unlike traditional OAuth flows that require human interaction, Auth Agent enables AI agents to authenticate themselves programmatically through PKCE and credential verification.

Watch Auth Agent in action:

Demo 1: Profilio Integration

AI agent authenticating on Profilio platform using browser-use.

Demo 2: Crypto Exchange Dashboard

Authentication flow on crypto trading platform.

Demo 3: GitHub Clone Website

Full OAuth flow on GitHub-style repository dashboard.

🔐 OAuth 2.1 Compliant - Full implementation with PKCE required
🤖 AI Agent Authentication - Agents authenticate using agent_id + agent_secret
⚡ No User Consent - Streamlined for autonomous agents (consent handled during onboarding)
🎫 JWT Access Tokens - Stateless token validation with JWT (HS256)
🔄 Refresh Tokens - Long-lived sessions with opaque refresh tokens
🔍 Token Introspection - RFC 7662 compliant token validation
🗑️ Token Revocation - RFC 7009 compliant token revocation
📋 OAuth Discovery - RFC 8414 metadata endpoint
🌐 Edge Deployment - Global deployment on Cloudflare Workers + Supabase PostgreSQL
📦 SDK Support - TypeScript & Python SDKs for easy integration

Cloudflare Workers - Edge serverless platform for OAuth endpoints
Supabase - PostgreSQL database for storing clients, agents, and tokens
Hono - Fast web framework for Cloudflare Workers
TypeScript - Type-safe development
JWT (jose) - JSON Web Tokens for stateless authentication

Next.js - React framework for demo websites
React - UI components and SDK widgets
TypeScript - Type-safe client SDK
Tailwind CSS - Styling for demo websites

Python - Agent SDK
aiohttp - Async HTTP client for agents

Supabase (PostgreSQL) - Primary database with row-level security

Vercel - Frontend deployment (demo websites)
Cloudflare Workers - Backend deployment (edge network)

PBKDF2 - Password hashing for secrets
SHA-256 - PKCE code challenge hashing
HS256 - JWT signing algorithm
bcrypt - Additional credential hashing

🔄 Complete OAuth 2.1 Workflow

sequenceDiagram participant Agent as AI Agent (browser-use) participant Website as Website (Next.js) participant AuthServer as Auth Server (Cloudflare Workers) Note over Agent,AuthServer: Auth Agent OAuth 2.1 Flow Agent->>Website: 1. Navigate to website Agent->>Website: 2. Click "Sign in with Auth Agent" button Note over Website: 3. Generate PKCE (code_verifier, code_challenge) Website->>AuthServer: 4. Redirect to /authorize (with PKCE challenge) AuthServer->>Agent: 5. Return spinning page (shows "Authenticating AI Agent") Note over Agent: 6. Extract request_id from window.authRequest Agent->>AuthServer: 7. POST /api/agent/authenticate { request_id, agent_id, agent_secret, model } Note over AuthServer: 8. Verify credentials (PBKDF2 hash check) AuthServer->>Agent: 9. Authentication success loop Polling for completion Agent->>AuthServer: 10. GET /api/check-status? request_id=... AuthServer->>Agent: 11. Status: "authenticated" end Agent->>Website: 12. Auto-redirect to callback (with authorization code) Website->>AuthServer: 13. POST /token { code, code_verifier, client_id, secret } Note over AuthServer: 14. Validate PKCE (SHA-256 verify) Note over AuthServer: 15. Generate JWT & refresh token AuthServer->>Website: 16. Return tokens { access_token, refresh_token } Note over Website: 17. Store tokens in localStorage Website->>Agent: 18. Redirect to dashboard (authenticated!)

Key Differences from Traditional OAuth

Traditional OAuth (for humans):

User clicks "Sign in"
User redirected to auth server
User enters credentials manually ❌
User approves consent screen ❌
User redirected back with code

Auth Agent (for AI):

AI Agent clicks "Sign in" (automated)
Browser redirected to auth server
Agent detects auth page programmatically ✅
Agent POSTs credentials via API ✅
Browser auto-redirects back with code

2. Configure Environment Variables

⚠️ Important: All .env* files are gitignored. You need to create your own .env files from the provided .env.example templates.

# Copy environment variable template cp .env.example .env # Edit .env with your actual credentials # See Configuration section below for details

3. Deploy to Cloudflare Workers

# Install Wrangler CLI if you haven't npm install -g wrangler # Login to Cloudflare npx wrangler login # Deploy npx wrangler deploy

This creates:

A test agent with credentials
A test client (website)
Saves credentials to test-credentials.json

Runs a complete OAuth flow simulation.

SDK Documentation - Client and agent SDKs
Browser-Use Integration - AI agent authentication examples
Demo Websites - Three integrated demo websites
Hackathon Pitch Guide - Presentation materials

Standard OAuth 2.1 authorization endpoint. Shows spinning page while agent authenticates.

Query Parameters:

client_id - OAuth client identifier
redirect_uri - Callback URL
response_type - Must be "code"
state - CSRF protection token
code_challenge - PKCE challenge (S256)
code_challenge_method - Must be "S256"
scope - Optional, defaults to "openid profile"

Exchange authorization code for tokens, or refresh access token.

Body (authorization_code grant):

{ "grant_type": "authorization_code", "code": "code_xxx", "code_verifier": "...", "client_id": "client_xxx", "client_secret": "..." }

Body (refresh_token grant):

{ "grant_type": "refresh_token", "refresh_token": "rt_xxx", "client_id": "client_xxx", "client_secret": "..." }

Validate and get information about a token (RFC 7662).

{ "token": "eyJhbG...", "token_type_hint": "access_token", "client_id": "client_xxx", "client_secret": "..." }

Revoke an access or refresh token (RFC 7009).

{ "token": "eyJhbG...", "token_type_hint": "access_token", "client_id": "client_xxx", "client_secret": "..." }

Agent Back-Channel Endpoints

POST /api/agent/authenticate

Agent sends credentials to complete an authorization request.

{ "request_id": "req_xxx", "agent_id": "agent_xxx", "agent_secret": "...", "model": "gpt-4" }

Check if agent has completed authentication (used by spinning page polling).

Query Parameters:

request_id - The authorization request ID

POST /api/admin/agents - Create new agent
GET /api/admin/agents - List all agents
GET /api/admin/agents/:id - Get agent details
DELETE /api/admin/agents/:id - Delete agent

POST /api/admin/clients - Create new client
GET /api/admin/clients - List all clients
GET /api/admin/clients/:id - Get client details
PUT /api/admin/clients/:id - Update client
DELETE /api/admin/clients/:id - Delete client

GET /.well-known/oauth-authorization-server - OAuth server metadata (RFC 8414)
GET /.well-known/jwks.json - JSON Web Key Set

Important: All .env* files are gitignored for security. Never commit actual credentials to the repository.

Environment variable templates (.env.example) are provided for:

Auth_Agent/workers/ - Auth Agent server configuration (Cloudflare Workers, Supabase, JWT)
website-integration-example/ - Website integration example with OAuth client credentials
Auth_Agent/examples/browser-use-integration/ - AI agent credentials (AGENT_ID, AGENT_SECRET, etc.)

To get started:

Copy the relevant .env.example file to .env (or .env.local for Next.js projects):

# For the Cloudflare Workers server cd Auth_Agent/workers cp .env.example .env # For browser-use examples cd Auth_Agent/examples/browser-use-integration cp .env.example .env # For website integration example (use .env.local for Next.js) cd website-integration-example cp .env.example .env.local
Fill in your actual credentials in the .env file
Create agents/clients using the provided scripts (see SDK documentation)

Server Environment Variables

For the Cloudflare Workers server, configure these variables in your wrangler.toml and Cloudflare dashboard:

JWT_SECRET=your-secret-key-change-in-production JWT_ISSUER=auth-agent.com SUPABASE_URL=https://your-project.supabase.co SUPABASE_ANON_KEY=your-supabase-anon-key SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key

PKCE (Proof Key for Code Exchange)

OAuth 2.1 requires PKCE for all authorization code flows. This prevents authorization code interception attacks.

Code verifier: Random 128-character string
Code challenge: SHA-256 hash of verifier
Method: S256 (SHA-256)

All secrets (agent_secret, client_secret) are hashed with PBKDF2 before storage. Original secrets are never stored in the database.

Access tokens are JWTs signed with HS256, enabling stateless validation. Tokens include:

sub - Agent ID
client_id - OAuth client identifier
model - AI model type
scope - Granted permissions
iat - Issued at timestamp
exp - Expiration timestamp

Refresh tokens are random strings stored in the database, allowing easy revocation and token rotation.

Authorization requests expire after 10 minutes to prevent replay attacks.

All redirect URIs must use HTTPS (except localhost for development).

Auth_Agent_YC/ ├── Auth_Agent/ # Main Auth Agent implementation │ ├── workers/ # Cloudflare Workers backend │ │ ├── src/ # Source code │ │ │ ├── index.ts # Main Hono router (OAuth endpoints) │ │ │ ├── routes/ # OAuth route handlers │ │ │ ├── db/ # Supabase database client │ │ │ ├── lib/ # Shared utilities (crypto, JWT) │ │ │ └── templates/ # HTML templates (spinning page, errors) │ │ └── wrangler.toml # Cloudflare Workers configuration │ ├── sdk/ # SDKs for integration │ │ ├── agent/ # AI Agent SDKs (TypeScript & Python) │ │ ├── client/ # Client SDK (React components, TypeScript) │ │ └── server/ # Server SDK (TypeScript) │ ├── examples/ # Integration examples │ │ └── browser-use-integration/ # Browser-use agent examples │ ├── scripts/ # Utility scripts │ │ ├── create-agent-credentials.js │ │ └── create-*-client.js/py │ └── demo/ # Video demonstrations ├── website-integration-example/ # Website integration example │ └── src/ # Next.js app with Auth Agent integration ├── logo/ # Branding assets └── README.md # This file