User-Managed Access (UMA) 2.0 Profile for Autonomous Agents

1.1. Design Rule

This profile uses UMA 2.0's wire surface wherever it fits and makes each departure explicit. The following are used as [UMAGrant] specifies them:¶

• the urn:ietf:params:oauth:grant-type:uma-ticket grant type;¶

• the need_info and request_submitted responses;¶

• the permissions array of the introspection response.¶

Over HTTP the challenge keeps UMA 2.0's WWW-Authenticate: UMA header (Section 3.2), but the header is no longer its only encoding (Section 3.1).¶

Section 12 lists every departure. Anything not listed there is intended to be UMA 2.0 as specified.¶

1.2. Relationship to Other Authorization Work

GNAP [RFC9635] addresses a comparable topology, including a resource owner who is not the end user and is contacted asynchronously (Section 1.6.4 of [RFC9635]). It does not define terms that the owner publishes and the client signs, which is the central addition of this set ([U4ATerms]). A binding of this profile to GNAP is possible.¶

DPoP [RFC9449] binds an access token to a key. This profile uses HTTP Message Signatures [RFC9421] instead, because the signature covers the request as well as binding the token, and because the same mechanism authenticates several parties in this set.¶

1.3. Specification Set

This document is the core of a set. [U4ATerms] and [U4AFedAuthz] are REQUIRED to implement alongside it; this document together with those two constitutes the UMA 2.0 profile for autonomous agents.¶

[U4APolicy], [U4ALineage], [U4AMultiParty] and [U4AOwner] are OPTIONAL extensions of this document. [U4AMCP] binds this profile to a transport; other bindings are possible. [U4AAAuth] specifies one credential an agent may identify itself with; others serve.¶

1.4. Roles

The roles of [UMAGrant] apply. This document uses UMA's entity terms: the software making a request is the client, and the party on whose behalf it acts is the requesting party. Where the client is an autonomous agent, the requesting party is the person or organization accountable for it, and is not necessarily present.¶

The UMA Work Group's legal work names the parties responsible for these entities: the party that seeks access through a client is the Requesting Agent, and the party responsible for the client software is the Client Operator. This document does not use "requesting agent" to mean software.¶

The following roles are added:¶

Client operator:

The party that runs a client and publishes a directory of the keys its clients hold, corresponding to the Client Operator. Where this document set says "operator" alone, it means the client operator. The owner may act against a client operator as a whole (see [U4APolicy]); a client operator is never an authorization input on its own.¶

Enforcement point:

The component that performs the resource server's jobs defined by [UMAFedAuthz]: holding the protection API access token, obtaining a permission ticket, introspecting, and refusing. [UMAFedAuthz] Section 1.4 describes these jobs without naming the component that performs them. An enforcement point MAY be a gateway in front of the resource, or the resource itself.¶

1.5. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

Base64url encoding is as defined in [RFC7515] Section 2, without padding.¶

The notation s256(x) denotes the string "s256:" followed by the base64url encoding, without padding, of the SHA-256 digest of the octets x. Where x is a JSON value, the octets are its serialization under the JSON Canonicalization Scheme [RFC8785], so that independent implementations compute the same digest.¶

The notation jkt(k) denotes the string "jkt:" followed by the JWK Thumbprint [RFC7638] of the JSON Web Key k. The value after the prefix is the same thumbprint DPoP [RFC9449] carries in its jkt confirmation method; the prefix marks it as a handle rather than a confirmation.¶

3.1. Parameters, Not a Header

[UMAGrant] Section 3.2 requires the resource server to return an HTTP 401 with a WWW-Authenticate: UMA header. This profile requires the parameters and lets each binding say how they travel.¶

An enforcement point MUST convey the following parameters when it refuses a request for want of authorization:¶

realm:

REQUIRED. As [RFC6750].¶

error:

REQUIRED. The value insufficient_authorization.¶

as_uri:

REQUIRED. The issuer identifier of the authorization server that decides access to this resource for this owner.¶

ticket:

REQUIRED. The permission ticket, as [UMAGrant].¶

resource_metadata:

REQUIRED. The URL of the protected resource metadata document [RFC9728] that describes this resource, as [RFC9728] Section 5.1. An enforcement point MUST name the document for the resource identifier the request was made to, formed as [RFC9728] Section 3 forms it, and not the document of another identifier the same resource is reachable by; a client following the pointer is required by [RFC9728] Section 3.3 to reject any other.¶

scope:

OPTIONAL. A space-delimited list of the scopes that would satisfy the attempted access, as [RFC6750] Section 3.¶

authorization_remediation:

REQUIRED. See Section 3.4.¶

A binding of this profile MUST define how these parameters are carried, and MUST carry all of those marked REQUIRED. The HTTP binding is given in Section 3.2; [U4AMCP] defines a binding for a transport that has no status line to decorate.¶

The reason for the narrowing is that mandating the header excludes the deployments most likely to adopt this profile. An enforcement point running in-process inside the resource returns a domain result, not a status line; a JSON-RPC method handler has nowhere to put a WWW-Authenticate. Both encodings run in the reference implementation against one authorization server, and one client reads both.¶

