Multi-Party Authorization for User-Managed Access (UMA) 2.0

1.1. Relationship to the Set

This document is an OPTIONAL extension of [U4ACore] and depends on [U4ATerms], [U4AFedAuthz] and [U4APolicy]. Its identifying URI is https://u4a.ai/spec/multiparty/1.0. An implementation MAY implement Part I, Part II, or both.¶

1.2. 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.¶

Throughout, a policy unit is as defined in [U4APolicy] Section 2.¶

2.1. Parties

Organization:

A party that holds resources and shares administration of them with its members. It publishes a charter, answers a decision endpoint, and signs documents its members' authorization servers verify against keys it publishes.¶

Member:

A resource owner under [U4ACore] who has enrolled with an organization. Her authorization server is hers; the organization is a party it consults.¶

The organization and the member's user agent have no relationship, and this document does not invent one. Every message from the organization is addressed to the member's authorization server.¶

2.2. The Charter

An organization MUST publish a charter, versioned, carrying:¶

claims:

REQUIRED. Patterns naming the resources the organization holds. A pattern MUST name a namespace: it MUST NOT place a wildcard in the segment that identifies whose resource it is, since such a claim would reach a member's own resources and jointly held ones alike.¶

roles:

REQUIRED. Named roles, each with grants (patterns within claims the role may reach) and delegation (Section 2.3).¶

envelope:

OPTIONAL. A ceiling on the terms a member may write over claimed resources (Section 2.4).¶

break_glass:

OPTIONAL. Whether and over which claimed resources the organization may reach past a member (Section 2.9).¶

The pattern language MUST be segment-wise, with a wildcard matching one segment and never crossing a separator, and MUST offer neither alternation nor a recursive wildcard. Four evaluators have to agree on what a pattern matches — the organization's service, the member's authorization server, the enforcement point, and any policy engine the organization runs — and a language small enough to be checked by reading is the only kind that can be.¶

2.3. Delegation

Each role MUST carry a delegation value, one of:¶

none:

The member may reach the resource herself. No agent acting for her may.¶

first-party-only:

An agent the member activated herself ([U4APolicy] Section 5) may be granted access under her terms. An agent somebody else runs may not, whatever her own terms say.¶

any-agent:

Any agent, subject to her terms and the charter.¶

delegation does not say what may be accessed. It says whose agent may do the accessing, on behalf of which person. That is a statement about parties rather than permissions, and it is only expressible because the member's authorization server can already distinguish an agent she activated from one somebody else operates.¶

2.4. The Envelope, Clamped on Write

An envelope MAY carry:¶

max_expires_in:

A member's expires_in over claimed resources comes down to this.¶

allowed_scopes:

Scopes not in it are removed from her terms.¶

require_prohibited:

Prohibitions missing from her terms are added.¶

always_ask:

Patterns over which her policy units are set to ask her every time.¶

Every envelope field moves a member's terms in one direction only. There MUST be no field that lengthens an expiry, adds a scope, removes a prohibition, or turns off an ask.¶

A member's authorization server MUST apply the envelope when a policy unit over a claimed resource is written, and again whenever the charter changes, by issuing a new version of the unit's terms document through the same path as one of her own edits. It MUST NOT apply the envelope only at grant time.¶

The clamp is applied on write so that the ceiling appears in the terms document the requesting side dereferences and signs, rather than being applied invisibly at the door. A terms document MUST state that a layer above the owner is in force over its resources: an agent reads the document before it signs anything, and that is the only moment at which "these terms are not hers alone" is information it can act on.¶

2.5. The Decision

For each request over a resource the charter claims, the member's authorization server MUST ask the organization's decision endpoint once, presenting the facts of the request, and MUST fold the answer into its own. The facts are a JSON object carrying resource_id, the scopes attempted, the policy unit as tier, the expires_in, purpose, reason, mission and operation of the agreement, and the assurance and standing facts of [U4APolicy]; the member's authorization server presents its membership credential with them.¶

The organization answers allow, ask or refuse, with reasons. allow means the organization has no objection, not that the request is granted. The composition rule is one sentence: both layers must allow, and either may refuse. An organization's ask raises the member's auto to ask, and the member MUST be shown the organization's reasons separately from her own.¶

An organization's decision MUST NOT widen what the member's policy would decide. Where the organization cannot be reached, the member's authorization server MUST refuse requests over claimed resources; a ceiling nobody can read is not a ceiling.¶

