]> MindGarden LLC

nickgamb@gmail.com

Venn Factory

Security UMA authorization terms consent receipts This document extends the claims-gathering loop of the User-Managed Access (UMA) 2.0 Grant so that the authorization server proffers the content of the claim it requires, rather than only naming acceptable claim formats. The resource owner's authorization server publishes a terms document — purpose, scope, duration and prohibitions — at a persistent, dereferenceable URI. The requesting side echoes that document, signs it with the key it will later prove possession of, and presents it as the claim token. The grant returns a receipt, counter-signed by the authorization server, embedding the signed agreement, so that both parties hold identical records of what was agreed.

Introduction Section 3.3.4 lets an authorization server tell a client what claims it needs by naming claim types and acceptable formats. The client then gathers those claims from wherever it can and presents them. The authorization server asks what can you tell me about yourself. This extension adds the other direction. The authorization server proffers a document stating what the resource owner requires of anyone who wants this access, and the claim the requesting side returns is that document, signed. The authorization server asks will you agree to this. The pattern is that of , in which an individual proffers machine-readable terms as first party and a counterparty's agent agrees to them as second party. This document extends it from privacy terms to terms of access, and carries the agreement inside a grant so that the terms are conditions on an authorization rather than a record kept beside one. It is also a direct descendant of UMA's own 2010 work , which defined a "requesting party policy" claim for exactly this purpose and which the 2.0 specifications did not carry forward.

Relationship to the Set This document extends and is REQUIRED to implement alongside . It is separable: a UMA deployment with no agents in it can adopt this extension on its own, and nothing here depends on the requesting side being autonomous. Its identifying URI, for the uma_profiles_supported metadata of Section 4, is https://u4a.ai/spec/terms/1.0.

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 when, and only when, they appear in all capitals, as shown here. The notation s256(x) is as defined in .

The Terms Document An authorization server implementing this extension MUST serve, for each set of terms it proffers, a document at a URI that resolves for as long as the authorization server serves the owner whose terms they are. A terms document MUST carry:

template_id:

REQUIRED. A stable identifier for this version of these terms, namespaced by owner.

purpose:

REQUIRED. What the access is for, in the owner's words.

scope:

REQUIRED. An array of scope strings the terms cover.

expires_in:

REQUIRED. The maximum lifetime, in seconds, of access granted under these terms.

prohibited:

REQUIRED. An array of identifiers naming what the requesting side undertakes not to do. MAY be empty.

proffered_by:

REQUIRED. The issuer identifier of the authorization server that proffers them.

A terms document MAY carry any other member; a member this document does not define is an undertaking the requesting side signs, not a control the enforcement point applies. One member is defined here:

per_operation:

OPTIONAL. Boolean. Where true, a grant under these terms is bound to one operation and spent once, as Section 7.2, and the agreement MUST name the operation proposed.

Versions Are Immutable The content of a terms document at a given template_id MUST NOT change. An authorization server that changes the owner's terms MUST issue a new template_id and MUST continue to serve every previous version. An agreement is a signature over a document. A document that can change after it is signed makes every agreement over it unverifiable later, which removes the only property that distinguishes this from a consent dialog.

Representations An authorization server MUST serve a terms document as JSON, and MUST serve, at the same URI, a plain-language representation intended for a person, selected by HTTP content negotiation. It SHOULD additionally serve a representation in a rights expression language such as . The three representations satisfy Sections 4.4.1 and 4.4.2. The requirement that they share a URI is what makes the human-readable statement and the machine-readable one the same terms rather than two documents that may drift.

Proffering Where the authorization server requires agreement to terms before it will decide, it responds to a ticket presentation with need_info as Section 3.3.6, carrying a required claim whose claim_type is urn:uma4agents:claim:myterms-agreement and whose claim_token_format array includes urn:uma4agents:format:myterms-agreement-v1+jws. The required claim MUST additionally carry a terms_template member: the terms document of , plus

terms_uri:

REQUIRED. The URI at which this version of this document is served.