3.2. The HTTP Binding

Over HTTP, an enforcement point MUST return 401 Unauthorized with a WWW-Authenticate header whose auth-scheme is UMA and whose auth-params are the parameters of Section 3.1:¶

HTTP/1.1 401 Unauthorized
WWW-Authenticate: UMA realm="alice-vault",
  error="insufficient_authorization",
  as_uri="https://alice-as.example",
  ticket="MWRlNzE4ZjgtMGY0OS00NDg2",
  resource_metadata="https://rs.example/.well-known/
    oauth-protected-resource/mcp",
  scope="trades:execute",
  authorization_remediation="eyJhdXRob3JpemF0aW9uX2RldGFpbHMi..."

3.3. Refusals That Are Not Challenges

Some refusals cannot be resolved by negotiating: the owner has ended the relationship, the request was malformed, or the grant was spent. A challenge there would send the client round a negotiation whose outcome is settled. An enforcement point refusing for such a reason MUST NOT include a challenge, and over HTTP MUST answer with the status below and a JSON object whose error member is the value below and which MAY carry error_description:¶

invalid_token:

1. The token was not presented as a proof-of-possession token, or proof of possession failed (Section 6.1).¶

consequence_changed:

1. The operation now declares a consequence the grant was not issued against (Section 7.2).¶

access_revoked:

1. Introspection gave a terminal reason ([U4AFedAuthz] Section 5); the owner, or a layer above her, has settled it, and renegotiating cannot change it.¶

already_consumed:

1. A single-use grant was spent by another request (Section 8.3).¶

operation_required, operation_mismatch:

1. The grant is bound to no operation, or to a different one (Section 7.3).¶

invalid_origin:

1. The request came from an origin the enforcement point does not serve.¶

request_body_too_large:

1. The body was, or may have been, cut short before the enforcement point read it.¶

temporarily_unavailable:

1. The authorization server could not be asked; the client MAY retry the same request.¶

Every value above except temporarily_unavailable is terminal for the token presented: the same request with the same token will be refused the same way.¶

A binding defines how these travel where there is no status line, and an extension or binding MAY add values for refusals of its own. A document that adds a value MUST say whether it is terminal. A client that receives a value it does not recognise MUST treat it as terminal and MUST NOT send the same request with the same token again. Treating an unknown value as retryable turns every value a client predates into a loop.¶

3.4. Structured Remediation

authorization_remediation is the parameter of [I-D.ietf-oauth-rar-metadata-remediation], carrying the same base64url-encoded JSON object that draft defines, with two additional members. The object has:¶

authorization_details:

REQUIRED. An array of authorization detail objects [RFC9396] describing what was attempted.¶

authorization_reference:

REQUIRED. s256 over authorization_details, serialized as [RFC8785].¶

authorization_server:

REQUIRED by this profile. The issuer identifier of the authorization server that decides. Same value as the as_uri parameter.¶

ticket:

REQUIRED by this profile. Same value as the ticket parameter.¶

{
  "authorization_details": [{
    "type": "https://u4a.ai/spec/core/1.0#tool-call",
    "locations": ["https://rs.example"],
    "identifier": "alice-vault/execute_trade",
    "actions": ["execute_trade"],
    "datatypes": ["trades:execute"]
  }],
  "authorization_reference":
    "s256:ij_r5Jn2rOT7fL8gSvNaOY1XBnRZnWOwasceTRKB42E",
  "authorization_server": "https://alice-as.example",
  "ticket": "MWRlNzE4ZjgtMGY0OS00NDg2"
}

Those two additional members are what make a decision by a third party possible. [I-D.ietf-oauth-rar-metadata-remediation] hands the client a template to submit to its own authorization server, which cannot work when the resource belongs to someone else and the client's authorization server has no standing to grant. Naming the owner's authorization server, and handing back a ticket rather than a template, is the whole of the difference: the client authors nothing and cannot widen what it was given.¶

Emitting the [RFC9396] vocabulary costs an enforcement point nothing, since it already knows the resource identifier and the scopes, and buys three things. A client that implements [I-D.ietf-oauth-rar-metadata-remediation] can read most of the challenge without knowing UMA. A downstream policy engine receives typed fields rather than only a digest. And authorization_reference lets a client holding many grants decide whether it already has one for this shape without parsing the details.¶

3.5. Corroborating the Authorization Server

A client MUST fetch the resource's metadata from the URL [RFC9728] Section 3 forms from the resource it called, and MUST refuse a challenge whose resource_metadata names any other URL. It MUST verify that the document's resource member identifies the resource being accessed as required by [RFC9728] Section 3.3, and MUST refuse a challenge whose as_uri does not appear in that document's authorization_servers array.¶

The URL is formed rather than followed because the challenge is the thing being checked. A forged challenge can name a document on the forger's own host that lists the forger's authorization server, and a client that fetched it would corroborate the forgery against itself.¶

