Subject: Link Relations registrations for OAuth

From: William Mills <[email-masked]>
Date: Wed, 10 Oct 2012 06:58:34 -0700 (PDT)

Please register the following link relations detailed below.

Thanks,

-bill mills

----------------

OAuth 2 Authorization Endpoint

    * Relation Name: oauth2-authorize
    * Description: An OAuth 2.0 authorization endpoint.
    * Reference: [I-D.ietf-oauth-v2] Hammer-Lahav, E, Recordon, D and D Hardt, "The OAuth 2.0 Authorization Framework", Internet-Draft draft-ietf-oauth-v2-26, May 2012.
    * Notes: This link type indicates an OAuth 2.0 authorization endpoint that can be used for user authentication/authorization for the endpoint providing the link.
    * Application Data: 

OAuth 2 Token Endpoint

    * Relation Name: oauth2-token
    * Description: The OAuth token endpoint used to get tokens for access.
    * Reference: [I-D.ietf-oauth-v2] Hammer-Lahav, E, Recordon, D and D Hardt, "The OAuth 2.0 Authorization Framework", Internet-Draft draft-ietf-oauth-v2-26, May 2012.
    * Notes: The OAuth 2.0 token endpoint to be used for obtaining tokens to access the endpoint providing the link.
    * Application Data: This link type has two link-extensions:
 grant-types:
A space separated list of OAuth 2.0 grant types (see section 4 of [I-D.ietf-oauth-v2]) that can 
be used at the token endpoint to obtain a token. This is not an exclusive list, it provides a hint 
to the application of what SHOULD be valid. A token endpoint MAY support additional grant 
types not advertised by a discovery service. The client MAY use this to determine the grant 
types available for use.
token-types:
A space separated list of OAuth 2.0 token types (see section 7.1 of [I-D.ietf-oauth-v2]) that 
may be issued by the token endpoint. It is possible for a token endpoint to issue multiple 
tokens, and types may vary based on scope or other factors. This is not an exclusive list, it 
provides a hint to the application of what SHOULD be valid, and it MAY be used by a client to 
determine if the client supports one or more of the token type(s) available.