A request over a resource the charter does not claim MUST NOT be sent to the organization.¶

2.6. What the Organization May See

An organization MAY be given a view of a member's pending requests, connections, operators and record, filtered by the member's authorization server to entries concerning resources the charter claims. It MUST NOT be able to read the member's policy; at most it may be told which of its envelope fields bound and whether her units are within the envelope.¶

The filtering is the member's authorization server's, applied before it answers, and is not the organization's to respect.¶

2.7. Acting for a Member

An organization MAY answer a pending request on a member's behalf, and MAY end an agent's reach to claimed resources. When it does:¶

• the record MUST name the organization's administrator, and MUST NOT record the decision as the member's ([U4APolicy] Section 8.4);¶

• an agent shut out by the organization loses its reach to claimed resources only, held in the membership record so that it ends when the membership does, and its standing with the member over her own resources is untouched;¶

• an introspection response for a grant so affected carries error of organization_revoked ([U4AFedAuthz] Section 6).¶

2.8. Enrolment and Leaving

A member's authorization server MUST NOT enrol her with an organization without her explicit agreement to a specific charter version, and MUST show her, before she agrees, what enrolling would change about terms she has already written.¶

The organization issues a membership credential to her authorization server at enrolment — a JWT with typ of u4a-membership+jwt, signed by the organization, naming the member as sub and the organization as org — and that server presents it as a bearer credential on every call to the organization. The organization MUST be able to end a membership and MUST notify the member's authorization server when it does, when her role changes, or when the charter changes. A notice is a JWT with typ of u4a-org-notice+jwt, signed by the organization and verified by the member's server against the keys it publishes, whose kind is one of membership_ended, role_changed, charter_changed, break_glass_opened, break_glass or break_glass_used.¶

Leaving MUST withdraw the member's access to claimed resources and the ceiling over her, and MUST leave every narrowing the ceiling applied in place. Her terms were narrowed with her agreement and republished under a new version; undoing that would silently widen what agents holding agreements over those versions are held to.¶

2.9. Break-Glass

Where the charter enables it, the organization MAY reach a claimed resource without the member's authorization server, by issuing a grant it signs itself. Such a grant MUST be single-use, bound to a key, short-lived, and over a resource the charter both claims and names for this purpose. The enforcement point MUST recognise it by issuer and MUST introspect it with the organization rather than with the member's authorization server.¶

The member MUST be notified at the moment the window opens, before any data moves. Break-glass cannot be a flag on an ordinary grant: it has to be a grant the organization signs, checked with the organization, bounded by a clause the member was shown before she joined, and unable to be quiet.¶

3.1. Parties

Holder:

A resource owner under [U4ACore] who holds a resource jointly with others. Each holder has her own authorization server.¶

Tally:

A party that publishes the mandate, folds the holders' terms into one document, collects verdicts, and issues a grant carrying them. It speaks the authorization-server surface of [U4ACore] to the requesting agent, which cannot tell it from an authorization server and does not need to.¶

With no party above the holders, the decision cannot be put anywhere without privileging the place it is put. The tally is that place, and the rest of Part II is what makes it unable to lie rather than trusted.¶

3.2. The Mandate

The tally MUST publish, for each jointly held resource, a mandate carrying:¶

resources:

REQUIRED. At least one resource identifier or pattern.¶

holders:

REQUIRED. At least two, each with owner, an https issuer naming her authorization server, and an integer weight of at least one. An owner MUST NOT appear twice.¶

rule:

REQUIRED. kind of all, any or threshold, normalised to a numeric threshold: the total weight for all, the lightest holder's weight for any, and a stated value between one and the total for threshold.¶

A holder's authorization server MUST store the mandate she agreed to, MUST re-ask her when the published mandate differs from it in holders, threshold or resources, and MUST refuse to count a holder who has written no terms over the resource.¶

A deployment MAY fix a floor below which no mandate's threshold may go. The interesting real-world version of this is not a group choosing its own quorum; it is a regulator or an account agreement fixing one, and a floor set from outside answers the question a self-chosen quorum cannot.¶

Authoring a mandate is where "who decides who decides" lives, and this document leaves it to configuration.¶

3.3. The Fold

When a requesting agent presents a ticket for a jointly held resource, the tally MUST obtain each holder's terms over it from her authorization server and MUST fold them into one terms document: the shortest expiry, the intersection of scopes, the union of prohibitions, and ask-me if any holder asks. It proffers that document under [U4ATerms], and the agent signs it once.¶