Without this, the only statement of which authorization server decides is an unauthenticated header on a refused request. With it, the challenge gains a second witness anchored in the resource's own TLS-protected origin. The challenge remains authoritative for the ticket, which is the one value the metadata document cannot carry.¶

4.1. Claim Token Formats

Where [UMAGrant] lets the authorization server name acceptable claim token formats, this profile additionally lets it proffer the claim's content. That extension is specified in [U4ATerms] and is REQUIRED to implement.¶

An authorization server MAY accept other claim token formats alongside it. One is worth naming because it is the case an enterprise deployment reaches for first: an identity assertion authorization grant [I-D.ietf-oauth-identity-assertion-authz-grant] MAY be accepted as a claim_token with claim_token_format of urn:ietf:params:oauth:token-type:id-jag, in which case the authorization server MUST treat it as a claim about identity and reach, and MUST NOT treat it as conferring access.¶

A client MUST send the credentials it exchanges for such an assertion only to the identity provider they belong to, as configured at the agent, and MUST NOT send them to a provider or token endpoint that only the authorization server's request names. The authorization server says which provider it will believe. If it could also say where the agent's credentials go, any resource an agent visited could collect an employee's token and the application's secret.¶

Presenting the same assertion as a jwt-bearer grant would have the identity provider's assertion produce the access token directly, which makes the identity provider the deciding party over a resource it does not own. An identity assertion proves who an agent acts for and carries no entitlement of its own, which is what a UMA claim is for. Where both are demanded, identity is demanded first, because which terms apply follows from which party the agent acts for.¶

4.2. Responses

The authorization server's responses are those of [UMAGrant] Sections 3.3.5 and 3.3.6. Two are constrained by this profile.¶

A request_submitted response indicates that the owner has been asked and has not yet answered. The authorization server MUST distinguish two kinds of pending request, and MUST make the kind available to the owner's decision surface:¶

connection:

The client has no standing relationship with this owner. The question put to the owner is whether to have one. See Section 9.¶

operation:

The client has a standing relationship, and the owner's policy requires her to answer for this particular access.¶

A request_denied response MAY carry an error_description. Where the refusal was reached without evaluating the owner's policy — because a quota was exhausted or the operator was blocked — the authorization server SHOULD say so, so that a well-behaved client can distinguish a refusal it might overcome from one it cannot.¶

4.3. Waiting

request_submitted is a state to render, not a call to hold open. A client that can express waiting to its own user SHOULD hand the wait up rather than block, and a binding SHOULD define how. The decision belongs to the owner either way; what changes is whether the requesting party's client hangs on it.¶

A binding that surfaces the wait MUST be able to say that the party being waited on is not the requesting party's own user, and that the client MUST NOT attempt to satisfy the wait from that user. A wait that cannot name its subject will be answered by the wrong person.¶

5.1. Identity Levels

A client presents itself at exactly one of two levels. The level determines the shape of the standing connection handle and nothing else.¶

Pseudonymous:

The client presents a bare public JWK [RFC7517]. The key is the identity. The connection handle is jkt(k).¶

Identified:

The client presents a credential from an issuer asserting its identity and binding it to a key — for example an aa-agent+jwt as defined by [I-D.hardt-oauth-aauth-protocol], whose cnf.jwk is the signing key, and accepted as [U4AAAuth] specifies. The authorization server MUST verify that credential against keys published by its issuer, MUST require that the issuer identifier use the https scheme, and MUST derive the connection handle from the issuer and subject rather than from the key. The issuer MUST qualify the handle whole, including any path. The handle MUST be the subject, followed by @ and the issuer identifier with its scheme and any trailing / removed, unless the subject already ends with that suffix, in which case the handle is the subject.¶

The handle for an identified agent MUST NOT be derived from its key. Issuers that attest agents commonly bind a fresh key per session; a thumbprint-keyed relationship forgets such an agent on every run, which presents to the owner as an agent she has approved asking to be approved again.¶

Qualifying by the issuer's host alone is the natural shortcut and it merges strangers. A multi-tenant identity provider commonly serves every tenant from one host and tells them apart by path, so two tenants' agents with the same subject would be one connection, sharing its standing and the owner's approvals.¶

Which issuers an authorization server will believe is deployment policy, not a wire-protocol rule. This profile deliberately specifies no issuer allow-list, and a deployment MUST supply one.¶

5.2. Descriptive Metadata

A client MAY additionally present descriptive metadata, so that an owner who has never met it can be told something true about it:¶

• a client identifier that is an https URL resolving to a client ID metadata document [I-D.ietf-oauth-client-id-metadata-document], which the authorization server MUST resolve and MUST reject unless the document's own client_id matches the URL it was fetched from;¶

• a Signature-Agent [I-D.meunier-webbotauth-registry] naming a directory of keys the operator publishes.¶

Both travel in the protected header of the agreement ([U4ATerms]), as the members client_id and signature_agent, so the agreement's signature covers them. A client that also sends a Signature-Agent header on a request to the resource MUST cover it with that request's signature (Section 6.1). The operator is the origin of the client identifier; a signature_agent directory at any other origin attests to nothing, since a client could otherwise name a directory it controls and vouch for itself.¶

