An OAuth 2.1 and OpenID Connect authorization server for AI agents, workloads, and MCP resource servers.

简体中文简介 · Getting started · Deployment guide · AWS cost estimates · User guide · Security

---

Watch the 60-second introduction video (MP4)

Agent Auth is a standards-oriented authorization server built for software that acts on behalf of people or other workloads. It gives agents an explicit, auditable way to obtain resource-bound access tokens instead of sharing user credentials or relying on opaque, application-specific authorization.

The project combines a Rust protocol core, AWS and Kubernetes deployments, resource-server SDKs, and a React administration UI. It supports conventional OAuth and OIDC clients while adding first-class authorization boundaries for agents, machine identities, delegation chains, and MCP resources.

Important

The latest stable source release is the publication record. This revision uses version 1.2.0; see its release notes. Semantic Versioning covers the HTTP API described by openapi/openapi.json and the TypeScript and Python resource-server SDK APIs; deployment configuration and persisted data formats are outside that guarantee. Review the conformance matrix, deployment design, and security assumptions before using it in a production environment. Project tests are not a certification by the OpenID Foundation or another standards body.

Current Status

• Release — use the latest stable source release. The v1.2.0 notes describe this revision. Release assets are source archives; Rust crates remain unpublished. The resource-server SDKs are published separately as agent_auth_rs 1.0.2 on npm and PyPI. SDK distribution and release qualification records verified public artifact digests, source/tag identity and independent installation checks for the npm tarball and Python wheel/sdist.
• Repository evidence — every completed row in the conformance matrix must map to exact automated selectors that CI actually runs. Broad suites, comments, and historical results do not count as exact evidence.
• External release gate — the external conformance contract runs the fixed OIDF Basic OP code-flow plan plus project-owned selected RFC 9700 regressions. Non-PASSED official outcomes require explicit, repository-bound, time-limited exceptions; a green gate is not standards-body certification.
• Third-party interoperability — sanitized live evidence from a real Okta SCIM directory job and a real Okta Cross App Access ID-JAG exchange is recorded in the conformance matrix (C12.2 and C13.8). These are recorded runs, not part of the daily external release gate.

Why Agent Auth?

Traditional identity systems generally assume a human user and a pre-registered web application. Agent systems introduce a different set of questions:

• Which agent or workload is requesting access?
• Is it acting for itself, for a user, or through a delegation chain?
• Which resource server may receive the token?
• What scopes and structured authorization constraints apply?
• How can a resource server validate the token without sharing secrets?
• How are tenant, issuer, key, and audit boundaries preserved?

Agent Auth makes these decisions part of the authorization-server contract. Tokens are bound to an explicit resource and audience, subject and actor types are represented directly, and security-sensitive behavior is backed by executable conformance requirements.

Highlights

• OAuth 2.1 and OIDC foundations — authorization code with PKCE, refresh token rotation, discovery, authorization-server metadata, UserInfo, client credentials, device authorization, CIBA, and token exchange.
• Agent and workload identity — authenticate workloads with AWS SigV4, OIDC assertions, SPIFFE JWT-SVIDs, or X.509-SVID mTLS profiles.
• MCP-aware authorization — issue single-audience, resource-bound access tokens and publish protected-resource metadata for MCP resource servers.
• Explicit delegation — represent user, agent, service, grant, actor-chain, scope, and rich-authorization constraints without hiding them in application-specific session state.
• Modern client security — Dynamic Client Registration, RFC 7592 client management, PAR, DPoP, exact redirect validation, and downgrade controls.
• Enterprise integration — upstream OIDC and SAML federation, passkeys, SCIM provisioning, security-event delivery, and administrative workflows.
• Kubernetes deployment — single-tenant PostgreSQL 16+, mounted signing and external secrets, private management, durable workers and pinned GHCR images/Helm chart. Qualification and restore holds are recorded in the delivery ledger.
• AWS-native deployment — Rust on Lambda behind API Gateway and CloudFront, with DynamoDB authority stores, KMS-backed signing, and AWS CDK infrastructure.
• Resource-server SDKs — TypeScript and Python packages for JWT, audience, issuer, scope, DPoP, and discovery validation.
• Executable specification — normative requirements are linked to exact automated test selectors and CI jobs.

For the precise status and evidence for each capability, use docs/CONFORMANCE.md rather than this summary.

Architecture

The Rust protocol and policy core uses storage, signing and transport ports. Local development uses in-memory adapters. Deployed systems select one profile:

• AWS-native: CloudFront and API Gateway route to Lambda runtimes backed by DynamoDB authority stores and KMS signing. CDK supports self-hosted and tenant-aware deployments.
• Kubernetes: one tenant and issuer, HTTPS ingress, separate web/token services, PostgreSQL authority stores, mounted ES256/RS256 keys and external secrets, and durable governance/event/SMTP/SSF workers. Management APIs have private admission; public /admin and /scim routes return 404. SaaS and multi-Region Kubernetes deployment are outside this profile.

Read docs/DESIGN.md for the protocol model and docs/DEPLOYMENT.md for AWS trust boundaries and topology. The PostgreSQL runtime and Kubernetes installation guide describe the portable composition. Installed qualification and the production restore hold remain separate evidence in the delivery ledger.

Quick Start

Prerequisites