nonce:

REQUIRED. A value the authorization server has not previously used, to be echoed in the agreement.

family:

REQUIRED. The identifier of this negotiation, stable across ticket rotations.

resource_id:

REQUIRED. The resource the terms are being proffered over.

The authorization server MUST offer exactly one set of terms per demand. There is no counter-offer and no negotiation beyond the single choice of agreeing or not, per Section 5.2.2. A protocol that let the requesting side propose amendments would make the owner a party to a conversation she is not present for.

The Agreement The requesting side agrees by presenting a claim token whose claim_token_format is urn:uma4agents:format:myterms-agreement-v1+jws and whose value is the base64url encoding of a JWS in compact serialization with a typ of myterms-agreement-v1+jws.

The Signing Key The JWS protected header MUST carry exactly one of:

jwk:

A public JWK , where the requesting side is pseudonymous.

agent_token:

A credential from an issuer that asserts the requesting agent's identity and names the signing key, where the requesting side is identified.

The authorization server MUST verify the JWS against the key so named, and MUST refuse an agreement carrying neither. The key that signs the agreement is the key that is confirmed in the grant, so that the party that agreed and the party that later acts are provably the same.

Claims The agreement MUST echo, unchanged, the template_id, terms_uri, purpose, nonce and family of the proffered template, and MUST carry an aud naming the authorization server that proffered them. It MUST carry an expires_in no greater than the template's, and a prohibited array that is a superset of the template's. Where the template's per_operation is true, the agreement MUST carry an operation member naming the operation proposed and the parameters proposed for it.

The superset test on prohibited is deliberate: binding yourself to more than was asked is agreement, and refusing it would make the honest case fail. Every other echoed member is compared for equality, because a requesting side that can alter the purpose it signed up to has signed a different document from the one the owner published.

What the Requesting Side May Author The agreement MAY carry the following, and MUST NOT carry anything else that affects the decision:

reason:

OPTIONAL. A string stating why the access is wanted. The authorization server MUST bound its length, MUST record it, and MUST NOT parse it, compare it to the purpose in the terms, or let its content affect the decision.

mission:

OPTIONAL. An object citing a mandate the requesting side is acting under, with an approver member that is an https URL and an s256 member that is a content digest. The authorization server MUST record the citation and MUST NOT dereference it.

Policy MAY read the absence of either. It MUST NOT read the content of either. See . An authority that reads a stated reason and rules on whether it is plausible has put a judgement about natural language inside an authorization decision: the same request becomes answerable two ways, and the requesting side learns to write whatever gets through. Bound it, record it, show it to the owner, and let policy do exactly one thing with it — notice when it is missing. A mission citation is recorded rather than dereferenced because the issuers that serve missions serve them to their own administrators. A relying party in another trust domain has nothing to fetch, so an agent citing a real mandate and one inventing a digest are indistinguishable to it. That is why the citation is a record for the owner to read and never an input to the decision.

The Receipt On issuing a grant against an agreement, the authorization server MUST return a receipt alongside the token, as a member named receipt in the token endpoint response. The receipt MUST be a JWS signed by the authorization server with a typ of myterms-receipt+jws, and MUST carry:

terms_uri:

REQUIRED. The document that was agreed to.

template_id:

REQUIRED. The version that was agreed to.

agreement:

REQUIRED. s256 over the octets of the agreement as transmitted.

agreement_jws:

REQUIRED. The complete agreement JWS, as received.

family:

REQUIRED. The negotiation this receipt completes.

Embedding the whole agreement rather than a reference to it is what makes the two records identical: the owner's side retains it with her decision record and the requesting side retains the receipt, and neither has to ask the other for the half it is missing. This satisfies Sections 5.2.2 and 5.4.4.