Neither is an authorization input. The key that verifies a request is always the one confirmed by the grant, the connection handle is unchanged by the presence or absence of either, and an authorization server MUST NOT admit a request it would otherwise refuse on the strength of descriptive metadata alone. Failure to resolve descriptive metadata MUST leave the request where it was rather than refusing it; an operator's outage is not evidence about a client.¶

A metadata document proves only that it claims its own URL. Anyone can publish one, so resolving it establishes a name to display and nothing more. What raises the metadata above a name is the operator directory, which the client does not control — see [U4APolicy].¶

6.1. The Message Signature Profile

Proof of possession uses HTTP Message Signatures [RFC9421].¶

A signature MUST cover at least the components "@method", "@authority", "@path" and "authorization". A signer MAY cover more, and a verifier MUST accept a superset rather than requiring an exact set.¶

On a request that carries no Authorization header, such as a resource server introducing itself or an owner's own signed request, the "authorization" component is covered with the empty string as its value, so the covered set is the same on every request. [RFC9421] Section 2.5 would otherwise treat covering an absent field as an error; this is a departure from it, and the signer and the verifier apply it identically.¶

Requiring an exact list is the intuitive implementation and it is wrong. It makes this profile and [I-D.ietf-webbotauth-httpsig-protocol] unable to coexist on one request, because each adds a component the other did not expect. Covering "authorization" is the security property; an exact list was never one.¶

A verifier MUST reconstruct the signature base using the @authority value it is configured with, and MUST NOT take it from the Host header or from any forwarded header. An authority read from the request is an authority the caller chose. This is a security rule and a portability rule with one cause: an enforcement point that recovers its authority from the routing layer breaks silently when the routing layer changes, with signatures failing to verify for a reason nothing in its logs names.¶

A verifier MUST echo the received @signature-params value verbatim when reconstructing the base, rather than re-serializing it from parsed components.¶

The algorithm is the one the verifying key is registered for, never the one the signature parameters or a header name. A signature whose alg parameter, where present, disagrees with its key MUST be refused.¶

A signature MUST carry the created parameter, and a verifier MUST refuse one whose created is further from its own clock than a window it is configured with, in either direction. The window SHOULD NOT exceed five minutes; the reference uses sixty seconds. Where expires is present the verifier MUST refuse a signature past it. A signature without created is refused rather than treated as fresh, since otherwise a captured request is valid for as long as the key is.¶

A signed request that changes the owner's state — any owner request other than a read — MUST NOT be accepted twice. The authorization server keeps each such signature it accepts for at least twice the window and refuses a second presentation. The signer of such a request SHOULD include a fresh nonce parameter: Ed25519 is deterministic and created counts seconds, so the same request sent twice within a second would otherwise carry the same signature and the second would be refused as a replay. A request to the protected resource is not held to this: a client that needs an operation performed at most once asks for a single-use grant (Section 7.3), whose consumption is the replay control.¶

6.2. Covering the Body

Where a request carries meaning in its body, the signature MUST cover a Content-Digest [RFC9530] header, and the verifier MUST recompute the digest from the received body as well as verifying the signature over it.¶

A request carries meaning in its body whenever it has one. That includes every tool call, whose operation and arguments are in the body, and every request to the owner or protection API that sends a body.¶

The four required components say who is asking and what they are asking of. They say nothing about the bytes. That is adequate for a request whose meaning is in its URL and unsafe for one whose meaning is in its body — and the endpoints where an owner says yes or no are exactly the latter. Without this, an intermediary can leave the signature untouched and change the word.¶

These are two obligations, not one. Recomputing the digest from the received body without reading the header is safe and is not conformant, and would reject any third-party signer whose serialization differs. A verifier MUST be able to require the digest rather than merely accept it when present, since a signer that omits it must not thereby escape the check.¶

An enforcement point MUST check a covered Content-Digest against the body it received, and MUST refuse a request whose signature covers one when it has no body to check it against. Covering the digest is the signer's statement that the bytes matter; an enforcement point that verifies the signature and never reads the body accepts that statement without testing it.¶

7.1. The Requesting Party Token

On success the authorization server responds as [UMAGrant] Section 3.3.5, with token_type of PoP:¶

{
  "access_token": "eyJ0eXAiOiJhdCtqd3QiLCJhbGciOiJFZERTQSIs...",
  "token_type": "PoP",
  "expires_in": 3600
}

A client presents the token in the Authorization header as PoP followed by a space and the token, on a request signed as Section 6.1 specifies. The PoP scheme is this profile's; it is not registered in the HTTP Authentication Scheme Registry, and a binding that carries the token elsewhere says where.¶

The requesting party token MUST be a JWT access token as [RFC9068] specifies, with typ of at+jwt, signed by the authorization server, and MUST carry:¶

iss, aud, jti, exp, iat:

REQUIRED, as [RFC9068]. aud names the resource server the token is for; jti is what consumption is recorded against.¶

