auth.md and Agent Registration over OAuth
A technical review of WorkOS's open auth.md proposal, its OAuth building blocks, and why structured metadata must remain authoritative.
auth.md is a WorkOS-authored open proposal for agentic registration. It pairs a procedural Markdown guide with an OAuth-based reference implementation so an agent can authenticate to a service on a user's behalf.
It is not an IETF standard. It doesn't replace OAuth discovery, and the repository's service-specific fields aren't registered protocol requirements. Published OAuth RFCs keep their own standards status; one Internet-Draft in the proposal remains work in progress.
That classification is important because an authentication guide can look authoritative to an agent. Operators and clients need a firm boundary between helpful procedure and machine-validated endpoint truth.
Three roles and several registration paths
The WorkOS material names an agent acting for a user, an agent provider that can mint identity assertions, and a service that accepts an assertion and issues credentials. Its reference implementation demonstrates several paths.
Where an agent provider supports an Identity Assertion Authorization Grant, the agent asks for an audience-specific assertion and presents it to the service. The service verifies that assertion, issues its own identity assertion, and accepts the result in a JWT bearer token exchange.
The identity assertion grant, commonly called ID-JAG, is currently an IETF Internet-Draft. Implementers must track the draft revision and should not describe it as a published RFC.
The reference project also covers a user claim ceremony for an agent that lacks a suitable provider assertion. A service can return a user code and verification URI, allowing the user to authenticate in a separate browser interaction. The agent polls for completion under defined timing and error rules. That pattern draws from the device flow in RFC 8628, while the proposal adds its own registration and claim behavior.
An anonymous registration path can begin with limited pre-claim access and later transfer control through a user claim. This is proposal behavior, not a general OAuth promise. A production service would need explicit rules for pre-claim scopes, account linking, abandoned claims, credential theft, and conflicts between users.
The proposal composes existing OAuth mechanisms
Several published specifications supply the protocol foundation:
- RFC 9728 lets a protected resource identify its resource URL, allowed authorization servers, and supported scopes.
- RFC 8414 publishes authorization-server issuer and endpoint metadata.
- RFC 7523 defines JWT profiles for OAuth client authentication and authorization grants.
- RFC 8628 defines the OAuth device authorization grant and its user-code ceremony.
- RFC 7009 defines token revocation.
The WorkOS reference includes an agent_auth metadata block for its identity, claim, and event endpoints. It also defines custom identity types, grant names, and event values. Those are proposal extensions controlled by the project. A client cannot assume another authorization server implements them merely because it supports OAuth.
The repository currently demonstrates standard and proposal fields together for convenience. A standards-based deployment should still preserve the RFC roles: Protected Resource Metadata is authoritative for the protected resource and its permitted issuers, while RFC 8414 metadata is authoritative for the authorization server. Service-specific registration fields can extend the applicable registry or profile only under a documented interoperability agreement.
What belongs in the Markdown guide
The sample AUTH.md acts like a procedural recipe. That format is suitable for instructions a person or agent must interpret, such as when to surface a user code, how the user completes a claim, which recovery route applies after expiry, and how to explain revocation.
Issuer identifiers, resource identifiers, token endpoints, key-set URLs, supported grants, and scopes should come from structured metadata. A client can compare identifiers, validate URLs, recognize registered fields, and apply profile rules to JSON. Prose is much harder to validate and easier to misread.
If the Markdown guide disagrees with Protected Resource Metadata or authorization-server metadata, stop the flow. Don't repair the mismatch by extracting a plausible endpoint from instructions. The operator may have deployed an old guide, or an attacker may have changed one artifact without changing the other.
The guide also shouldn't ask an agent to weaken OAuth protections. It must not tell a client to skip issuer comparison, disable TLS checks, reuse an assertion for another audience, request every available scope, or send a token to an unvalidated host.
There is no settled requirement that an arbitrary site place this document at a particular path. The WorkOS example references an auth.md URL from proposal metadata. Treat that URL and the document shape as WorkOS proposal material rather than a registered well-known URI.
Version the guide with the service behavior. Test every described branch against production and include a review date. If a registration mode is disabled, remove its instructions in the same release instead of leaving an agent to discover the failure after presenting identity material.
Registration creates durable security obligations
An agentic registration flow can issue credentials that remain useful after the immediate conversation. The service needs to bind each assertion to the intended audience, issuer, subject, expiry, and permitted use. Assertion replay should fail. Tokens need minimum scope, short appropriate lifetimes, secure storage, rotation where relevant, and revocation.
User participation must be visible. A claim page should identify the service, agent, requested authority, and resulting account relationship. User codes need sufficient entropy, attempt limits, expiry, and one-time completion. Polling endpoints need rate limits and the error behavior required by the profile.
Redirects and metadata fetches also cross network boundaries. Constrain HTTPS destinations, public address resolution, response size, and redirect hops. Revalidate the destination after each redirect. Never let prose select an arbitrary token endpoint.
Operations need telemetry for failed assertions, claim attempts, token exchanges, revocations, and unusual scope requests. Logs should exclude access tokens, private assertions, and claim secrets. A compromised key or proposal extension needs a tested rollback path.
TKOResearch's adoption threshold
TKOResearch doesn't operate a public OAuth-protected service that accepts agent registration. Publishing auth.md now would advertise identity acceptance and credential issuance without an issuer, protected-resource document, registration policy, revocation operation, or service owner.
TARE should consider the proposal only after a production authorization surface has exact RFC 9728 and RFC 8414 metadata, named ownership, approved identity issuers, audience rules, minimum scopes, user-visible claim behavior, revocation, monitoring, and interoperability tests. The Markdown guide can then document the human steps that structured metadata cannot express.
Until that service exists, omitting auth.md avoids a false authentication promise. A guide can supplement deployed authority; it cannot create that authority by itself.