Declining A requesting side that will not agree to the proffered terms MUST be able to say so. An authorization server MUST accept a decline parameter with the value true at the token endpoint while a negotiation is awaiting a claim, MUST end the negotiation, and MUST record the refusal against the terms that were declined. A refusal is a record too, per Section 5.2.4. It is also the only signal an owner has that her terms are the reason nobody uses a resource she has published. A declining requesting side has signed nothing, so there is no key and no identity to file the record under. An authorization server MUST record such a refusal without attributing it to a party. An implementation that invents an attribution here is asserting something it does not know.

Security Considerations

The Agreement Binds the Key That Will Act See . If the agreement could be signed by one key and the grant confirmed to another, the party that agreed and the party that acts would be different parties, and the agreement would say nothing about the requests made under it.

The Digest Is Over the Transmitted Octets The agreement member of the receipt, and any digest of the agreement recorded with the grant, MUST be computed over the agreement exactly as transmitted, not over a re-serialization of its claims. A digest over re-serialized JSON is a digest of the verifier's serializer, and two conforming implementations will disagree about it.

Terms Are Not a Sandbox An owner's prohibitions divide into two kinds, and an implementation SHOULD be able to say which is which for each one it supports. A prohibition on something that must cross the owner's boundary to happen — placing an order outside approved parameters, reusing an approval for a second action — can be refused at the enforcement point. A prohibition on what happens afterwards on the requesting side's own systems — retention, onward sharing, training — cannot. Both belong in the terms, and only one is a control. The second is what the dually-signed record exists for: it makes the undertaking checkable against conduct rather than preventing the conduct. Describing the second kind as enforcement is the overstatement this section exists to prevent.

Privacy Considerations

The Roster Is the Owner's Section 4.2 places the roster of proffered terms with a neutral non-profit, so that an individual chooses from a small set of well-understood agreements rather than authoring her own. This document places it with the owner's own authorization server, because the terms here are conditions inside a grant that server issues and it has to be able to serve them for as long as the grant is checkable. The divergence is real and has a cost: terms nobody else proffers are terms nobody else has read. A deployment SHOULD proffer terms drawn from a published roster where one exists for its domain, and the template_id namespacing in is designed so that a roster identifier can be used directly.

The Terms Document Is Public A terms document is dereferenced by a requesting side that holds no token, so its content is public to anyone who can guess or observe its URI. It states what the owner requires, which is a statement about her. An authorization server MUST NOT place anything in a terms document that identifies the owner beyond what the resource identifier already discloses. Where a layer above the owner has narrowed her terms, the narrowing appears in the document, which is deliberate — see . An agent reads the document before it signs, and that is the only moment at which "these terms are not hers alone" is information it can act on.

IANA Considerations

Media Type Registration IANA is asked to register the following in the "Media Types" registry.

Type name:

application

Subtype name:

myterms-agreement-v1+jws

Required parameters:

N/A

Optional parameters:

N/A

Encoding considerations:

binary; a JWS in compact serialization

Security considerations:

See of this document

Interoperability considerations:

N/A

Published specification:

of this document

Applications that use this media type:

Applications implementing UMA 2.0 with this extension

Change controller:

IETF

IANA is asked to register application/myterms-receipt+jws in the same registry, with the same considerations and with of this document as its published specification.

URN Sub-namespace Registration IANA is asked to record the following identifiers, which are defined by this document within the urn:uma4agents: namespace: Identifier Defined in urn:uma4agents:claim:myterms-agreement urn:uma4agents:format:myterms-agreement-v1+jws

JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification. A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. This process is not mandatory. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. This document obsoletes RFC 6982, advancing it to a Best Current Practice.

Implementation Status This section records the status of known implementations in the sense of , and is to be removed before publication as an RFC. The reference implementation described in implements this extension in full, including all three representations of , the immutability requirement of , the receipt of and the unattributed refusal record of . It was checked clause by clause against ; the divergences found are the ones stated in this document rather than a longer list kept elsewhere.

Acknowledgments The direction this extension reverses — an authorization server that proffers rather than demands — is the "requesting party policy" claim of , and this document is its descendant. supplied the pattern, the three representations, the single-choice rule and the dual-record requirement, and the divergences in are stated in its terms rather than around them.