sub, client_id:

REQUIRED. Both are the connection handle of Section 5.1. The client is both the software acting and the party asking, and the handle is the name the owner's authorization server knows it by.¶

cnf:

REQUIRED. A confirmation claim whose jwk member is the public key the client must prove possession of. This is the key that signed the claim token, and the key the enforcement point verifies requests against.¶

permissions:

REQUIRED. The array defined by [UMAFedAuthz] Section 5.1.1 — each element carrying resource_id, resource_scopes and OPTIONAL exp, iat and nbf — carried here as a claim rather than being visible only through introspection.¶

owner:

REQUIRED. The resource owner on whose behalf this token was issued. See Section 11.¶

contract:

REQUIRED where the grant was issued on an agreement under [U4ATerms]. s256 over the agreement's JWS compact serialization, the same value the receipt of [U4ATerms] carries as agreement.¶

consequence:

REQUIRED where the resource server declared one for the operation ([U4AFedAuthz]) at the time the grant was issued. The class the owner's authority answered against.¶

clearance:

REQUIRED where the owner's policy required an attestation from a party other than the requesting one ([U4APolicy]). It MUST be a digest over the attested facts and MUST NOT carry the facts themselves: that a clearance was checked is the enforcement point's business, and what it said is the subject's.¶

A bearer requesting party token is a credential that works for whoever picks it up, which is an unreasonable thing to hand software that makes thousands of calls across networks it does not control. Carrying permissions inline lets an enforcement point see what was granted without a round trip; introspection remains the authority on whether the grant is still live, which is a different question and the one that changes.¶

7.2. Consequence

Where the grant carries a consequence and the resource server declares one for the operation at the time of the call, an enforcement point MUST refuse the request if the declared class now leaves less remedy than the class the grant carries. The owner's authority answered a question about the operation as it was described; a resource that re-describes it afterwards is asking a different question, and the answer to the first does not carry over.¶

An enforcement point MUST NOT refuse a grant that carries no class. A deployment that describes its operations for the first time would otherwise invalidate every grant standing at that moment, which is a cost paid by owners for an improvement nobody asked them about.¶

7.3. Operation Binding and Single Use

Where the owner's policy requires her to approve a particular access rather than a class of access, the authorization server MUST bind the grant to that access. Such a token MUST carry:¶

single_use:

REQUIRED. Boolean true.¶

operation:

REQUIRED. An object with a tool member naming the operation and a params_s256 member carrying s256 over the parameters approved, serialized as [RFC8785]: the params member of the agreement's operation [U4ATerms].¶

{
  "single_use": true,
  "operation": {
    "tool": "execute_trade",
    "params_s256": "s256:ogtS-uV8x6mcllHxtXOVD9IRgj46zju5wnPAZDDyTNM"
  }
}

Classic OAuth and UMA scopes authorize classes of action. "She approved this trade" and "she authorized trading" are different facts, and a protocol with only scopes can express the second. This is the narrowest useful addition that expresses the first.¶

8.1. Obligations, Not a Topology

[UMAFedAuthz] gives the resource server a list of obligations and never names the component that discharges them. This profile states them as a conformance profile that any resource-side implementation may satisfy.¶

An enforcement point MUST hold a protection API access token issued in the owner's name, MUST register attempted access to obtain a permission ticket, MUST introspect a presented token before allowing a call, and MUST refuse by default. Whether it is a gateway, a service mesh filter, a framework middleware, or the resource itself is out of scope.¶

Naming a topology here would exclude in-process deployments, which are the resource-side implementations most likely to adopt this profile.¶

8.2. Ordering

An enforcement point MUST perform the following steps in this order, and the order is normative:¶

1. Introspect the presented token, without consuming it, and establish that it is active and that the relationship behind it still stands. An inactive token is answered as [U4AFedAuthz] Section 5 says for its reason.¶

2. Establish that the resource being accessed appears in permissions with a scope that covers the attempted access, and that the permission's own exp and nbf, where present, admit the present time. Where they do not, answer with a challenge: negotiating again can succeed. Checks an extension places on the grant itself, such as [U4AMultiParty]'s ceiling and joint mandate, run here, after this step and before the next.¶

3. Verify proof of possession against the key named by cnf in the introspection response, and refuse with invalid_token where it fails. Then apply Section 7.2, refusing with consequence_changed.¶

4. Where the token carries single_use, or the enforcement point treats the attempted operation as single-use, establish that the attempted operation matches operation.tool and that s256 over the received parameters equals operation.params_s256.¶

5. Consume the token.¶

An enforcement point MUST NOT consume a single-use token before step 5, and a refusal at any earlier step leaves it unspent.¶

A binding MUST define how the operation and its parameters are read from a request. Where a request carries no parameters, they are the empty JSON object {}, and params_s256 is computed over that.¶

An enforcement point that treats an operation as single-use MUST refuse a token for it that carries no operation. An enforcement point MUST consume a token that carries single_use wherever it is presented, whether or not it treats the operation as single-use. The grant says what it was issued for; an enforcement point that reads single-use from its own configuration alone lets a grant issued for one act serve as standing authority wherever that configuration is absent.¶

