Editorial issues on FedAuthz from Cigdem

[xmlgrrl]

Cigdem noted these issues, made on rev 05; see notes in attachment. (One or two are OBE in rev 06.)
Federated Authorization for User-Managed Access (UMA) 2.0.pdf

[xmlgrrl]

To @ciseng:

• Sec 1 "central service location": Yes, as Grant defines them informally in its own introduction, authorization grant rules are policy conditions. Since FedAuthz is dependent on Grant for interpretation, I don't think we need to spell that out again here. But something like s/at a central service location/through the authorization server/ would be more accurate since policy-setting is technically out of band (the AS could just front a PIP) and we've already said "single".

• Sec 1 "with the use of token introspection": Rev 06 actually removed this due to further WG discussion. The original intent was that the use of this optional feature conveyed the benefit, but we decided there is no qualification needed.

• Sec 1.2 "takes the role of the resource owner authorizing": I think the grammar is correct here, but agreed that it's hard to understand. We're saying that the "grant RO", say, Alice, is the same RO that authorizes issuance of the PAT (which is a totally separate OAuth flow, if you think about it). Will clarify.

• Sec 1.4 "additional": This is a good catch. The V1.0.1 version was simply "The resource server MAY apply additional authorization controls when determining how to respond.", and we added an example. This is the "Adrian clause", but it doesn't read quite right. This seems more appropriate: "For example, even if an RPT provides sufficient permissions for a particular case, the resource server can choose to bar access based on its own criteria."

More to come...

[ciseng]

• Sec 1 “central service location": +1. Want to make sure that the terminology is consistent across documents, and does not lead to confusion.
• OK
• Sec 1.2 - I see - it is hard to parse as a sentence. No problem with the meaning.
• Sec 1.4: +1

[xmlgrrl]

More for @ciseng:

• Sec 1.4.1 "see Section 3": This should point specifically to the resource registration API.

• Sec 1.5.1 "token introspection is in use, it": With our decision of late to hold off on requesting IANA registration of the permission JWT claim and its subclaims, indeed we're not building in an official way other than the token introspection object for revealing permissions (at least, technically/interoperably speaking).

• Sec 3 "(Set policy conditions)": This relates somewhat to issue #335 sub-issue c, regarding "separating sequence diagrams for resource configuration by resource owner from resource access by requesting party". However, rather than remove this, FedAuthz rev 06 Sec 3 makes the commentary more useful and specific -- hopefully, anyway -- by saying "Set policy conditions (anytime before deletion/deregistration)".

• Sec 3 ""service provider": Yes, this would be clearer. Will change.

• Sec 3.1.1 (example): Changed to describe a print scope.

• Sec 3.2 "List": Yikes, great catch! Mentioning Delete as well. NOTE: Though this is an editorial fix, we should note it specially for implementers.

• Sec 3.2 (example): We added the example at some point because somebody needed it, so I'm loath to remove it now.

• Sec 4 "token": Actually, the way we phrase things in Grant, when a client makes an initial resource request, it's "without an access token" (we now always add "access" so I've already added that in rev 06), because at that point the RS doesn't even know if the client is UMA-enabled.

• Sec 4 "is possible": Yes, that is less ambiguous. I will reword the sentence all around.

• Sec 5 "RPT": Fixed.

• Sec 5 "defined": Fixed.

• Sec 5 (Fig 5 caption): That's true. Hmm. All of the figures for the endpoints show only success paths. I will make a note to look specially at adding error paths to them all, but will do this in a separate pass. Not sure it would be viable to add error paths to the Grant swimlane, but I think it would be relatively doable (and helpful and compact) to add them to FedAuthz. Your thoughts welcome.

• Sec 5.1 "}": Oops, actually, according to the examples here, the close brace is extraneous and needs to be removed.

• Sec 5.1.1 (strikethrough text): That's now been removed.

• Sec 8 (privacy consideration text): You're correct; the second sentence is not related to the overall privacy consideration. I'll remove it. (I suppose we could question whether this security consideration is related to FedAuthz only, or could reasonably go in Grant. But it does seem like a "separation of responsibilities" topic.)

Thank you once again for your careful reading!

[ciseng]

Thanks Eve. All sound very good. A few additional thoughts/comments/agreements :)

• Sec 3.1: example - OK. Maybe then the example can be even more helpful by saying: directing to the policy-setting interface for the folder once the deleted resource resided to remove policies that are no more valid. I am probably over-thinking here.
• Sec 4- “token” - ah, yes. Sure.
• Sec 5 - Fig. 5 caption: I think error paths can be shown separately (esp. when we have so many questions on errors). An interim fix may be captioning figures like “Token Introspection Endpoint: Success” or sth.

[xmlgrrl]

Good suggestion on Sec 3.1. And good suggestion on Sec 5 figure (and potentially all the relevant figures) too. At least that documents accurately what's being shown (and figures and examples are only non-normative anyway).