• Rust 1.85 or newer
• curl
• jq

Run the local development server

git clone https://github.com/amliuyong/a-auth.git
cd a-auth
cargo run -p agent-auth-http --bin agent-auth-server

The development server listens on 127.0.0.1:8080 and uses in-memory stores; it does not require an AWS account.

In another terminal:

curl --silent http://localhost:8080/.well-known/openid-configuration | jq

Use localhost, not 127.0.0.1, in protocol requests because the local issuer is derived from the validated request host.

The complete local Authorization Code + PKCE walkthrough is in docs/GETTING_STARTED.md.

Deployment

The included AWS CDK application supports a self-hosted deployment and the tenant-aware topology described in the deployment documentation.

Start with a synthesis, which does not deploy resources:

cd infra
npm ci
npm run build
npx cdk synth

Before deploying, read docs/INSTALL_DEPLOY.md. It covers prerequisites, configuration, domains, keys, migration steps, validation, and teardown. AWS deployments can create billable resources.

For single-tenant Kubernetes deployment with PostgreSQL, follow docs/KUBERNETES_INSTALL.md. It covers the pinned GHCR images and Helm chart, mounted signing keys, private management access, configuration, upgrades, and backup/restore disposition.

Repository Layout

Path	Purpose
crates/	Rust protocol, policy, token, authentication, workload, and HTTP runtime crates
infra/	AWS CDK application, deployment configuration, and infrastructure tests
web/	React and TypeScript login, consent, account, and administration UI
sdk/ts/	TypeScript resource-server verification SDK
sdk/python/	Python resource-server verification SDK
openapi/	Generated OpenAPI contract
specs/	Capability index linked to normative conformance evidence
docs/	Architecture, protocols, operations, deployment, and user documentation
e2e/	Local and live-environment acceptance harnesses
.github/conformance/	Requirement inventory, evidence mapping, and exception policy

Development

Enable the repository hook after cloning:

git config core.hooksPath .githooks

Common checks:

cargo fmt --all -- --check
cargo test --workspace --lib --locked

npm ci
npm run lint:markdown

cd infra
npm ci
npm test

The CI workflow also checks Clippy, AWS adapters, exact conformance selectors, the web application, infrastructure, OpenAPI drift, and both resource-server SDKs.

When changing protocol behavior, update the relevant implementation, tests, OpenAPI surface, specification, and conformance evidence together. See CONTRIBUTING.md for the contribution workflow.

Documentation

Document	Start here when you want to...
GETTING_STARTED.md	Run a local flow and choose a role-specific path
PROTOCOLS_101.md	Understand the OAuth, OIDC, MCP, DPoP, CIBA, and SPIFFE concepts
USER_GUIDE.md	Integrate a client, agent, resource server, user, or administrator
FEDERATION_TEMPLATES.md	Configure enterprise OIDC and distinguish draft, network and real-login checks
BRANDING.md	Preview and manage bounded self-hosted login and consent presentation
DESIGN.md	Review protocol invariants, token contracts, and architectural decisions
DEPLOYMENT.md	Understand issuer, tenant, key, migration, and topology boundaries
INSTALL_DEPLOY.md	Build and deploy the AWS infrastructure
KUBERNETES_INSTALL.md	Install the single-tenant Kubernetes + PostgreSQL deployment
AGENT_PAYMENT.md	Authorize one exact agent payment and verify its single execution (controlled channel only)
CONFORMANCE.md	Check normative requirements and their automated evidence
EXTERNAL_CONFORMANCE.md	Review the official OIDF and project regression release-gate contract
CHANGELOG.md	Check release history and user-visible changes

Security

Security vulnerabilities must not be reported in a public issue. Use GitHub private vulnerability reporting as described in SECURITY.md.

Never commit real credentials, tokens, personal data, AWS account identifiers, production domains, or deployment evidence. Examples and tests must use synthetic values.

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md before submitting a change. Contributions that affect wire behavior should include focused tests and corresponding documentation or conformance updates.

简体中文简介

Agent Auth 是一个面向 AI agent、workload 和 MCP Resource Server 的 OAuth 2.1 / OpenID Connect 授权服务器。它重点解决“谁在代表谁、可以访问哪个资源、 经过了怎样的委托链、资源服务器如何独立验证权限”等 agent 授权问题，同时兼容 传统 OAuth/OIDC 客户端。

当前源码版本为 v1.2.0，发布状态以 最新稳定版为准， 变更和升级要求见 v1.2.0 发布说明。 项目采用 Rust 实现协议与策略核心，提供 AWS CDK 部署、 Kubernetes + PostgreSQL 单租户部署、 React 管理界面以及 TypeScript/Python Resource Server SDK。 1.0 起按语义化版本对 HTTP API （openapi/openapi.json）与 TypeScript/Python Resource Server SDK 做兼容承诺， 部署配置与持久化数据格式不在承诺范围内； 生产使用前请审阅 docs/CONFORMANCE.md、 docs/DESIGN.md 和 docs/INSTALL_DEPLOY.md。

60 秒介绍视频见 docs/assets/agent-auth-intro.mp4。 中文读者建议从 docs/GETTING_STARTED.md 开始， 再按角色阅读 docs/USER_GUIDE.md 或部署文档。

License

Licensed under the Apache License 2.0.