Consuming at step 1 is the intuitive placement and it is a denial of service. Anyone who observes the token can replay it with a garbage signature: the replay is correctly refused, and the grant is already spent, so the one legitimate call — the operation the owner personally approved seconds earlier — then fails. An attacker who cannot forge a signature can still destroy the grant.¶

An enforcement point MUST verify proof of possession against the key returned by introspection rather than the key carried inside the token, so that a token accepted at step 1 and a key trusted at step 3 come from the same answer.¶

8.3. Indivisibility

A single-use artifact — a permission ticket, or a token carrying single_use — MUST be consumed by an operation that decides and records in one indivisible step, and that reports to its caller whether that caller was the one that consumed it. A caller told that it was not MUST refuse the request.¶

A read followed by a write is correct in one process and wrong the moment there are two. Two callers read consumed = false, both are told yes, and one owner-approved action is performed twice. The failure is silent, it appears only under replication, and it cannot be tested for in a single-process deployment — which is where the specification has to carry it, because the implementation will not.¶

[UMAGrant] Section 5.5 says a permission ticket is single-use and does not say where in enforcement it is spent, nor what "single-use" means when the authorization server has more than one replica. Both are stated here.¶

8.4. Introspection Responses

An authorization server MUST include, in an introspection response [RFC7662] whose active member is false, an error member naming the reason. At minimum it MUST distinguish a reason that further negotiation cannot change from one that it can.¶

An enforcement point receiving a reason of the first kind MUST refuse without issuing a fresh challenge. A bare {"active": false} sends a client around a negotiation whose outcome the owner has already settled, which wastes the agent's time and puts a request in front of the owner that she has already answered.¶

An introspection response for an active token MUST carry cnf and permissions, and single_use, operation, contract, consequence and clearance where the token carries them, with the token's values. The steps of Section 8.2 read them from the introspection response and not from the token, so that what an enforcement point acts on comes from the same answer that said the token is active, and it never needs to verify the authorization server's signature itself.¶

An authorization server MUST NOT describe a token as active to a resource server whose protection API access token was issued for a different owner than the token's, and MUST answer as it would for a token it does not know ([U4AFedAuthz] Section 5). A resource server holds one such token per owner it serves; the one it presents says whose resources it is asking about, and a grant against anybody else's is not its business.¶

13.1. Authorization Inputs Never Come From the Transport

The signature base is reconstructed from the enforcement point's configuration and from the credential presented, never from the routing layer that delivered the request. See Section 6.1. An authority taken from a header is an authority the caller can choose.¶

13.2. Consumption Is Ordered and Last

See Section 8.2. The failure this prevents is not forgery — it is destruction. An observer who cannot forge a signature can still spend a grant, if the grant is spent before the signature is checked.¶

13.3. Single Use Must Survive Replication

See Section 8.3. An implementation that is correct on one replica and wrong on two is the normal outcome of reading this requirement as "spend it once", and the resulting double-spend is silent.¶

13.4. Descriptive Metadata Is Not Authorization

See Section 5.2. A client ID metadata document proves that it claims its own URL and nothing further; a key directory proves that whoever controls that origin published a key. Treating either as an authorization input means that anyone able to publish a document can influence a decision. An implementation that displays a resolved name to the owner should expect that name to be the thing an implementer reaches for when writing policy, and must refuse it there.¶

13.5. Issuers Are Trusted by Dereference

An authorization server that verifies an identified agent's credential resolves the issuer over TLS and believes the keys it publishes. TLS on the issuer origin is the trust root, which is why non-https issuers are refused. This profile specifies no allow-list of issuers; a deployment MUST supply one, and a deployment that does not has delegated the question of which parties may attest agents to the DNS.¶

13.6. Revocation Is Atomic

See Section 9. Ending a relationship and invalidating the grants under it are the same decision and MUST be the same operation.¶

13.7. A Truncated Request Must Fail Closed

Where an enforcement point receives a request body that an intermediary may have truncated, it MUST refuse with a reason naming the truncation. A cut-off structured body does not parse, so the operation being attempted disappears from a request that was merely padded. Deny-by-default catches this and misreports it, which means the deployment learns nothing from a log full of unknown-operation refusals.¶

13.8. The Resource Server Must Not Read the Owner's Policy

This is the cross-principal property the whole profile exists for, and it is structural rather than advisory: the protection API is scoped to a token the owner authorized, and it carries no operation that returns her policy. An implementation SHOULD be able to demonstrate the paired assertion — that the enforcement point is refused the owner's policy and allowed her published keys, on the same origin.¶

13.9. Not Addressed

Signing-key rotation is possible through published key sets and is not exercised by the reference implementation. Revocation propagation between authorization servers that do not share state is out of scope. [RFC9728] permits an array of authorization servers per resource and this profile is written for one.¶

14.1. Public Metadata Is Structural

