In working on this just now, here's how I've ended up doing the edits. Section 1.4 now has four bite-sized subsections, a lot more along the lines of OIDC https://openid.net/specs/openid-connect-discovery-1_0.html's structure and more aligned with the rest of our spec: - 1.4: Authorization Server Configuration - 1.4.1 Configuration Properties - 1.4.2 Configuration Document - 1.4.3 Requests to Authorization Server for Configuration Document - 1.4.4 Authorization Server Response Containing Configuration Document Aligning with their text also means we now have more rigor: - There is now language that supports what to do around a non-empty issuer value in the .well-known path. - We no longer erroneously say that /.well-known/uma[2]-configuration is a directory, vs. a document. - We say what's returned is a JSON object that needs to be application/json. - We say the response needs to use 200 OK. If any of this gives you heartburn, let me know now so we can discuss it. One question I have is whether we should make our Section 1.4 into a Section 2, which would obviously push out the numbering of our other big sections. I've gone back and forth in my thinking on this over time, but it probably doesn't matter that much. *Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl On Fri, Nov 4, 2016 at 10:15 AM, Eve Maler wrote:

Here is how *OIDC* refers to all of this.

The relevant spec is called OpenID Connect *Discovery*. However, "discovery" in this context refers primarily to OpenID Provider Issuer discovery, which means determining the location of the OpenID Provider by means of webfinger given an identifier that was input by a user. This takes up all of Section 2. Discovery is optional.

Section 3 *catalogues* OpenID Provider *metadata*, the equivalent of what we are currently calling *configuration data* for an UMA authorization server.

