Network Working Group P. White
Internet-Draft 13 May 2025
Intended status: Informational
Expires: 14 November 2025
AAuth - Agentic Authorization OAuth 2.1 Extension
draft-patwhite-aauth-00
Abstract
This document defines the *Agent Authorization Grant*, an OAuth 2.1
extension for *confidential agent clients*—software or AI agents with
long-lived identities—to request end-user consent and obtain access
tokens via HTTP polling, Server-Sent Events (SSE), or WebSocket. It
is heavily inspired by the core dance of the OAuth 2.0 Device
Authorization Grant (RFC 8628) but is tailored for agents either long
lived identities, and introduces scoped, natural-language
descriptions and a reason parameter provided by the agent.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 14 November 2025.
Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved.
White Expires 14 November 2025 [Page 1]
Internet-Draft AAuth May 2025
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions and Requirements Language . . . . . . . . . . . . 2
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2
4. Agent Authorization Grant . . . . . . . . . . . . . . . . . . 3
4.1. Agent Authorization Request . . . . . . . . . . . . . . . 3
4.2. User Approval User Approval . . . . . . . . . . . . . . . 4
4.3. Token Retrieval . . . . . . . . . . . . . . . . . . . . . 4
4.4. Error Handling & Back-Off . . . . . . . . . . . . . . . . 5
5. Security Considerations. Security Considerations . . . . . . 6
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6
7.1. Normative References . . . . . . . . . . . . . . . . . . 6
1. Introduction
OAuth 2.1 provides a framework for delegated access via bearer
tokens. In modern AI architectures, *agents*—autonomous software
processes—act on behalf of users or other agents. This extension
defines the *Agent Authorization Grant*, enabling agents with long
lived identities to request a delegated token with human-in-the-loop
consent, and to receive tokens asynchronously via polling, SSE, or
WebSocket, while leveraging natural-language scope descriptions
published by resource servers.
2. Conventions and Requirements Language
The key words “MUSTâ€, “MUST NOTâ€, “REQUIREDâ€, “SHALLâ€, “SHOULDâ€,
“SHOULD NOTâ€, “RECOMMENDEDâ€, “MAYâ€, and “OPTIONAL†are to be
interpreted as described in [RFC2119].
3. Terminology
* *Agent*: A confidential client (software or AI) with a stable,
long-lived identity (client_id).
* *Authorization Server (AS)*: Issues request_code handles, manages
user consent, and issues access tokens.
White Expires 14 November 2025 [Page 2]
Internet-Draft AAuth May 2025
* *Resource Server (RS)*: API server that protects resources via
OAuth tokens and publishes human-readable scope descriptions at
/.well-known/aauth.json.
* *request_code*: Opaque handle returned by the AS to correlate an
agent’s request with subsequent token retrieval.
* *reason*: Human-readable explanation provided by the agent, shown
to the user during consent.
* *scope_descriptions*: Natural-language text for each requested
scope, fetched from the RS’s discovery document.
4. Agent Authorization Grant
| This flow is modeled on the OAuth 2.0 Device Authorization Grant
| (RFC 8628) but is tailored for *confidential agent clients* with
| long-lived identities, and optimized for performant delivery of
| tokens to the agent.
4.1. Agent Authorization Request
An agent requests user approval by authenticating and POSTing to
/agent_authorization:
POST /agent_authorization HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>
grant_type=urn:ietf:params:oauth:grant-type:agent_authorization&
scope=urn:example:resource.read urn:example:resource.write&
reason="<human-readable reason>"
* *grant_type*: MUST be urn:ietf:params:oauth:grant-
type:agent_authorization.
* *scope*: Space-delimited list of scope URIs.
* *reason*: Concise, human-readable explanation provided by the
agent; MUST be echoed verbatim by the AS.
Upon receipt, the AS:
1. *Validates* client credentials.
2. *Fetches* each scope’s description from the target RS’s
https://{rs}/.well-known/aauth.json#scope_descriptions.
3. *Returns:*
White Expires 14 November 2025 [Page 3]
Internet-Draft AAuth May 2025
{
"request_code": "GhiJkl-QRstuVwxyz",
"token_endpoint": "https://auth.example.com/token",
"poll_interval": 5,
"expires_in": 600,
"poll_sse_endpoint": "https://auth.example.com/agent_authorization/sse",
"poll_ws_endpoint": "wss://auth.example.com/agent_authorization/ws"
}
4.2. User Approval User Approval
The AS is fully responsible for user interaction:
1. *Initiate* the consent review flow with the user. This spec does
not specify how this occurs, it could be through an app, a chat
client, or some other mechanism.
2. *Display* the reason and each scope_descriptions entry to ensure
the user has all the information necessary to assess the consent
request.
3. *Authenticate* the user (including MFA) and, upon consent, bind
approval to request_code.
| _Note:_ The agent does *not* handle redirects or UI rendering—it
| passively awaits token availability.
4.3. Token Retrieval
After user approval, the agent obtains its access token via one of:
1. *HTTP Polling*
POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>
grant_type=urn:ietf:params:oauth:grant-type:device_code&
device_code=GhiJkl-QRstuVwxyz
_Pending_: {"error":"authorization_pending"} _Success_: Standard
OAuth 2.x token response.
2. *Server-Sent Events (SSE)*
GET /agent_authorization/sse?request_code=GhiJkl-QRstuVwxyz HTTP/1.1
Host: auth.example.com
Authorization: Bearer <agent_jwt>
Accept: text/event-stream
White Expires 14 November 2025 [Page 4]
Internet-Draft AAuth May 2025
On approval:
event: token_response
data: {"access_token":"<JWT>","expires_in":900,"issued_token_type":"urn:ietf:params:oauth:token-type:jwt"}
3. *WebSocket*
GET /agent_authorization/ws?request_code=GhiJkl-QRstuVwxyz HTTP/1.1
Host: auth.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Protocol: aauth.agent-flow
Authorization: Bearer <agent_jwt>
On open:
{
"type": "token_response",
"access_token": "<JWT>",
"issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
"expires_in": 900
}
4.4. Error Handling & Back-Off
* *HTTP Polling*: MUST honor error="slow_down" with Retry-After
headers; return standard OAuth error codes such as
authorization_pending, access_denied, or expired_token.
* *Server-Sent Events (SSE)*:
- On token response:
event: token_response
data: {"access_token":"<JWT>","expires_in":900,"issued_token_type":"urn:ietf:params:oauth:token-type:jwt"}
- On user rejection:
event: error
data: {"error":"access_denied","error_description":"The user denied the request."}
- On request expiration:
event: error
data: {"error":"expired_token","error_description":"The request_code has expired."}
* *WebSocket*:
White Expires 14 November 2025 [Page 5]
Internet-Draft AAuth May 2025
- On token response:
{"type":"token_response","access_token":"<JWT>","issued_token_type":"urn:ietf:params:oauth:token-type:jwt","expires_in":900}
- On user rejection or expiration:
{"type":"error","error":"access_denied","error_description":"The user denied the request."}
{"type":"error","error":"expired_token","error_description":"The request_code has expired."}
* *Security*: All endpoints SHOULD enforce TLS and require client
authentication.
5. Security Considerations. Security Considerations
* Agents MUST protect their long-lived credentials.
* Short-lived request_code and tokens limit replay risk.
* RS scope descriptions should not expose sensitive system details.
* Implement rate-limiting on polling and push channels to prevent
abuse.
6. IANA Considerations
This document registers the following new OAuth grant type:
urn:ietf:params:oauth:grant-type:agent_authorization
7. References
7.1. Normative References
* [RFC2119] Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119.
* [RFC8628] Wahl, "OAuth 2.0 Device Authorization Grant", RFC 8628.
* [RFC8693] Jones & Campbell, "OAuth 2.0 Token Exchange", RFC 8693.
White Expires 14 November 2025 [Page 6]