OAuth 1.0a Request Initiation Endpoint
    * Relation Name: oauth-initiate
    * Description: The OAuth 1.0a request initiation endpoint used to get an access request.
    * Reference: [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, April 2010. 
    * Notes: The OAuth 1.0a endpoint used to initiate the sequence, this temporary request is what the user approves to grant access to the resource.
    * Application Data:

OAuth 1.0a Authorization Endpoint
    * Relation Name: oauth-authorize
    * Description: The OAuth 1.0a authorization endpoint used to approve an access request.
    * Reference: [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, April 2010. 
    * Notes: Expected to be a user interactive web interface.
    * Application Data:

Token Endpoint
    * Relation Name: oauth-token
    * Description: The OAuth 1.0a token endpoint used to exchange an approved access request for a token.
    * Reference: [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, April 2010. 
    * Notes:
    * Application Data:

---

From: Julian Reschke <[email-masked]>
Date: Wed, 10 Oct 2012 17:06:15 +0200

Hi William,

I' afraid it's not *that* easy, see comments inline.

> Please register the following link relations detailed below.

The reference should point to a document that actually defines the link 
relation. As far as I can tell, this is not that case here.

Either add the actual definition to draft-ietf-oauth-v2, or have a 
separate document defining it.

>      * Application Data: This link type has two link-extensions:

See above.

Also: "Application Data" is additional meta data to be added to the 
registry. What you have here are additional parameters to the link 
relation, which is something completely different (and also something 
that I think should be avoided).

>      * Reference: [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, April 2010.

...again, see above: the reference actually needs to define the link 
relation (the registry should contain *pointers* to definitions, not the 
definitions themselves).

Best regards, Julian

---

From: Barry Leiba <[email-masked]>
Date: Wed, 10 Oct 2012 11:12:39 -0400

> I' afraid it's not *that* easy, see comments inline.
...
> separate document defining it.

Julian, I don't agree, and I'm the one who told him that he should do
it this way.

The only thing that has to be published in a stable, public document
is the reference, not the registration request.

Why do you think the registration request needs to be published in an RFC?

Barry

---

From: Julian Reschke <[email-masked]>
Date: Wed, 10 Oct 2012 17:24:57 +0200

> Why do you think the registration request needs to be published in an RFC?

I didn't say that.

What needs to be published in an RFC (or stable spec...) is the actual 
description of the link relation.

Best regards, Julian

---

From: Barry Leiba <[email-masked]>
Date: Wed, 10 Oct 2012 11:32:45 -0400

> description of the link relation.

Ah.  IOW, you're saying that the OAuth specs describe OAuth, but not
the link relation, so they are not the correct references to use.
I'll buy that.

Which means that my too-quick advice to Bill needs to be rescinded,
and the correct advice is something like this:

------------------------
>    * Reference: [I-D.ietf-oauth-v2]
>    * Notes: This link type indicates an OAuth 2.0 authorization endpoint
>      that can be used for user authentication/authorization for the endpoint providing the link.
>    * Application Data:

draft-ietf-oauth-v2 is not a correct and useful reference for this
link relation.  You'll need to go back to your original document and
use it to document the link relation specifically, and in THAT
documentation refer to draft-ietf-oauth-v2 as appropriate.  Then that
document can register the link relation with a reference to itself,
which will in turn have a reference to draft-ietf-oauth-v2.

And similarly for the other four link relations you're requesting.
------------------------

Julian, does that seem right?

Bill, that document can be Informational, and can either be
AD-sponsored or go through the Independent Stream.

Barry

---

From: Julian Reschke <[email-masked]>
Date: Wed, 10 Oct 2012 17:39:15 +0200

> the link relation, so they are not the correct references to use.

Exactly.

> and the correct advice is something like this:

Absolutely.

In case these link relations have the OAuth WG consensus, it might also 
be possible to add them to the OAuth spec itself (not sure about timing 
& scope, though).

Best regard, Julian

---

From: Barry Leiba <[email-masked]>
Date: Wed, 10 Oct 2012 11:41:57 -0400

>> AD-sponsored or go through the Independent Stream.

Great.  Then, Bill, I'm sorry I initially steered you wrong, but the
correct answer is that you need to beef up the document a bit, with a
section describing each link relation.  Then the document will not
just be nothing more than an IANA Considerations section, but will
actually have some documentation in it.

> In case these link relations have the OAuth WG consensus, it might also be
> possible to add them to the OAuth spec itself (not sure about timing &
> scope, though).

No, that's not happening.  The OAuth v1 doc is an RFC, and the OAuth
v2 doc is in AUTH48 now.

b

---

From: William Mills <[email-masked]>
Date: Wed, 10 Oct 2012 09:04:19 -0700 (PDT)

OK, I'll beef up each link relation section a bit with descriptive text.  Easily done.

Is there an advantage to the AD process or Independent Stream?  I'm happy to do either, but I'm not familiar with either so I need to know next steps please.

Regards,

-bill

----- Original Message -----
From: Barry Leiba <[email-masked]>
To: Julian Reschke <[email-masked]>
Cc: William Mills <[email-masked]>; [email-masked]
Sent: Wednesday, October 10, 2012 8:32 AM
Subject: Re: Link Relations registrations for OAuth

------------------------

Barry

---

From: Julian Reschke <[email-masked]>
Date: Wed, 10 Oct 2012 18:27:54 +0200

> Is there an advantage to the AD process or Independent Stream?  I'm happy to do either, but I'm not familiar with either so I need to know next steps please.

I don't think it matters a lot.

An AD sponsoring it will probably help process-wise. On the other hand, 
it would be nice to demonstrate that we don't *need* an AD here, so it 
would also be nice to test the Independent Stream approach.

Best regards, Julian

---

From: Barry Leiba <[email-masked]>
Date: Wed, 10 Oct 2012 12:38:00 -0400

>> Is there an advantage to the AD process or Independent Stream?  I'm happy
>> to do either, but I'm not familiar with either so I need to know next steps
>> please.
>

I agree.

> An AD sponsoring it will probably help process-wise. On the other hand, it
> would be nice to demonstrate that we don't *need* an AD here, so it would
> also be nice to test the Independent Stream approach.

We're already testing it with Herbert van de Sompel's document.

The difference is that an Independent Stream document goes directly to
the RFC Editor (the Independent Stream Editor (ISE), specifically);
see http://www.rfc-editor.org/indsubs.html
Those documents can't be Standards Track or BCP, but that doesn't
matter here (it'll be Informational either way).  The ISE will review
it, and wil send it to a couple of other reviewers.  It will then go
to the IESG for a check that it's not trying to skirt IETF process and
doesn't interfere with IETF work (in this case, that's an easy pass,
but it takes a couple of weeks in the schedule).  The document will be
published with boilerplate that does not say that it has the consensus
of the IETF community.  I don't know how long the ISE is taking to
review and approve documents.

With an AD-sponsored document, you need to get an AD (I'll do it, once
the designated experts have given their approval for the
registrations), and then the document goes out for a four-week IETF
last call.  Then it gets put on an IESG telechat for formal approval,
and the IESG can evaluate it and ask for changes.  The likely time
frame is 5 or 6 weeks from the time the document gets approval from
the designated experts to the time it gets IESG approval, though it
can be longer if there are a lot of IESG comments.

In either case, it then goes to the RFC Editor queue, and IANA can
make the registration.

I suggest you go for the AD sponsorship path, since you do have a
willing AD.  When you have the document changes, post back to this
list.  When the DEs say it's ready for approval, I'll send out the
IETF last call.

Barry