OpenID Connect System Design AGENTS.md Template

Overview

Direct answer: This AGENTS.md template codifies an OpenID Connect system design workflow for AI coding agents, detailing roles, handoffs, governance, and production rules to run single-agent and multi-agent orchestration safely and auditable.

This page provides a concrete, copyable operating manual for building and operating an OpenID Connect (OIDC) system with AI coding agents. It governs how agents collaborate to configure, validate, and operate OIDC components such as identity providers, relying parties, clients, tokens, and JWKS handling. It supports both single-agent execution (for simple grant flows) and multi-agent orchestration (for complex, compliant token validation, multi-IdP scenarios, and policy enforcement). This template emphasizes tool governance, human review, and explicit handoffs to ensure secure, maintainable designs.

When to Use This AGENTS.md Template

• You are architecting an OpenID Connect implementation involving multiple services, clients, and IdPs.
• You need clear agent roles, handoffs, and escalation rules to manage token validation and user authentication across services.
• You require explicit memory, source-of-truth, and audit trails for OIDC configuration, tokens, and policy decisions.
• You want to enforce safe tool usage, secret handling, and production safeguards in an AI-assisted design process.
• You are shipping a production-grade OIDC integration and need a rigorous operating model to prevent context drift and architecture drift.

Copyable AGENTS.md Template

# AGENTS.md

Project role: OpenID Connect system design for an API ecosystem, coordinating AI coding agents to provision, validate, and operate OIDC flows with PKCE, nonce handling, and token validation.

Agent roster and responsibilities:
- Planner: defines scope, success criteria, and sequence of OIDC tasks (discovery, client registration, provider config, JWKS handling, token validation rules).
- Implementer: encodes OIDC workflow logic, integrates with IdP metadata, builds token validation, and configures clients and redirect URIs.
- Researcher: gathers IdP capabilities, PKCE requirements, JWKS rotation policy, and security considerations (nonce, state, replay protection).
- Reviewer: reviews architectural correctness, security alignment, and compliance with enterprise policies.
- Tester: validates login flows, token exchange, and edge cases (expired tokens, nonce reuse, clock skew).
- Domain Specialist (Security): ensures threat modeling, key rotation, and secrets handling meet policy.

Supervisor or orchestrator behavior:
- The Orchestrator coordinates planning, execution, reviews, and approvals across roles.
- It maintains a single source of truth (discovery document, provider metadata, client config) and propagates changes through the pipeline.

Handoff rules between agents:
- Planner → Implementer: hand off scoped tasks and acceptance criteria with provider metadata and initial client config.
- Implementer → Reviewer: present implemented flows, code, and evidence of correctness.
- Reviewer → Tester: authorize test plans and verify test data and environments.
- Tester → Domain Specialist: request security review for identified risks.
- Domain Specialist → Plamer: confirm changes to policy or guidance.

Context, memory, and source-of-truth rules:
- Context: current IdP configuration, issuer, JWKS URL, client metadata, PKCE methods, and token validation rules.
- Memory: persist decisions, encountered edge cases, and test outcomes across tasks for traceability.
- Source of Truth: OIDC discovery document, provider metadata, JWKS, client registry, and policy documents.

Tool access and permission rules:
- Tools: HTTP client, secret store, code repository, CI/CD, logging/observability.
- Access: secrets only via a managed secret store; no plaintext in logs; tokens never persisted in memory beyond runtime scope.
- Production access requires approvals and guardrails; avoid blast-radius changes without review.

Architecture rules:
- Use Authorization Code flow with PKCE for public clients; ensure proper redirect URIs and client types.
- Separate concerns: discovery/configuration, token validation, and policy decisions in discrete components.
- Validate issuer, audience, expiry, nonce, and at-rest/in-transit protection.

File structure rules:
- Keep only workflow-relevant folders; avoid unrelated tech stacks.
- Example:
  oidc-workflow/
    planners/
    implementers/
    reviewers/
    testers/
    researchers/
    domain-specialists/
    configs/
    docs/
    tests/

Data, API, or integration rules:
- Always fetch discovery from https:///.well-known/openid-configuration and validate issuer.
- Verify JWKS alignment with signing keys and rotate keys safely.
- Validate token claims (aud, iss, exp, iat) and enforce nonce on authentication responses.

Validation rules:
- Token validation passes all security checks; failing validation should abort flows with clear errors.
- All changes go through code review and automated tests before deployment.

Security rules:
- Secrets must be stored in a dedicated vault; do not log secrets.
- Rotate signing keys on a defined cadence; enforce short-lived tokens where possible.
- Enforce least privilege for agents' API access.