Which resources a named person owns MUST NOT be published at an unauthenticated URI. [U4AFedAuthz] specifies the split: the public document describes the resource's shape, and whose instances sit behind it is served only to the authority that owner named.¶

14.2. The Record Names a Counterparty

An authorization server implementing this profile keeps a record of what was promised, decided and done, and that record names the client. It is the owner's record of her own decisions and it is also a per-agent history, which is a more sensitive object than either half. Retention is deployment policy; this profile requires only that a decision the owner did not personally take MUST NOT be recorded as one she did.¶

14.3. A Stated Purpose Is Not Evaluated

Where a client states why it wants access, the authorization server records it and shows it to the owner. It MUST NOT parse it, compare it to the purpose in the owner's terms, or let it affect the decision other than by its absence. An authority that reads a stated purpose and rules on whether it is plausible has put a judgement about natural language inside an authorization decision, which makes the same request answerable two ways. See [U4ATerms] and [U4APolicy].¶

16.1. Normative References

[I-D.ietf-oauth-client-id-metadata-document]

Parecki, A. and E. Smith, "OAuth Client ID Metadata Document", Work in Progress, Internet-Draft, draft-ietf-oauth-client-id-metadata-document-02, 6 July 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-02>.

[I-D.ietf-oauth-identity-assertion-authz-grant]

Parecki, A., McGuinness, K., and B. Campbell, "Identity Assertion JWT Authorization Grant", Work in Progress, Internet-Draft, draft-ietf-oauth-identity-assertion-authz-grant-04, 21 May 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-identity-assertion-authz-grant-04>.

[I-D.ietf-oauth-rar-metadata-remediation]

Zehavi, Y., "OAuth 2.0 RAR Metadata and Error Remediation", Work in Progress, Internet-Draft, draft-ietf-oauth-rar-metadata-remediation-00, 23 August 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar-metadata-remediation-00>.

[I-D.meunier-webbotauth-registry]

Guerreiro, M., Kirazci, U., and T. Meunier, "Registry and Signature Agent card for Web bot auth", Work in Progress, Internet-Draft, draft-meunier-webbotauth-registry-03, 26 June 2026, <https://datatracker.ietf.org/doc/html/draft-meunier-webbotauth-registry-03>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC6750]

Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, <https://www.rfc-editor.org/rfc/rfc6750>.

[RFC7515]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, <https://www.rfc-editor.org/rfc/rfc7515>.

[RFC7517]

Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, <https://www.rfc-editor.org/rfc/rfc7517>.

[RFC7638]

Jones, M. and N. Sakimura, "JSON Web Key (JWK) Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 2015, <https://www.rfc-editor.org/rfc/rfc7638>.

[RFC7662]

Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, <https://www.rfc-editor.org/rfc/rfc7662>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8414]

Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, <https://www.rfc-editor.org/rfc/rfc8414>.

[RFC8785]

Rundgren, A., Jordan, B., and S. Erdtman, "JSON Canonicalization Scheme (JCS)", RFC 8785, DOI 10.17487/RFC8785, June 2020, <https://www.rfc-editor.org/rfc/rfc8785>.

[RFC9068]

Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens", RFC 9068, DOI 10.17487/RFC9068, October 2021, <https://www.rfc-editor.org/rfc/rfc9068>.

[RFC9396]

Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, May 2023, <https://www.rfc-editor.org/rfc/rfc9396>.

[RFC9421]

Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP Message Signatures", RFC 9421, DOI 10.17487/RFC9421, February 2024, <https://www.rfc-editor.org/rfc/rfc9421>.

[RFC9530]

Polli, R. and L. Pardue, "Digest Fields", RFC 9530, DOI 10.17487/RFC9530, February 2024, <https://www.rfc-editor.org/rfc/rfc9530>.

[RFC9728]

Jones, M.B., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", RFC 9728, DOI 10.17487/RFC9728, April 2025, <https://www.rfc-editor.org/rfc/rfc9728>.

[RFC9864]

Jones, M.B. and O. Steele, "Fully-Specified Algorithms for JSON Object Signing and Encryption (JOSE) and CBOR Object Signing and Encryption (COSE)", RFC 9864, DOI 10.17487/RFC9864, October 2025, <https://www.rfc-editor.org/rfc/rfc9864>.

[U4AFedAuthz]

Gamb, N. and E. Maler, "Federated Authorization for Autonomous Agents", Work in Progress, Internet-Draft, draft-gamb-uma4agents-fedauthz-00, 2026, <https://u4a.ai/spec/draft-gamb-uma4agents-fedauthz-00.html>.

[U4ATerms]

Gamb, N. and E. Maler, "Owner-Proffered Terms for User-Managed Access (UMA) 2.0", Work in Progress, Internet-Draft, draft-gamb-uma4agents-terms-00, 2026, <https://u4a.ai/spec/draft-gamb-uma4agents-terms-00.html>.

[UMAFedAuthz]

Maler, E., Machulak, M., and J. Richer, "Federated Authorization for User-Managed Access (UMA) 2.0", Kantara Recommendation, 7 January 2018, <https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-federated-authz-2.0.html>.

