Subject: [OAUTH-WG] I-D Action: draft-ietf-oauth-urn-sub-ns-03.txt

From: [email-masked]
Date: Thu, 21 Jun 2012 10:53:17 -0700

A New Internet-Draft is available from the on-line Internet-Drafts directories.
 This draft is a work item of the Web Authorization Protocol Working Group of the IETF.

	Title           : An IETF URN Sub-Namespace for OAuth
	Author(s)       : Brian Campbell
                          Hannes Tschofenig
	Filename        : draft-ietf-oauth-urn-sub-ns-03.txt
	Pages           : 7
	Date            : 2012-06-21

Abstract:
   This document establishes an IETF URN Sub-namespace for use with
   OAuth related specifications.

The IETF datatracker status page for this draft is:
https://datatracker.ietf.org/doc/draft-ietf-oauth-urn-sub-ns

There's also a htmlized version available at:
http://tools.ietf.org/html/draft-ietf-oauth-urn-sub-ns-03

A diff from previous version is available at:
http://tools.ietf.org/rfcdiff?url2=draft-ietf-oauth-urn-sub-ns-03

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

---

From: Mike Jones <[email-masked]>
Date: Thu, 21 Jun 2012 18:14:16 +0000

This draft is much clearer.  Thanks for the quick turn-around.

One question:  You added:
  *Index value: values subordinate to urn:ietf:params:oauth are of the from urn:ietf:params:oauth:<class>:<id> with <class>:<id> as the index value
Why bake the assumption of a two-level structure into the registry?

For instance, you could easily imagine legal and useful registrations of the form <class>:<subclass>:<id>, etc.

Maybe change this to say:
  *Index value: values subordinate to urn:ietf:params:oauth are of the from urn:ietf:params:oauth:<value> with <value> as the index value.  It is suggested that <value> include both a "class" and an "identifier-within-class" component, with the two components being separated by a colon (":"); other compositions of the <value> may also be used.

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of [email-masked]
Sent: Thursday, June 21, 2012 10:53 AM
To: [email-masked]
Cc: [email-masked]
Subject: [OAUTH-WG] I-D Action: draft-ietf-oauth-urn-sub-ns-03.txt

Abstract:

_______________________________________________
OAuth mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/oauth

---

From: Brian Campbell <[email-masked]>
Date: Thu, 21 Jun 2012 12:49:50 -0600

I was trying to write something useful for the "Index value" while
still staying in-line with the previous revisions of doc as well as the
URNs that we've used in the SAML and JWT profiles.  But I agree that
there's no need to unnecessarily restrict it to a two level structure.

---

From: Brian Campbell <[email-masked]>
Date: Thu, 21 Jun 2012 13:04:20 -0600

Assuming that change is made (and I think it should be), the text in
the first paragraph of §3 should be similarly reworked.

http://tools.ietf.org/html/draft-ietf-oauth-urn-sub-ns-03#section-3

---

From: Hannes Tschofenig <[email-masked]>
Date: Thu, 21 Jun 2012 22:12:31 +0300

Hi Mike, 

Thanks for your mail. 

First, I would like to argue for a registry that has more than one level. We need a two level registry because the different extensions have (and will also in the future) have different extension policies. 

The structure of the registry is: urn:ietf:params:oauth:<class>:<id>

On the first level, the <class> part, we have high level functionality that was defined in the core specification. This includes things like 