Section 4 describes the *process* of obtaining *configuration information*, which seems to be a synonym for what was just previously catalogued as metadata. The well-known location is, in fact, called /.well-known/openid-configuration. There's a GET request called a "configuration request", and the OP's response is called a "configuration response". (This spec accounts for a process of configuration information validation, something we hadn't thought of yet. Also dictating how to do string comparisons. Nice.)

====

Here is how *OAuth* refers to all of this.

The relevant spec is called OAuth Authorization Server *Metadata* https://tools.ietf.org/html/draft-ietf-oauth-discovery-04, but note that the IETF I-D is ietf-oauth-discovery. The spec postdates and is attempting to align with OIDC.

Section 2 catalogues the metadata. (It also explicitly accounts for how to sign bundles of values, which is a nice added capability.)

Section 3 discusses, in a framework sort of way, how the metadata MUST be made available at a /.well-known location whose name MUST be IANA-registered. The word *configuration* is thrown around a lot wrt what the JSON document might be called, but this isn't required. The word "discovery" doesn't come up.

====

Here is a proposal for people to throw tomatoes at.

- Continue to use "/.well-known/uma2-configuration" for the well-known location. Rationale: This is consistent with what both OIDC and OAuth (in spirit) do. - Use "configuration data" / "configuration document" to describe the information about the authorization server endpoints etc. Rationale: "Metadata" as an additional word adds no value and actually seems confusing in the OIDC case. "Configuration" is consistent with at least one version of what both OIDC and OAuth conceive this information to be, and "data" is shorter than "information". And it's what we do now. :-) - Use the word "discovery" only in the context of describing actual discovery: say, when the RS gives the client the as_location, or when the client learns a protected resource's location out of band of UMA, etc. - Align other wording passages with the OIDC spec wording wherever possible. - Add something about configuration data validation a la OIDC. - Check that we have covered all cases of string comparisons a la OIDC. - Discuss whether to add signed configuration data bundles a la OAuth.

*Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl

On Tue, Nov 1, 2016 at 6:06 PM, Eve Maler wrote:

...

https://github.com/KantaraInitiative/wg-uma/issues/256

This is one of a series of messages meant for discussion of naming of entities and concepts. This message consolidates *configuration/discovery* terms from the GitHub issue:

- configuration data (original) - discovery document (proposed; might change the name of the directory -- or should it be file? -- where the metadata resides)

For now, let's please discuss only in email, unless we're all somehow magically aligned by the time we get to the next call.

*Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl

Thanks for the feedback. *Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl On Sat, Nov 12, 2016 at 9:38 PM, Justin Richer wrote:

+1 to these changes.

— Justin

On Nov 12, 2016, at 1:25 AM, Eve Maler wrote:

In working on this just now, here's how I've ended up doing the edits.

Section 1.4 now has four bite-sized subsections, a lot more along the lines of OIDC https://openid.net/specs/openid-connect-discovery-1_0.html's structure and more aligned with the rest of our spec:

- 1.4: Authorization Server Configuration - 1.4.1 Configuration Properties - 1.4.2 Configuration Document - 1.4.3 Requests to Authorization Server for Configuration Document - 1.4.4 Authorization Server Response Containing Configuration Document

Aligning with their text also means we now have more rigor:

- There is now language that supports what to do around a non-empty issuer value in the .well-known path. - We no longer erroneously say that /.well-known/uma[2]-configuration is a directory, vs. a document. - We say what's returned is a JSON object that needs to be application/json. - We say the response needs to use 200 OK.

If any of this gives you heartburn, let me know now so we can discuss it.

One question I have is whether we should make our Section 1.4 into a Section 2, which would obviously push out the numbering of our other big sections. I've gone back and forth in my thinking on this over time, but it probably doesn't matter that much.

*Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl

On Fri, Nov 4, 2016 at 10:15 AM, Eve Maler wrote:

...

Here is how *OIDC* refers to all of this.

The relevant spec is called OpenID Connect *Discovery*. However, "discovery" in this context refers primarily to OpenID Provider Issuer discovery, which means determining the location of the OpenID Provider by means of webfinger given an identifier that was input by a user. This takes up all of Section 2. Discovery is optional.

Section 3 *catalogues* OpenID Provider *metadata*, the equivalent of what we are currently calling *configuration data* for an UMA authorization server.

Section 4 describes the *process* of obtaining *configuration information*, which seems to be a synonym for what was just previously catalogued as metadata. The well-known location is, in fact, called /.well-known/openid-configuration. There's a GET request called a "configuration request", and the OP's response is called a "configuration response". (This spec accounts for a process of configuration information validation, something we hadn't thought of yet. Also dictating how to do string comparisons. Nice.)

====

Here is how *OAuth* refers to all of this.

The relevant spec is called OAuth Authorization Server *Metadata* https://tools.ietf.org/html/draft-ietf-oauth-discovery-04, but note that the IETF I-D is ietf-oauth-discovery. The spec postdates and is attempting to align with OIDC.

Section 2 catalogues the metadata. (It also explicitly accounts for how to sign bundles of values, which is a nice added capability.)

Section 3 discusses, in a framework sort of way, how the metadata MUST be made available at a /.well-known location whose name MUST be IANA-registered. The word *configuration* is thrown around a lot wrt what the JSON document might be called, but this isn't required. The word "discovery" doesn't come up.

====

Here is a proposal for people to throw tomatoes at.

- Continue to use "/.well-known/uma2-configuration" for the well-known location. Rationale: This is consistent with what both OIDC and OAuth (in spirit) do. - Use "configuration data" / "configuration document" to describe the information about the authorization server endpoints etc. Rationale: "Metadata" as an additional word adds no value and actually seems confusing in the OIDC case. "Configuration" is consistent with at least one version of what both OIDC and OAuth conceive this information to be, and "data" is shorter than "information". And it's what we do now. :-) - Use the word "discovery" only in the context of describing actual discovery: say, when the RS gives the client the as_location, or when the client learns a protected resource's location out of band of UMA, etc. - Align other wording passages with the OIDC spec wording wherever possible. - Add something about configuration data validation a la OIDC. - Check that we have covered all cases of string comparisons a la OIDC. - Discuss whether to add signed configuration data bundles a la OAuth.

*Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl

On Tue, Nov 1, 2016 at 6:06 PM, Eve Maler wrote:

...

https://github.com/KantaraInitiative/wg-uma/issues/256

This is one of a series of messages meant for discussion of naming of entities and concepts. This message consolidates *configuration/discovery* terms from the GitHub issue:

- configuration data (original) - discovery document (proposed; might change the name of the directory -- or should it be file? -- where the metadata resides)

For now, let's please discuss only in email, unless we're all somehow magically aligned by the time we get to the next call.

*Eve Maler*Cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl

_______________________________________________ WG-UMA mailing list WG-UMA@kantarainitiative.org http://kantarainitiative.org/mailman/listinfo/wg-uma