The fold is the clamp of Section 2.4 applied sideways: each holder's terms are a ceiling on the running document. An implementation SHOULD use one implementation of the narrowing for both, since two would be two chances to disagree about what "narrower" means in the two places where disagreeing is worst.¶

3.4. Verdicts

Each holder's authorization server, asked by the tally about one negotiation, MUST answer with a verdict: a JWS [RFC7515] signed by that server with a typ of u4a-verdict+jwt, carrying:¶

holder:

REQUIRED. The holder.¶

account:

REQUIRED. The jointly held resource.¶

negotiation:

REQUIRED. The negotiation identifier this verdict answers.¶

contract:

REQUIRED. The digest of the agreement the agent signed, as [U4ATerms].¶

effect:

REQUIRED. allow or refuse.¶

because:

OPTIONAL. Reasons, for a refusal.¶

exp:

REQUIRED. Short.¶

A verdict is bound to one negotiation and one agreement so that it cannot carry a later request. Before answering allow, a holder's authorization server MUST compare the folded document the agent signed against the terms she published, and MUST refuse on any difference in the direction of more: a longer expiry, an extra scope, a dropped prohibition. Differences in the direction of less are expected, since another holder's terms were folded in. This is what lets the folding party be untrusted.¶

{
  "iss": "https://alice-as.example",
  "holder": "alice",
  "account": "joint-brokerage-1",
  "negotiation": "fam_8f3aQ2Xc",
  "resource_id": "joint-brokerage-1/get_positions",
  "contract": "s256:mNTA0Zjg1YTBkYzQxZWY4YjkyMWM4ZGIy",
  "effect": "allow",
  "iat": 1789430000,
  "exp": 1789430300
}

Where the holder's policy asks her, the verdict is withheld until she answers, and the tally holds the negotiation pending as [UMAGrant] request_submitted.¶

3.5. Verdicts Are Not Claims

A verdict MUST travel from the holder's authorization server to the tally. It MUST NOT be gathered by the requesting agent and presented as a claim.¶

A claim the requesting party gathers is a claim it can decline to gather. A holder's refusal has to reach the decision point without the cooperation of the party it refuses, and claims-gathering cannot carry it. The general boundary: claims work when the requesting party is the only one who holds the fact, and fail when the fact may be adverse to it.¶

3.6. The Count

The tally MUST sum the weight of holders whose verdict is allow and compare it to the threshold. It MUST refuse the moment the weight still outstanding cannot carry the request over the threshold — under all, the first refusal ends it — rather than waiting for every holder. Silence and unreachability MUST both fail closed; only the record distinguishes them.¶

3.7. The Grant Carries the Verdicts

A grant the tally issues MUST carry a joint claim with:¶

account:

REQUIRED. The jointly held resource.¶

mandate:

REQUIRED. The mandate as the tally holds it.¶

verdicts:

REQUIRED. Every verdict received, as issued.¶

tally:

OPTIONAL. The tally's own count, for display.¶

{
  "joint": {
    "account": "joint-brokerage-1",
    "mandate": {
      "holders": [
        {"owner": "alice", "issuer": "https://alice-as.example",
         "weight": 1},
        {"owner": "carol", "issuer": "https://carol-as.example",
         "weight": 1}
      ],
      "rule": {"kind": "all", "threshold": 2},
      "resources": ["joint-brokerage-1/*"]
    },
    "verdicts": ["eyJ0eXAiOiJ1NGEtdmVyZGljdCtqd3Qi...",
                 "eyJ0eXAiOiJ1NGEtdmVyZGljdCtqd3Qi..."],
    "tally": {"effect": "allow", "for": 2, "threshold": 2}
  }
}

3.8. Re-Verification at the Enforcement Point

An enforcement point protecting a jointly held resource MUST, before allowing a call under such a grant:¶

1. fetch the mandate from where the tally publishes it, and MUST NOT use the copy embedded in the grant;¶

2. verify each verdict against the keys published by the issuer the published mandate names for that holder;¶

3. establish that each verdict names this negotiation and this agreement;¶

4. re-run the count of Section 3.6 and refuse unless it allows.¶

The tally member of the grant is for display and MUST NOT be trusted.¶