1) authorization grants (which you call grant-type in your registration request in http://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer-12) 

So, this would be urn:ietf:params:oauth:grant-type

2) client authentication mechanism (which you call client-assertion-type in http://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer-12 but should rather mean something like client-auth-type) 

So, this could be something like urn:ietf:params:oauth:client-auth-type

3) Access Token Types (which is called 'token-type' in http://www.ietf.org/id/draft-ietf-oauth-json-web-token-00.txt)

This is urn:ietf:params:oauth:token-type. 

[PS: The text in the http://tools.ietf.org/html/draft-ietf-oauth-v2-28#section-8.1 for registering new access token types is a bit confusing and I am not sure whether an absolute URI would actually be required even though it makes a lot of sense.]

While I believe that our initial requirement for "RFC required" for adding these top level classes makes sense since these basic extension features to OAuth are really core to the protocol functionality it is good that the group checks them carefully. 

Then, at the <id> level the individual values reside. For the authorization grant this is 'saml2-bearer' as defined in http://tools.ietf.org/html/draft-ietf-oauth-saml2-bearer-12#section-6. 

So, what is the right policy for adding values under urn:ietf:params:oauth:grant-type? http://tools.ietf.org/html/draft-ietf-oauth-v2-28#section-8.3 says what the policy is. So, instead of re-deciding a new policy for adding entries here it would be good to get it inline with what the policy is in the core spec. 

What could go wrong if the two are not aligned? I actually had that case in the DIME working group. Without going into the details the registry had a much stronger policy (RFC required) than the protocol specification (which only required a specification, if I remember it). The consequence was that people couldn't easily register new values from other organizations since they would fail in the last step when a new registry value had to be created (since IANA then told them 'RFC Required'). Consequently, these other organizations who wanted to get their work done then avoided doing so by misusing other extensions, which was really not good.  

Mike, you have actually been suggesting that a three level category for certain classes of sub-registries is actually OK as well. That may be true and we could relax the text to say that whoever defines the class also decides about the structure of the child elements underneath it.  

What I believe we need to add in the document is to populate the registry with the three URIs (from above; referring to the classes) and pointing to the policy from the core specification. Then, other docs (like draft-ietf-oauth-json-web-token-00.txt) can just put their values in there. 

Ciao
Hannes

---

From: Barry Leiba <[email-masked]>
Date: Thu, 21 Jun 2012 15:28:23 -0400

This one's mostly there.  As Mike and Hannes are discussing, the WG
needs to sort out exactly what goes under "oauth" here.

Here's a suggestion:
Have Section 3 specify that what comes after "oauth" are one or more
tokens, delimited by ":".
Have Section 3 create the registry for the first-level token, "class".
 In your example, that's "grant-type".
Have Section 3 specify that the definition of each "class" token
specifies what comes after it -- how many tokens, and the meaning(s).
Have Section 3 note that certain classes might create new
sub-registries for what goes under them, if necessary.
Have Section 3 note that certain classes might have *no* further
tokens under them.

I realize that there might not be any use cases envisioned right now
for that last one, but it might be a bad idea to forbid it.

Section 5:

   o  Repository: [[not sure about this? this document or
      http://www.iana.org/assignments/oauth]]

Yeh, I've never been sure about that either.  I think what you want
here is "[[The registry created in Section 3.]]".
See RFC 6134 for how I did this with the "sieve" namespace.

Barry

---

From: Hannes Tschofenig <[email-masked]>
Date: Thu, 21 Jun 2012 22:48:05 +0300

Btw, in a discussion with Brian we check the policies for the three extensions in the OAuth core specification

1) Section 8.3.  Defining New Authorization Grant Types

If you don't define additional token endpoint parameters then there is actually no requirement for expert review or a specification. 
It is probably FCFS. 

2) Section 8.1.  Defining Access Token Types

For URIs there seems to be no constraint either although the text talks about limited to vendor-specific implementations. 

3) client_assertion_type is created in http://tools.ietf.org/html/draft-ietf-oauth-assertions-03#section-8.3 

There is no description either for what is required to register a new assertion type into the URN class client_assertion_type. 

(For client authentication mechanisms there is actually no registry in core and therefore there is no policy either.)

Ciao
Hannes

---

From: Brian Campbell <[email-masked]>
Date: Thu, 21 Jun 2012 13:55:13 -0600

I honestly don't understand the push to have additional registries
under urn:ietf:params:oauth?

---

From: Mike Jones <[email-masked]>
Date: Thu, 21 Jun 2012 20:29:35 +0000

I agree that one registry is sufficient.  The number of registrations won't be huge and so having sub-registries seems like overkill.

				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Brian Campbell
Sent: Thursday, June 21, 2012 12:55 PM
To: Barry Leiba
Cc: OAuth WG
Subject: Re: [OAUTH-WG] I-D Action: draft-ietf-oauth-urn-sub-ns-03.txt

I honestly don't understand the push to have additional registries under urn:ietf:params:oauth?

---

From: Brian Campbell <[email-masked]>
Date: Thu, 21 Jun 2012 14:48:39 -0600

> If you don't define additional token endpoint parameters then there is actually no requirement for expert review or a specification.

That raises a different question/issue.

My understanding of the core spec was that it used URIs in extension
points that might be profiled by actual specifications as well as by
vendor-specific or other less rigorous implementations.

To the extent that's true, §8.3 of OAuth core[1] is problematic in
that it allows for any URI defining the grant type but requires
additional parameters the grant type might use to be registered in the
The OAuth Parameters Registry (and new grant types will most likely
need additional parameters).

Inf fact, I've already got a vendor-specific grant type that uses an
unregistered parameter on the token endpoint - it's a simple grant
type for access token introspection [2]. At the time I was thinking
the parameter was implicitly qualified by the grant type and this was
all okay. But looking at it again, per the letter of the spec, this
would seem to be a violation. But what should we have done? How does a
vendor-specific extension go about registering a parameter? Would that
even be a good idea?

[1] http://tools.ietf.org/html/draft-ietf-oauth-v2-28#section-8.3
[2] http://documentation.pingidentity.com/display/PF66/Grant+Type+Parameters#GrantTypeParameters-1079271

---

From: Brian Campbell <[email-masked]>
Date: Thu, 21 Jun 2012 15:07:01 -0600

As far as the rest of the policy discussion, I have no interest or
intent to define policy for this stuff. A year+ ago I needed a URI for
the SAML grant type. It could be anything but it should be something
stable. And it'd be nice if it was semi-meaningful.  I was using
http://openid.net or something for a while and there were concerns
about ownership and stability. Also because SAML grant was an IETF
draft, it seed to make sense to have an IETF URI. I didn't know how to
get one so I asked. Eventually Hannes suggested the text that became
draft-ietf-oauth-urn-sub-ns. A few more things came along that
similarly needed URIs (JWT grant and client assertion auth) so it
seemed to be working out well. Very little changed in that draft for
nearly a year until the AD review yesterday brought up some
deficiencies. I tried to address those in -03 today (and would like to
do a -04 soon with the minor changes Mike suggested).

With that said, all I really wanted was an easy way to reserve or
register a stable and somewhat meaningful URI. It's proven not to be
easy, however. Adding additional sub-registries and policy to
urn:ietf:params:oauth, which will probably only ever have a few values
in it,  seems to me to be unnecessarily adding a lot of overhead to it
all.

Perhaps I'm mistaken but wouldn't Expert Review catch URIs that are
just wrong prior to registration? And even if it didn't, what really
is the harm?

---

From: Barry Leiba <[email-masked]>
Date: Thu, 21 Jun 2012 17:10:12 -0400

> I agree that one registry is sufficient.  The number of registrations won't be
> huge and so having sub-registries seems like overkill.

No, there was no "push"; I was just making a suggestion for how things
might be set up.  If there's no need envisoned for sub-registries,
that's fine.

b

---

From: Brian Campbell <[email-masked]>
Date: Thu, 21 Jun 2012 15:18:01 -0600

Thanks for clarifying Barry. And my apologies if I interpreted more
"push" in your comments than there really was.

I honestly can't envision the need for sub-registries so believe that
a single one is more than sufficient.

---

From: "Manger, James H" <[email-masked]>
Date: Fri, 22 Jun 2012 16:09:02 +1000

> In fact, I've already got a vendor-specific grant type that uses an
> type for access token introspection [2].
>
> [2]
> http://documentation.pingidentity.com/display/PF66/Grant+Type+Parameter
> s#GrantTypeParameters-1079271

Why are you trying to overload this new functionality onto a URI used for other purposes?
Why not just pick a URI specifically for your purpose, eg /as/validate?

--
James Manger

---

From: Stephen Farrell <[email-masked]>
Date: Fri, 22 Jun 2012 13:06:25 +0100

I'll wait until the chairs tell me what you want
but I'm fine with doing the IETF LC on -03 now, or
with waiting if the chairs reckon that's better.
So just let me know.

Cheers,
S.

---

From: Brian Campbell <[email-masked]>
Date: Fri, 22 Jun 2012 07:39:45 -0600

Unless there are objections from the WG, I'd like to publish -04 today
with two smallish changes (new text listed below) to address the
question raised yesterday in
http://www.ietf.org/mail-archive/web/oauth/current/msg09381.html and
have -04 be the draft for LC.

First paragraph of §3:
 "If a registrant wishes to have a OAuth URI registered, then a URN of
   the form urn:ietf:params:oauth:<value> will be requested where
   <value> is a suitable representation of the functionality or concept
   being registered."

Index value bullet of §5.1
   "Index value: values subordinate to urn:ietf:params:oauth are of
      the from urn:ietf:params:oauth:<value> with <value> as the index
      value.  It is suggested that <value> include both a "class" and an
      "identifier-within-class" component, with the two components being
      separated by a colon (":"); other compositions of the <value> may
      also be used.

Thanks,
Brian

---

From: Peter Saint-Andre <[email-masked]>
Date: Fri, 22 Jun 2012 09:12:56 -0600

>       separated by a colon (":"); other compositions of the <value> may

WFM.

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Hannes Tschofenig <[email-masked]>
Date: Sat, 23 Jun 2012 15:38:14 +0300

Hi Brian, 

you typically do not dump unrelated parameters into the same registry. 

Think of a registry as a table. A table has a policy that is executed when IANA gets a request for adding a new row to the table. A table also has columns, namely those that we define in our documents.

An example of such a table can be found here: 
http://www.iana.org/assignments/params/params.xml

The policy for adding new rows is 'IETF Consensus'. 

Now, it would have been possible to dump all the values from the sub-registries (XML, sieve, etc.) into this table. Since each of these sub-registries have different policies for adding new values this would have been totally confusing for readers and for IANA. 

It would also be confusing for the reader when it looks for XML schema registries (see http://www.iana.org/assignments/xml-registry/schema.html) to also find the sieve registry values in there (see http://www.iana.org/assignments/sieve-extensions/sieve-extensions.xml). 

You are essentially suggesting to dump everything into the same table. While this is theoretically possible it does not offer any obvious advantage. Creating sub-registries in the draft-ietf-oauth-urn-sub-ns just requires a few more lines of text and we will manage to write that text. 

Ciao
Hannes

---

From: Hannes Tschofenig <[email-masked]>
Date: Sat, 23 Jun 2012 15:39:08 +0300

Hi Mike, 

in a previous mail you wanted to even be more flexible by having not only two levels but potentially three levels. 
Now, you say one registry is sufficient. 

That does not make sense. 

Ciao
Hannes

---

From: Hannes Tschofenig <[email-masked]>
Date: Sat, 23 Jun 2012 17:30:19 +0300

Hi Brian, 

Hi Brian, 

> That raises a different question/issue.
It is a related issue. 

The core document says you need an URI for defining new extensions and that means everyone can almost do whatever they want (as I tried to explain in this mail). Note that I saw "almost" -- as you will see below.  

> vendor-specific or other less rigorous implementations.

Correct. 

For the extensions that are registered under urn:ietf:params:oauth we do, however, need to define the policy. 

> need additional parameters).

I agree with you. 

> vendor-specific extension go about registering a parameter? Would that

The URN you have chosen for your product (urn:pingidentity.com:oauth2:validated_token) is, however, IMHO incorrect. There is no URN registered that starts with urn:pingidentity.com (see http://www.iana.org/assignments/urn-namespaces/urn-namespaces.xml) but I am happy to be educated otherwise. 

You could have just used http://www.pingidentity.com/oauth2/validated_token (or anything like that). The problem with that is that some folks will then try to do a lookup on this URI and will, surprise - surprise, not find anything because this URI is just meant for a different purpose. That's the only problem. 

Of course we could also allow a vendor specific branch in the URN we are defining (something which uses a enterprise id, see http://www.iana.org/assignments/enterprise-numbers). 

Ciao
Hannes

---

From: Hannes Tschofenig <[email-masked]>
Date: Sat, 23 Jun 2012 17:41:23 +0300

Hi Brian, 

On Jun 22, 2012, at 12:07 AM, Brian Campbell wrote:

> get one so I asked.

This all makes sense. 

> Eventually Hannes suggested the text that became
> seemed to be working out well.

It indeed does work in the way you had envisioned. 

> Very little changed in that draft for

Fully understand that. 

With many drafts few people read through them in detail only when the last call for comment starts. 

> in it,  seems to me to be unnecessarily adding a lot of overhead to it

What is the overhead? 

If you want a new URN for a new grant type then you 

1) pick an string that has not been used before (you see in the registry what others had put in there already. 
Example: foo-bar 

2) you stick it to urn:ietf:params:oauth:grant-type: 
Example: urn:ietf:params:oauth:grant-type:foo-bar

If you instead want to define a new assertion type you will have to stick it to urn:ietf:params:oauth:client-assertion-type:

Then, you send that request to IANA (with the template we defined in the draft). 

The only discussion point we are having is whether 
* you have to add a link to the specification that defines what this foo-bar grant type is, 
* whether there is any review following the registration. 

That's all.

Does not sound very complicated to me. 

> just wrong prior to registration? And even if it didn't, what really

With expert review you, for example, do not have to add a pointer to the specification to the registry. 
The expert obviously has to get the document since otherwise he wouldn't know what to do. 

In your example from above would you be OK to stick the link to the document into the registry? 

Ciao
Hannes

---

From: Hannes Tschofenig <[email-masked]>
Date: Sat, 23 Jun 2012 17:58:04 +0300

I read through the mails exchanges again and I believe I understand what you want. 

You like the idea of hierarchies in the identifiers (which is what the URNs you are using in your documents actually do right now) but you don't want to call them hierarchies (because it sounds complex). 

Have a look what Section 3 of http://tools.ietf.org/html/rfc3553 says about the colon character (":"). You conceptually want to exactly use that concept but you refuse to call it in that way.

So, you want to register all grant types under urn:ietf:params:oauth:grant-type, such as 
* urn:ietf:params:oauth:grant-type:saml2-bearer, and 
urn:ietf:params:oauth:grant-type:jwt-bearer 
instead of registering them all in one bucket, such as urn:ietf:params:oauth:saml2-bearer and urn:ietf:params:oauth:jwt-bearer

Ciao
Hannes