Terminology and diagram comments

[xmlgrrl]

The following comments were received during the Public Comment period [UPDATE: Edited to add letters to distinguish individual comments for reference in Disposition of Comments document]:

Terminology

• a: The terms of "authorization" and "authorization server" are very generic. They appear in OAuth, OIDC and UMA specifications. Is there any way to distinguish these? Our recommendation would be to introduce and use the terms "UMA authorization server" and "OpenID Provider" in full where possible.

• b: The use of the terms "correlation handle", "ticket" and "token". For example in Figure 1 of UMAGrant, we suggest to spell out the term "permission ticket" where possible.

Sequence diagrams

• c: Please consider separating sequence diagrams for resource configuration by resource owner from resource access by requesting party. This emphasizes the asynchronous nature of the specification and the fact that the resource owner does not need to be anywhere present when a requesting party wants to access a resource.

• d: Also please consider presenting a sequence diagram with the simplest possible "sunny day" sequence for resource access. For example split Figure 1 of UMAGrant into two separate figures. One with "claims push" and other with "claims gathering". Also provide explanation of difference between "claims push" and "claims gathering".

[xmlgrrl]

Editor response to sub-issue (a): In the UMA V1.0.n specifications, the prefix "UMA" was added to "authorization server", "resource server", "client", etc. when necessary for disambiguation in contexts where OAuth was also being discussed. However, in the UMA V2.0 specifications, an UMA authorization server, resource server, client, etc. is literally an OAuth one as well, since UMA is defined as an OAuth extension grant.

The word "authorization" is used carefully and is generally qualified in precise ways with "... process", "... assessment", and so on as defined in the specifications.

When identity (vs authorization) terms are used, and specifically OpenID Connect terms, the full phrases are indeed used (for example OpenID Provider).

The editor therefore recommends making no changes.

[xmlgrrl]

Editor response to sub-issue (b): The editor accepts the suggestion to use the full phrase "permission ticket" where possible, including throughout the figure(s) in Grant.

Not sure if the commenter intended to provide a concrete suggestion regarding "correlation handle"; this is just a phrase used as part of the definitions of "permission ticket" and "persisted claims token (PCT)". While Internet searches for this phrase mostly turn up definitions that are somewhat .NET-specific, its usage in software and protocol conversations is not uncommon.

Regarding the mention of "token", perhaps the suggestion is to always qualify the word "token" with "access ...", "claim ...", "persisted claim ...", "requesting party ...", "refresh ...", "bearer ...", "ID ...", etc. where possible. This would be reasonable. In this case, the editor recommends making the following edits (or similar):

• In Grant Sec 3.1, the title and text should say "with no access token"
• In Grant Sec 3.3.5.1, the text should say "so as to enable clients to manage RPTs efficiently"
• In Grant Sec 3.3.6, the text should say "An array of strings specifying a set of acceptable formats for a claim token pushed"
• In Grant Sec 3.5, the text should say "as if the request were unaccompanied by an access token" and "how the resource server can introspect the RPT"
• In Grant Sec 5.2, the text should say "which could maliciously pass the RPT"
• In FedAuthz Sec 1.5, the text should say "when that text is unaccompanied by an access token"
• In FedAuthz Sec 1.5.1, the text should say "When the client makes a resource request unaccompanied by an access token, or if the resource request fails,"
• In FedAuthz Sec 4, the text should say "After the client's initial resource request without an access token"
• In FedAuthz Figure 3, the first arrow should say "Request resource (no or insufficient access token)"

[xmlgrrl]

Editor response to sub-issue (c): The original rationale for including the (out-of-scope) setting of policy by the resource owner was to have a single diagram with the five UMA entities present in it. However, the editor agrees it would indeed be beneficial to demonstrate the asynchronous nature of the grant (along with potentially some notion of the flexibility afforded authorization servers and resource owners in the timing of policy setting) by having two diagrams.

[xmlgrrl]

Editor response to sub-issue (d): This is a good suggestion. While there is a brief explanation, after a fashion, of separate rationales for claims pushing vs claims gathering in Grant Sec 1.3.1, it doesn't follow closely enough after Figure 1. The editor agrees the explanation would be helped by being moved up and by having the two flows separated out into different diagrams, since the hybrid flow in Figure 1 is (at least at this time) an unlikely scenario.

[xmlgrrl]

On second thought about sub-issues (c) and (d): Will need to seek the WG's feedback, as the existing diagram was created with some specific implementer purposes in mind.