Testing rules:
- Unit tests for token validation logic; integration tests against a mock IdP; end-to-end tests for typical login flows.
- Run tests in CI on PR; require green tests before merge.

Deployment rules:
- Deploy changes to staging first; require security sign-off for production changes.
- Monitor token-related metrics and alert on anomalies.

Human review and escalation rules:
- Escalate to Security Lead if a critical flaw is found; require dual approvals for production changes affecting authentication.

Failure handling and rollback rules:
- If IdP is unavailable, fail closed and present a clear incident, revert to last good config if safe.
- Roll back changes to discovery/config until verification passes.

Things Agents must not do:
- Do not bypass validation, skip code review, or modify security-critical configurations without approval.
- Do not log tokens or secrets; do not perform production changes without test pass.
- Do not introduce new IdPs or flows without stakeholder sign-off.

Recommended Agent Operating Model

The agent roles described above collaborate under an Orchestrator that enforces decision boundaries: Planner defines scope and gates; Implementer builds the OA (OpenID Connect) flows; Reviewer validates; Tester exercises flows; Researcher informs security; Domain Specialist ensures policy compliance. Escalation paths are explicit and time-bounded. Decisions about PKCE methods, token validation claims, and IdP changes require dual approvals when impact is production-critical.

Recommended Project Structure

oidc-workflow/
  planners/
  implementers/
  reviewers/
  testers/
  researchers/
  domain-specialists/
  configs/
  docs/
  tests/

Core Operating Principles

• Operate with explicit memory and a single source of truth for all OIDC config and policy decisions.
• Ensure least privilege and strict separation of concerns across agents.
• Require validation and human review for security-critical changes.
• Audit all agent decisions with traceable evidence and test results.

Agent Handoff and Collaboration Rules

Plan to Implementer handoffs must include evaluation criteria, provider metadata, and initial client configuration. Implementer must include evidence of correct token validation logic. Reviewer may require additional security checks before moving to testing. Tester re-validates after any policy change or IdP update. Domain Specialist must sign off on any changes impacting security posture.

Tool Governance and Permission Rules

Use a secret store for credentials; avoid plaintext storage. All API calls to IdP and token validation endpoints must go through controlled agents with access controls. Production changes require approvals, feature flags, and monitored rollouts. Do not bypass any gate when handling keys or secrets.

Code Construction Rules

• Follow the OIDC specification strictly for flows used (e.g., Authorization Code with PKCE).
• Validate issuer, audience, and nonce consistently across environments.
• Keep client metadata and provider configuration immutable post-deploy unless changes are tested and approved.
• Write idempotent operations where possible; log traceable events only.

Security and Production Rules

• Enable key rotation and verify JWKS signatures securely.
• Enforce short-lived access tokens and rotate refresh tokens per policy.
• Do not expose discovery metadata publicly beyond necessary endpoints.
• Implement strict CORS and redirect URI validation for all clients.

Testing Checklist

• Token validation unit tests cover issuer, audience, exp, iat, nonce.
• Integration tests simulate IdP discovery, JWKS rotation, and client registration.
• End-to-end tests verify login flows, consent, and token exchange.
• Security tests for replay protections and clock drift.
• Regression tests for policy modifications and IdP changes.

Common Mistakes to Avoid

• Skipping nonce validation or PKCE verification.
• Bypassing security reviews for production changes.
• Logging tokens or secrets in plain text or verbose logs.
• Treating discovery data as immutable without governance.

Related implementation resources: AI Use Case for Xero Reports and Business Performance Insights and AI Use Case for Visa Consultants Using Government Portals To Check Application Documents for Missing Requirements.

FAQ

What is the purpose of this AGENTS.md Template?

It provides a concrete operating manual to govern an OpenID Connect system using AI coding agents, covering roles, handoffs, tool governance, and security policies for single-agent and multi-agent orchestration.

Which OpenID Connect flows are covered?

Primary focus is Authorization Code flow with PKCE for public clients; other flows may be added with proper gating and tests.

How are agent handoffs handled in this template?

Handoffs follow a defined chain: Planner → Implementer → Reviewer → Tester → Domain Specialist; with documented acceptance criteria and evidence required at each step.

What constitutes the source of truth?

The OIDC discovery document, provider metadata, JWKS, client registry, and policy documents constitute the single source of truth for configuration and decision-making.

What happens on a failed IdP or key rotation?

Fail closed, revert to last known-good configuration, escalate to Security Lead, and execute a staged recovery plan guarded by approvals.