Reading the mandate from the grant would let the party being checked supply the standard it is checked against: a single genuine verdict beside a rewritten threshold would pass with every signature verifying. Carrying the verdicts in the grant and re-verifying them at the resource is what makes the tally an ordinary service rather than a ledger — there is no ordered history here to agree on and no long-lived state a fork could damage.¶

3.9. No Organization Reaches a Jointly Held Resource

A charter claim MUST NOT match a jointly held resource, and a holder's authorization server MUST refuse to apply an organization's envelope or decision to one regardless. A jointly held resource MUST NOT share a policy unit with any other resource, since a ceiling applies to a whole unit once it reaches any resource in it.¶

Peers compose horizontally; an authority above them clamps vertically. The two are orthogonal rather than rival, and this document keeps them apart.¶

4.1. A Layer Above May Only Narrow

See Section 2.4 and Section 2.5. The one-directionality of every envelope field and of the decision's effect on the member's own result is the property the whole of Part I rests on. An implementation SHOULD be able to demonstrate over its full envelope that no combination of envelope and terms produces wider terms than it started with.¶

4.2. Reach Stops at the Claim

See Section 2.6 and Section 2.7. Everything the organization can see or do stops at the resources its charter claims, and the scoping is applied by the member's authorization server before it answers. An organization given a member's whole record because it is easier has been given her relationships with parties that have nothing to do with it.¶

4.3. An Administrator's Decision Is Not the Owner's

See Section 2.7. "The owner personally approved" may relax a rule under [U4APolicy]; a decision taken for her must not produce that fact.¶

4.4. The Mandate Is Read Where It Is Published

See Section 3.8. This is the single check that makes the tally untrusted.¶

4.5. Silence Is Not Consent

See Section 3.6. A holder who has not answered and a holder who cannot be reached both count for nothing.¶

4.6. Break-Glass Is Loud

See Section 2.9. An emergency path that can be exercised quietly is an ordinary path with a better name.¶

5.1. Members Are Not Visible to Each Other

Under Part I, an organization's view of one member is filtered to claimed resources and says nothing about any other member. Under Part II, a holder's authorization server MUST NOT expose another holder's pending queue, decisions or record; each holder sees her own verdicts and the count.¶

5.2. The Ceiling Is Disclosed to the Agent

Section 2.4 requires that a terms document state when a layer above the owner is in force. That discloses to the requesting side that the owner is a member of some organization, which is a fact about her. The alternative — a ceiling applied invisibly — asks the agent to sign terms that are not the terms it will be held to, and this document prefers the disclosure.¶

6.1. Media Type Registration

IANA is asked to register application/u4a-verdict+jwt, application/u4a-membership+jwt, application/u4a-org-notice+jwt and application/u4a-org-admin+jwt in the "Media Types" registry, each with:¶

Required parameters:

N/A¶

Optional parameters:

N/A¶

Encoding considerations:

binary; a JWT in compact serialization¶

Security considerations:

See Section 4 of this document¶

Interoperability considerations:

N/A¶

Applications that use this media type:

Applications implementing UMA 2.0 with this extension¶

Change controller:

IETF¶

and with the following published specifications: Section 3.4 for u4a-verdict+jwt; Section 2.8 for u4a-membership+jwt and u4a-org-notice+jwt; Section 2.7 for u4a-org-admin+jwt.¶

6.2. JSON Web Token Claims Registration

IANA is asked to register the following in the "JSON Web Token Claims" registry established by [RFC7519].¶

Claim Name:

joint¶

Claim Description:

The mandate and verdicts under which a jointly held resource was released¶

Change Controller:

IETF¶

Specification Document(s):

Section 3.7 of this document¶

Claim Name:

break_glass¶

Claim Description:

That a grant was issued by an organization under its emergency clause, and the justification¶

Change Controller:

IETF¶

Specification Document(s):

Section 2.9 of this document¶

7.1. Normative References

[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>.

[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>.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/rfc/rfc7519>.

[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>.

[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>.

[U4ACore]

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

[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>.

[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>.

[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>.

[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>.

7.2. Informative References

[PP2PI]

Lush, N., Ed. and Kantara Initiative User-Managed Access Work Group, "Solving Data Sharing Challenges with UMA: The Julie Adams Healthcare Use Case from PP2PI", Kantara Editors' Draft Report, March 2023, <https://kantara.atlassian.net/wiki/spaces/uma/pages/4850258/Notes+drafts+and+WIP>.

[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>.

[U4ALAB]

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