[UMAGrant]

Maler, E., Machulak, M., and J. Richer, "User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization", Kantara Recommendation, 7 January 2018, <https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-grant-2.0.html>.

16.2. Informative References

[I-D.hardt-oauth-aauth-protocol]

Hardt, D., "AAuth Protocol", Work in Progress, Internet-Draft, draft-hardt-oauth-aauth-protocol-10, 6 August 2026, <https://datatracker.ietf.org/doc/html/draft-hardt-oauth-aauth-protocol-10>.

[I-D.ietf-webbotauth-httpsig-protocol]

Meunier, T. and S. Major, "HTTP Message Signatures for automated traffic", Work in Progress, Internet-Draft, draft-ietf-webbotauth-httpsig-protocol-00, 1 September 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-webbotauth-httpsig-protocol-00>.

[RFC7942]

Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, July 2016, <https://www.rfc-editor.org/rfc/rfc7942>.

[RFC9449]

Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449, September 2023, <https://www.rfc-editor.org/rfc/rfc9449>.

[RFC9635]

Richer, J., Ed. and F. Imbault, "Grant Negotiation and Authorization Protocol (GNAP)", RFC 9635, DOI 10.17487/RFC9635, October 2024, <https://www.rfc-editor.org/rfc/rfc9635>.

[U4AAAuth]

Gamb, N. and E. Maler, "AAuth Agent Tokens as Agent Credentials for User-Managed Access (UMA) 2.0 for Autonomous Agents", Work in Progress, Internet-Draft, draft-gamb-uma4agents-aauth-00, 2026, <https://u4a.ai/spec/draft-gamb-uma4agents-aauth-00.html>.

[U4ALAB]

Gamb, N. and E. Maler, "UMA for Agents: a reference implementation", 2026, <https://github.com/nickgamb/uma4agents>.

[U4ALineage]

Gamb, N. and E. Maler, "Agent Lineage for User-Managed Access (UMA) 2.0", Work in Progress, Internet-Draft, draft-gamb-uma4agents-lineage-00, 2026, <https://u4a.ai/spec/draft-gamb-uma4agents-lineage-00.html>.

[U4AMCP]

Gamb, N. and E. Maler, "Model Context Protocol Binding for User-Managed Access (UMA) 2.0", Work in Progress, Internet-Draft, draft-gamb-uma4agents-mcp-00, 2026, <https://u4a.ai/spec/draft-gamb-uma4agents-mcp-00.html>.

[U4AMultiParty]

Gamb, N. and E. Maler, "Multi-Party Authorization for User-Managed Access (UMA) 2.0", Work in Progress, Internet-Draft, draft-gamb-uma4agents-multiparty-00, 2026, <https://u4a.ai/spec/draft-gamb-uma4agents-multiparty-00.html>.

[U4AOwner]

Gamb, N. and E. Maler, "The Resource Owner's API for User-Managed Access (UMA) 2.0", Work in Progress, Internet-Draft, draft-gamb-uma4agents-owner-00, 2026, <https://u4a.ai/spec/draft-gamb-uma4agents-owner-00.html>.

[U4APolicy]

Gamb, N. and E. Maler, "Owner Policy, Assurance and Attention for User-Managed Access (UMA) 2.0", Work in Progress, Internet-Draft, draft-gamb-uma4agents-policy-00, 2026, <https://u4a.ai/spec/draft-gamb-uma4agents-policy-00.html>.

[UMAClaims2010]

Maler, E. and P. Bryan, "Simple Access Authorization Claims", April 2010.

A.1. Profile Identifiers

[UMAGrant] Section 4 asks that a profile or extension be given a uniquely identifying URI. The identifying URIs of this set are:¶

A.2. JSON Web Token Claims

A.3. Authorization Details Type

A.4. Other Values

B.1. UMA for Agents Reference Implementation

Organization:

Independent¶

Description:

A running deployment of this profile and the rest of its set: an authorization server, an enforcement point in two hosting shapes, a protected resource, an operator key directory, and clients at both identity levels. It runs under container orchestration and on a single host, against both an in-memory and a replicated store. It carries two client implementations that share no code — one in Python, one in TypeScript — which meet on the wire and nowhere else; the second was written from these documents rather than from the first, and found one defect in the enforcement point on its first run.¶

Level of maturity:

Research. The implementation exists to establish that the requirements in this document can be met and to find the ones that cannot.¶

Coverage:

Every normative requirement in this document is exercised by an automated check, except those addressed to deployments or to bindings rather than to this profile's own components. The register at https://u4a.ai/spec/conformance.yaml names, for each requirement, the check that verifies it and the assertion that check prints.¶

Licensing:

Apache 2.0.¶

Contact:

[U4ALAB]¶

Notes:

Several requirements in this document exist because the intuitive implementation was written first and was wrong. Section 8.2, Section 8.3, Section 6.1 and Section 5.1 each record a defect found by running the implementation rather than by reading the specification it was built from.¶