Subject: [OAUTH-WG] Proposal for a New 2617 Scheme: Token

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 1 Oct 2009 16:12:01 -0700

This is my draft proposal for replacing the auth scheme defined in the authentication draft in the upcoming version. Feedback requested!

Background

OAuth Core 1.0 uses the 'oauth' scheme name in HTTP authentication headers. It also uses the oauth_version="1.0" parameter to indicate the authentication version used. The version parameter has been poorly defined in the 1.0 spec and therefore provides little transitional value. We also know that we are going to change the version number of the protocol (I am advocating a 2.0 approach instead of the initial 1.1 direction). I think it is better to drop version numbers in favor of using different scheme names to identify different version.

Unlike Basic and Digest which are based on a username/password pair, OAuth is based on a Token/Secret pair. The distinction between username and token isn't just technical but has an application meaning. Username implied direct access while Token implies delegated access. It is important to make sure a server can reply to a protected resource request with more than one auth header to indicate that both usernames and tokens are welcomed. This is why we cannot use Basic or Digest to send token credentials, even if the two protocols provide all the necessary technical coverage.

Given the recent discussion about the requirement to use the HTTP authentication headers, I am proposing that (for the time being) we drop support for form-encoded or URI query authorization parameters. We can discuss adding some form of support for non-header delivery of authentication parameters later but that will require special handling and other headers to prevent breaking the web.

Proposal

The new scheme (I am proposing 'Token' as scheme name but an open for other suggestions) will replace the 'OAuth' scheme name and will use the following syntax (please help with an ABNF version please...):

	WWW-Authenticate: Token <sub-scheme> realm="", <sub-scheme-param>, ...
	Authorization: Token <sub-scheme> <token>, <sub-scheme-param>, ...

Core sub-schemes:

* Plain - Just like Basic without base64 encoding (since it really adds not value and just a waste of time):

	WWW-Authenticate: Token Plain realm=""

	Authorization: Token Plain <token> <secret>

* HMAC - Similar to the Core 1.0 signature method (with hopefully simpler normalization rules):

	WWW-Authenticate: Token HMAC realm="", algorithm="SHA1 SHA2 MD5"

	Authorization: Token HMAC <token> algorithm="SHA1", nonce="", timestamp="", digest="", body-hash=""

	(the 'body-hash' is an optional parameter that if included, must also be included in the HMAC text)

I am purposely not including the RSA option since it is no sufficiently defined. If there is a need for it (Google was the only company asking for it and they now support other alternatives) we can discuss how to implement it in this new proposal.

We should establish a registry for new sub-schemes and use an established registry for algorithm names.

EHL

---

From: John Panzer <[email-masked]>
Date: Thu, 1 Oct 2009 16:33:07 -0700

On Thu, Oct 1, 2009 at 4:12 PM, Eran Hammer-Lahav <[email-masked]>wrote:

> This is my draft proposal for replacing the auth scheme defined in the
> authentication draft in the upcoming version. Feedback requested!
>
> Background
>
> OAuth Core 1.0 uses the 'oauth' scheme name in HTTP authentication headers.
> It also uses the oauth_version="1.0" parameter to indicate the
> authentication version used. The version parameter has been poorly defined
> in the 1.0 spec and therefore provides little transitional value. We also
> know that we are going to change the version number of the protocol (I am
> advocating a 2.0 approach instead of the initial 1.1 direction). I think it
> is better to drop version numbers in favor of using different scheme names
> to identify different version.
>
> Unlike Basic and Digest which are based on a username/password pair, OAuth
> is based on a Token/Secret pair. The distinction between username and token
> isn't just technical but has an application meaning. Username implied direct
> access while Token implies delegated access. It is important to make sure a
> server can reply to a protected resource request with more than one auth
> header to indicate that both usernames and tokens are welcomed. This is why
> we cannot use Basic or Digest to send token credentials, even if the two
> protocols provide all the necessary technical coverage.
>
> Given the recent discussion about the requirement to use the HTTP
> authentication headers, I am proposing that (for the time being) we drop
> support for form-encoded or URI query authorization parameters. We can
> discuss adding some form of support for non-header delivery of
> authentication parameters later but that will require special handling and
> other headers to prevent breaking the web.
>
> Proposal
>
> The new scheme (I am proposing 'Token' as scheme name but an open for other
> suggestions) will replace the 'OAuth' scheme name and will use the following
> syntax (please help with an ABNF version please...):
>

Is the realm literally just an empty string (for compatibility with RFC
2617)?

> I am purposely not including the RSA option since it is no sufficiently
> defined. If there is a need for it (Google was the only company asking for
> it and they now support other alternatives) we can discuss how to implement
> it in this new proposal.
>

I think RSA should be included.

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

---

From: Brian Eaton <[email-masked]>
Date: Thu, 1 Oct 2009 16:44:19 -0700

On Thu, Oct 1, 2009 at 4:12 PM, Eran Hammer-Lahav <[email-masked]> wrote:
> The new scheme (I am proposing 'Token' as scheme name but an open for other suggestions) will
> replace the 'OAuth' scheme name and will use the following syntax
> (please help with an ABNF version please...):

Any pressing reason to change from "OAuth" to "Token"?

>        WWW-Authenticate: Token <sub-scheme> realm="", <sub-scheme-param>, ...

Should probably drop "realm" unless we can define the semantics.  (I can't.)

I think that the ABNF should probably just be the prefix, followed by
name-value pairs.  I don't see a reason to have a separate sub-scheme.

Out of curiosity, what would people think if instead of defining
yet-another-serialization-format, we used JSON for this, e.g.

WWW-Authenticate: Token <json>

> I am purposely not including the RSA option since it is no sufficiently defined.
> If there is a need for it (Google was the only company asking for it and they now
> support other alternatives) we can discuss how to implement it in this new proposal.

RSA is important.  Public key crypto is a building block we shouldn't
leave out.  Not having it means we can't ever do any kind of automatic
consumer discovery.

That said, RSA might only get used when requesting access tokens, not
when using them.  There is no RSA private key associated with an
access token, so it's kind of hard to use it. =)

Cheers,
Brian

---

From: "Manger, James H" <[email-masked]>
Date: Fri, 2 Oct 2009 10:33:28 +1000

> It is important to make sure a server can reply to a protected resource request
> with more than one auth header to indicate that both usernames and tokens are welcomed.
> This is why we cannot use Basic or Digest to send token credentials,
> even if the two protocols provide all the necessary technical coverage.

I think that reasoning is wrong. Different "realm" values can indicate different credential groups if necessary (username vs token) while using the same scheme.

RFC 2617 "HTTP Authentication" explicitly states:
  "Note that there may be multiple challenges with the same auth-scheme but
   different realms."

A server can quite legitimately return:
  401 Unauthenticated
  WWW-Authentication: BASIC realm="User access"
  WWW-Authentication: BASIC realm="Delegated app access"

Web browsers (at least IE8 and FF3) just act on the first of these header -- which is what we want.

When issuing a token, OAuth could indicate the realm to which the token applies so a client knows which WWW-Authentication header is appropriate.
When issuing a token, OAuth should indicate the authentication mechanism(s) allowed with the token, which also helps the client pick an appropriate WWW-Authentication header.

Accepting usernames and tokens will not generally be a problem as any caller (a user's browser or an OAuth client) will only have one or the other -- it just uses what it has.

It may be trickier if servers need to indicate that OAuth client credentials (eg app-id/app-secret) and delegation credentials (token/secret) can both be used to access a given protected resource. Different realms are one solution. Often the client will know which credentials are appropriate as it knows the context in which it is making the call. If it is too hard, servers can just use different URIs for access by users, clients-as-themselves, and clients-on-behalf-of-users.

James Manger
[email-masked]
Identity and security team — Chief Technology Office — Telstra

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 1 Oct 2009 18:31:15 -0700

> -----Original Message-----
> From: Brian Eaton [mailto:[email-masked]]
> Sent: Thursday, October 01, 2009 4:44 PM

> Should probably drop "realm" unless we can define the semantics.  (I

I think 2617 defines realm pretty well. It is a URI string that identifies the set of resources accessible with a given credential. If you feel we need to spell out the lessons (restrictions) learned from Basic, we can look into that.
 
> name-value pairs.  I don't see a reason to have a separate sub-scheme.

Why define a parameter when it is clearly a sub-scheme? I makes client much simpler by being able to look for the first two words in the header and known what is going on. Otherwise we need to define a certain order for parameters which is ugly.
 
> WWW-Authenticate: Token <json>

That's crazy talk.
 
> access token, so it's kind of hard to use it. =)

Then we need to define how it works in the context of authentication. Keep in mind that this is ONLY for accessing protected resources once a token has been obtained. We will deal with obtaining tokens separately and there we can include PK support as part of the client credentials package.

EHL

---

From: "Manger, James H" <[email-masked]>
Date: Fri, 2 Oct 2009 11:31:01 +1000

I think OAuth needs:

1. A WWW-Auth scheme indicating that requests can be signed with a shared-secret key.

2. A WWW-Auth scheme indicating that a web delegation flow can be used to get user authorization.

The two are quite separate.
The first would be defined in draft-ietf-oauth-authentication and would make no reference to delegation at all. "MAC" would be a good name.

<-  WWW-Authenticate: MAC realm="whatever"; algorithm="HMAC-SHA1 HMAC-SHA256 CMAC-AES";
                     mode="HEADER URI POST" <perhaps some more parameters>

->  Authorization: MAC realm="whatever"; algorithm="HMAC-SHA256"; sig="65dFM…"; nonce…

The option to encode the signature in a URI is worthwhile (eg a client can sign a URI then give it to another party to access, eg another party to click in a browser). Hence, the "mode" parameter above. I am less convinced by POST, but it is a small step from URI to POST so it is probably worth having.
[HEADER = can put signature in HTTP Authorization request header;
 URI = can put signature in URI query string;
 POST = can put signature in HTML <form> POST]

>	Authorization: Token Plain <token> <secret>

This isn't necessary. Just use BASIC.
A server may need to ensure usernames and tokens can be distinguished, but that is easy enough.

If an RSA-based mechanism is required a separate WWW-Auth scheme would be the best approach.

A WWW-Auth scheme to trigger the delegation flow is more interesting, but that is for a separate thread.

James Manger

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 1 Oct 2009 18:35:20 -0700

> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Manger, James H
> Sent: Thursday, October 01, 2009 5:33 PM

> I think that reasoning is wrong. Different "realm" values can indicate
> different credential groups if necessary (username vs token) while
> using the same scheme.
> 

While it is an interesting idea, I think it is bad design. How is a client supposed to know what to do with this? What is the value of reusing Basic or Digest here? Digest has failed adoption and Basic provides practically zero value. I think this will cause confusion and problems with existing deployments with no real benefits.

EHL

---

From: "Manger, James H" <[email-masked]>
Date: Fri, 2 Oct 2009 12:26:18 +1000

> How is a client supposed to know what to do with this?

This is not enough to trigger a web-delegation flow -- we need another WWW-Auth header for that. Once a client has an id and shared-secret (whether from a web delegation flow, a configuration file, prompting a user operating the client...) the above header tells it to retry the request with a "Authorization: BASIC Zm9vOmJhcg==" header.

If the client was given a realm value when it got the id and shared-secret, then the two headers above indicate if those credentials can be used for this protected resource.
If the client has its own id/secret and another id/secret as a delegate for another user, then the multiple realms can tell it which set the server is asking for.

> Digest has failed adoption

Fine, so we should be wary about reinventing it with "Token HMAC" unless that offers something significantly different. The ability to put the signature in the URI or body is different (but you want to drop that); simplicity may be different enough. Getting the credentials from a delegation flow is not a difference as it should be orthogonal.

> Basic provides practically zero value

I don't understand how "Token Plain" can offer any more value than BASIC.
(Personally I think BASIC is massively useful over HTTPS)

The "Token Plain" and "Token HMAC" WWW-Auth schemes look like a deliberate attempt to keep authentication and web-delegation tightly coupled. This must be unnecessary. I though the whole idea of splitting OAuth into authentication and web-delegation specs was that these are separate concerns. The authentication part is useful even if you didn't get the credentials via delegation. The delegation part is useful whatever authentication mechanism is subsequently used.

It seems like bad design to keep the authentication spec bound to web-delegation (though there will need to be some links in the other direction).

James Manger

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Thu, 1 Oct 2009 20:57:44 -0700

The idea of using the realm value as a differentiator between username-based auth and token-based auth is wrong. This is not what the realm is for and it is already a misused feature. The consensus in the OAuth community has always been against even having realm in the first place, and while I disagree with that, it does indicate that building on top of that is a bad idea.

I would also argue that it should be perfectly valid to use the exact same realm (resource set) with both username-based and token-based credentials. Your proposal breaks that and forces servers to make up new realms that are not based on their server file hierarchy which is the most common approach.

The reality is that Basic and Digest auth are well established and used for username/password authentication. They are widely deployed and to overload them with a new meaning will likely cause more harm than good. At the same time, you are not offering any value by reusing them, other than making the spec shorter. Yes Basic is very useful but who needs the stupid base64 encoding or even the ':' separator between the username and password?

Yes, we need to figure out the discovery of how to get a token from a 401 response. One thing at a time.

EHL

> Sent: Thursday, October 01, 2009 7:26 PM
> To: [email-masked]
> Subject: Re: [OAUTH-WG] Proposal for a New 2617 Scheme: Token
> 
> >>   401 Unauthenticated
> This is not enough to trigger a web-delegation flow -- we need another
> WWW-Auth header for that. Once a client has an id and shared-secret
> (whether from a web delegation flow, a configuration file, prompting a
> user operating the client...) the above header tells it to retry the
> request with a "Authorization: BASIC Zm9vOmJhcg==" header.
> 
> If the client was given a realm value when it got the id and shared-
> secret, then the two headers above indicate if those credentials can be
> used for this protected resource.
> If the client has its own id/secret and another id/secret as a delegate
> for another user, then the multiple realms can tell it which set the
> server is asking for.
> 
> 
> 
> Fine, so we should be wary about reinventing it with "Token HMAC"
> unless that offers something significantly different. The ability to
> put the signature in the URI or body is different (but you want to drop
> that); simplicity may be different enough. Getting the credentials from
> a delegation flow is not a difference as it should be orthogonal.
> 
> 
> The "Token Plain" and "Token HMAC" WWW-Auth schemes look like a
> deliberate attempt to keep authentication and web-delegation tightly
> coupled. This must be unnecessary. I though the whole idea of splitting
> OAuth into authentication and web-delegation specs was that these are
> separate concerns. The authentication part is useful even if you didn't
> get the credentials via delegation. The delegation part is useful
> whatever authentication mechanism is subsequently used.
> 
> It seems like bad design to keep the authentication spec bound to web-
> delegation (though there will need to be some links in the other
> direction).
> 
> 
> 
> James Manger

---

From: Brian Eaton <[email-masked]>
Date: Fri, 2 Oct 2009 09:39:13 -0700

On Thu, Oct 1, 2009 at 6:31 PM, Eran Hammer-Lahav <[email-masked]> wrote:
> I think 2617 defines realm pretty well. It is a URI string that identifies the
> set of resources accessible with a given credential. If you feel we need to
> spell out the lessons (restrictions) learned from Basic, we can look into that.

Except that the mapping from "URI string" to "set of resources" bit
doesn't actually work in practice.  The mappings either tend to be
trivial (in which case realm is unnecessary) or complex (in which case
realm doesn't have a syntax rich enough to describe the problem.)

I can't prove that realm is useless, but I'm pretty sure that if you
give me a dozen examples of possible semantics for "realm" I can break
all of them. =)

> Why define a parameter when it is clearly a sub-scheme? I makes client much
> simpler by being able to look for the first two words in the header and known what is going on.
> Otherwise we need to define a certain order for parameters which is ugly.

Or we can have clients that know to look at the "Token" scheme and
then parse the rest of the header as name/value pairs.  There is no
need to define parameter ordering.

>> WWW-Authenticate: Token <json>

OK. =)

> Then we need to define how it works in the context of authentication. Keep in mind that this is
> ONLY for accessing protected resources once a token has been obtained. We will deal
> with obtaining tokens separately and there we can include PK support as part of the
> client credentials package.

OK, that makes sense.

Cheers,
Brian

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 2 Oct 2009 10:12:34 -0700

In the case of Basic, it is very useful for UI optimization and I think that can translate to OAuth as well. The browser knows it already asked the user for credentials for a given realm and can simply reuse them without having to ask for it again. However, the browsers today look for other bits of information to make sure an evil domain doesn't pretend to have the realm of a good domain, etc.

Also, I think I skipped your comment about why we need a new scheme name (to replace 'OAuth'). I don't want to use the oauth_version parameter but still need a super simple way for clients to figure out that this is another version. It also means that old clients will not try to do something stupid with the wrong OAuth challenge because they don't look at the version.

The version parameter was poorly defined and does not provide enough clarity to reuse the same scheme name.

EHL

> Sent: Friday, October 02, 2009 9:39 AM
> To: Eran Hammer-Lahav
> Cc: [email-masked]

---

From: Justin Hart <[email-masked]>
Date: Fri, 2 Oct 2009 12:12:59 -0600

In the discovery-sense, could realm define the URL to the discovery
document, which would then define the complex validity-realm information as
well as all the appropriate endpoints, etc?  Seems like building that in
could help solve any 'magic' url in the discovery phase.  Seems like a
reasonable use of the parameter.

On Fri, Oct 2, 2009 at 11:12 AM, Eran Hammer-Lahav <[email-masked]>wrote:

> In the case of Basic, it is very useful for UI optimization and I think
> that can translate to OAuth as well. The browser knows it already asked the
> user for credentials for a given realm and can simply reuse them without
> having to ask for it again. However, the browsers today look for other bits
> of information to make sure an evil domain doesn't pretend to have the realm
> of a good domain, etc.
>
> Also, I think I skipped your comment about why we need a new scheme name
> (to replace 'OAuth'). I don't want to use the oauth_version parameter but
> still need a super simple way for clients to figure out that this is another
> version. It also means that old clients will not try to do something stupid
> with the wrong OAuth challenge because they don't look at the version.
>

---

From: Brian Eaton <[email-masked]>
Date: Fri, 2 Oct 2009 12:03:09 -0700

> reasonable use of the parameter.

That approach caused a fundamental security hole in the first OAuth
discovery spec, where an evil resource could steal credentials from a
good credential issuer.  I'm not saying it's not a solvable problem,
but it is complicated, and I just haven't seen a whole lot of use
cases for a generic solution.

(As an example of how completely useless current working definitions
of "realm" really are, check out
http://code.google.com/p/browsersec/wiki/Part3#HTTP_authentication.)

Cheers,
Brian

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 2 Oct 2009 12:16:02 -0700

> Sent: Thursday, October 01, 2009 6:31 PM

> 1. A WWW-Auth scheme indicating that requests can be signed with a

This is too specific. We need a scheme that indicate requests can be made with a token (vs. username).

> to get user authorization.

I am not sure this is the right way to provide delegation discovery (via the auth header). Using Link: headers is much more appropriate.
 
> The first would be defined in draft-ietf-oauth-authentication and would
> make no reference to delegation at all. "MAC" would be a good name.
> 

The syntax differences from my proposal aren't significant. I think there is value in creating a family of authentication methods using a scheme and sub-scheme. It is better to support extensibility in the scheme than to force new methods to define new schemes. This will allow easier implementation of new sub-schemes.
 
> The option to encode the signature in a URI is worthwhile (eg a client
> can sign a URI then give it to another party to access, eg another
> party to click in a browser). Hence, the "mode" parameter above. I am
> less convinced by POST, but it is a small step from URI to POST so it
> is probably worth having.

Header server support should not be optional and hence does not need discovery.

Is it too much to ask all servers to support the URI mode? We are going to make supporting the auth headers mandatory in all implementations. Since we are dropping POST (no use cases, no matter how simple it is to keep) and headers are required, why not require support for a single URI header parameter?
 
> A server may need to ensure usernames and tokens can be distinguished,

Yes it is. The idea of requiring servers to make this distinction is impractical. Basic auth is well defined and any attempt to overload it with new meaning is wrong.
 
> If an RSA-based mechanism is required a separate WWW-Auth scheme would

It is not clear what the RSA requirements are and how they should be managed yet. It should be a sub-scheme.
 
EHL

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Fri, 2 Oct 2009 12:17:12 -0700

There is no reason to overload the realm with new meanings. It is well defined already in 2617.

If we decide to support a discovery method using an external document (XRD, etc.), it should be expressed using a Link header not inside the auth header.

EHL

From: Justin Hart [mailto:[email-masked]]
Sent: Friday, October 02, 2009 11:13 AM
To: Eran Hammer-Lahav
Cc: Brian Eaton; [email-masked]
Subject: Re: [OAUTH-WG] Proposal for a New 2617 Scheme: Token

In the discovery-sense, could realm define the URL to the discovery document, which would then define the complex validity-realm information as well as all the appropriate endpoints, etc?  Seems like building that in could help solve any 'magic' url in the discovery phase.  Seems like a reasonable use of the parameter.
On Fri, Oct 2, 2009 at 11:12 AM, Eran Hammer-Lahav <[email-masked]<mailto:[email-masked]>> wrote:
In the case of Basic, it is very useful for UI optimization and I think that can translate to OAuth as well. The browser knows it already asked the user for credentials for a given realm and can simply reuse them without having to ask for it again. However, the browsers today look for other bits of information to make sure an evil domain doesn't pretend to have the realm of a good domain, etc.

EHL

> From: Brian Eaton [mailto:[email-masked]<mailto:[email-masked]>]
> Cc: [email-masked]<mailto:[email-masked]>
> On Thu, Oct 1, 2009 at 6:31 PM, Eran Hammer-Lahav <[email-masked]<mailto:[email-masked]>>
> wrote:
_______________________________________________
OAuth mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/oauth

---

From: "Manger, James H" <[email-masked]>
Date: Sun, 4 Oct 2009 04:13:21 +1100

> This is too specific. We need a scheme that indicate requests can be made with a token (vs. username).

Eran,

I think some of the disconnect between our ideas revolves around what a 'token' is.

In OAuth, a (access) token is an identifier for a delegation of some authority from a specific user to a client. It is chosen by the server. It is an opaque blob as far as the client is concerned — they just have to include it in subsequent requests.

From the perspective of just the authentication part of OAuth (draft-ietf-oauth-authentication), a token is just an id. I don't see a token as any different from a username, or an app id, or an employee number, or a device id -- as far as any authentication protocol is concerned.

The web hasn't needed different versions of BASIC for users (with usernames) and for applications (generally with long random app-ids).

If we need BASIC for usernames and TOKEN PLAIN for delegation tokens, wont we also need something else for direct access by clients. Mightn't we need a different scheme for tokens issued by the OAuth web-delegation flow vs token issued via some other mechanism?

> I am not sure this is the right way to provide delegation discovery (via the auth header). Using Link: headers is much more appropriate.

A Link header might work. 1 or 2 extra round-trips could be avoid with a WWW-Auth scheme compared to a Link relation, as a WWW-Auth scheme could be more descriptive (more scheme-specific parameters) that seems sensible to cram into a Link relation.

>> ->  Authorization: MAC realm="whatever"; algorithm="HMAC-SHA256";

> The syntax differences from my proposal aren't significant.

Indeed, I wasn't suggesting any change here (other than "MAC" as a better scheme name).

>> I think there is value in creating a family of authentication methods using a scheme and sub-scheme. It is better to support extensibility in the scheme than to force new methods to define new schemes. This will allow easier implementation of new sub-schemes.

So you want the "TOKEN" scheme to mean "delegation credentials", and the sub-scheme to be the authentication mechanism.
I don’t think a special indicator for "delegation credentials" is necessary (use case?). If an indicator is necessary we should make it independent of the authentication mechanism: an extra parameter to add to existing WWW-Auth schemes; a special string to include in the realm values of existing WWW-Auth schemes; a separate HTTP response header identifying which WWW-Auth headers are meant for "delegation credentials"…

> Yes it is. The idea of requiring servers to make this distinction is impractical. Basic auth is well defined and any attempt to overload it with new meaning is wrong.

Could you explain what is impractical?
If a server really cannot distinguish tokens it chooses from usernames it can use separate URIs for the two groups.
I don't think treating an OAuth token as a username, or a shared secret as a password is a "new meaning".

James Manger

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Sat, 3 Oct 2009 10:55:07 -0700

> Sent: Saturday, October 03, 2009 10:13 AM

> I think some of the disconnect between our ideas revolves around what a

Only in the sense that while technically correct, your proposal breaks existing expectations and browser behavior. Just the fact that servers will need to worry about the order of their authorization header in order to support both usernames and tokens on the same resource is to me a non-starter.

My point is only that the existing deployment of Basic prevents it from being used in the way you proposed because it is more likely to break things and does not offer any real benefit (other than a theoretical cleaner architecture), and less work for the spec editor.

> If we need BASIC for usernames and TOKEN PLAIN for delegation tokens,
> wont we also need something else for direct access by clients. Mightn't
> we need a different scheme for tokens issued by the OAuth web-
> delegation flow vs token issued via some other mechanism?

I agree that the scheme name (Token) isn't accurate and happy for other suggestions (such as 'Delegate', etc.). To me token implies some other credential in place of a username but I agree that this is not the common use of the word.

Direct access by clients does work well with existing username-based schemes because that's what it is - direct access. We have two distinct cases: direct access and delegated access. The issue is to have both direct access and delegated access coexist on the same resource.

> >> 2. A WWW-Auth scheme indicating that a web delegation flow can be
> used
> >> to get user authorization.
> 
> > I am not sure this is the right way to provide delegation discovery
> (via the auth header). Using Link: headers is much more appropriate.
> 
> A Link header might work. 1 or 2 extra round-trips could be avoid with
> a WWW-Auth scheme compared to a Link relation, as a WWW-Auth scheme
> could be more descriptive (more scheme-specific parameters) that seems
> sensible to cram into a Link relation.

I disagree that an auth scheme is more appropriate than Link. Link can be as easily extended. I do not consider providing discovery information about where credentials can be obtained as a valid 401 challenge. This is exactly what Link is for.
 
> Indeed, I wasn't suggesting any change here (other than "MAC" as a

I think the scheme name should reflect its specific delegation-related role, so MAC would be good generic as well.
 
> >> I think there is value in creating a family of authentication
> methods using a scheme and sub-scheme. It is better to support
> extensibility in the scheme than to force new methods to define new
> schemes. This will allow easier implementation of new sub-schemes.
> 
> So you want the "TOKEN" scheme to mean "delegation credentials", and
> the sub-scheme to be the authentication mechanism.
> I don’t think a special indicator for "delegation credentials" is
> necessary (use case?). If an indicator is necessary we should make it
> independent of the authentication mechanism: an extra parameter to add
> to existing WWW-Auth schemes; a special string to include in the realm
> values of existing WWW-Auth schemes; a separate HTTP response header
> identifying which WWW-Auth headers are meant for "delegation
> credentials"…

This is needed to work with existing deployments, and while I really like the idea of adding a parameter to existing schemes, it will not help with existing code which will simply ignore it and break.

> >> A server may need to ensure usernames and tokens can be
> distinguished,
> >> but that is easy enough.
> 
> > Yes it is. The idea of requiring servers to make this distinction is
> impractical. Basic auth is well defined and any attempt to overload it
> with new meaning is wrong.
> 
> If a server really cannot distinguish tokens it chooses from usernames
> it can use separate URIs for the two groups.

It means changing existing username platforms (many with strong backend integration with a login system) to first check for a pattern. It puts limitations on token design because of existing usernames. But the main issue is that it is very likely to break existing clients.

I don't think you have demonstrated the value of your proposal other than making the spec shorter. The deployment requirement you are proposing (order of auth headers, structure of tokens, duplication of resource URI based on access type) while possible, take away any value in reuse and are generally unacceptable to me.

EHL

---

From: "Manger, James H" <[email-masked]>
Date: Sun, 4 Oct 2009 14:13:13 +1100

> My point is only that the existing deployment of Basic
> prevents it from being used in the way you proposed because
> it is more likely to break things and does not offer any real benefit
> (other than a theoretical cleaner architecture),
> and less work for the spec editor.

One very real benefit is that established authentication schemes, such as BASIC, are already supported by frameworks/libraries/systems/infrastructure/plumbing. I think Eran stated that one aim of the current OAuth work was to get OAuth supported in those contexts, not just as app-layer libraries.

Consider a networking library (eg java.net.URLConnection) that adds support for TOKEN XXX WWW-Auth schemes (in addition to existing support for BASIC etc). The library has no way of knowing if a caller is making a request in a "direct" or a "delegated" context so it has no way of knowing if it should react to BASIC or TOKEN XXX. All it can do is ask the caller (eg via a caller-supplied java.net.Authenticator), "Have you got a username/password for this address/port/protocol/realm/scheme"?

If both a BASIC and a TOKEN PLAIN WWW-Auth header are present in a 401 response, java.net.URLConnection will ask java.net.Authenticator about both in turn (probably in the order they appear) until it gets some credentials. The process is the same if two BASIC headers are present -- it asks about both until it gets an answer. If BASIC and MAC (TOKEN HMAC) headers are present it might ask about the MAC header first as it is the stronger algorithm.  [P.S. I assume this is how Java works, but I haven't confirmed all the details yet]

> Direct access by clients does work well with existing username-based schemes
> because that's what it is - direct access.
> We have two distinct cases: direct access and delegated access.
> The issue is to have both direct access and delegated access coexist on the same resource.

I don't think this divide works.
People have made lots of use of the OAuth 1.0 request signing mechanism for delegated access and for "2-legged" direct access.
If TOKEN HMAC is not usable for "2-legged" direct access then it misses half the proven use cases.
Is removing support for "2-legged" request signing intentional?

James Manger

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Sat, 3 Oct 2009 22:46:17 -0700

*** It would be helpful if other people chime in on this topic. This is a critical decision we need to make regarding new schemes. One proposal is to have different scheme for different type of access (direct vs. delegated). Another is to reusing existing scheme (with a new MAC-based one) for both usernames and tokens, and differentiating them on the server side using the credential structure (token or username) and on the client side using the realm parameter (and the header order). Of course, there are probably other proposals coming. ***

> Sent: Saturday, October 03, 2009 8:13 PM
> To: [email-masked]
> One very real benefit is that established authentication schemes, such
> as BASIC, are already supported by
> frameworks/libraries/systems/infrastructure/plumbing. I think Eran
> stated that one aim of the current OAuth work was to get OAuth
> supported in those contexts, not just as app-layer libraries.

(not sure why you are talking past me...)

The existing support for Basic is not going to make a big difference because the goal is to get the new authentication scheme (the one that works without SSL) deployed. Are you suggesting that reusing Basic is the way to get transport-layer support? That doesn't get us much.

> Consider a networking library (eg java.net.URLConnection) that adds
> support for TOKEN XXX WWW-Auth schemes (in addition to existing support
> for BASIC etc). The library has no way of knowing if a caller is making
> a request in a "direct" or a "delegated" context so it has no way of
> knowing if it should react to BASIC or TOKEN XXX. All it can do is ask
> the caller (eg via a caller-supplied java.net.Authenticator), "Have you
> got a username/password for this address/port/protocol/realm/scheme"?
> 
> If both a BASIC and a TOKEN PLAIN WWW-Auth header are present in a 401
> response, java.net.URLConnection will ask java.net.Authenticator about
> both in turn (probably in the order they appear) until it gets some
> credentials. The process is the same if two BASIC headers are present -
> - it asks about both until it gets an answer. If BASIC and MAC (TOKEN
> HMAC) headers are present it might ask about the MAC header first as it
> is the stronger algorithm.  [P.S. I assume this is how Java works, but
> I haven't confirmed all the details yet]

The problem with this flow is that it doesn't account for a new, non-username based authentication method. The only way this can work with your proposal is by using the realm as the only differentiator between usernames and tokens. I think this is an abuse of the realm parameter and given all the other problems we have with defining realm, is just asking for problems.
 
> People have made lots of use of the OAuth 1.0 request signing mechanism
> for delegated access and for "2-legged" direct access.

Removing support for "2-legged" was intentional in my proposal only in the sense that it is something we should figure out separately. Our charter allows us to define a new authentication method for HTTP that is useful beyond the delegation use case. However, the current way people are using OAuth 1.0 for direct access is mixed. Some use the client credentials as username/password, omitting the token. Others give clients special tokens to use with API calls that do not have a user context.

There are many ways to take whatever new auth scheme we come up with and enable it for the non-delegated use case. But given this is a secondary goal, I would like to first come up with the best authentication scheme we can for delegation and then review it for the 2-legged use cases. Either way, there is no requirement for us to define a single auth scheme. We can define two schemes with identical syntax but different names, one for delegation and another for usernames (just one of many ways to address this).

BTW, OAuth is being used in many unexpected ways all of which are of little interest to us. We are not trying to maintain every possible use case someone found for 1.0.

EHL

---

From: Brian Eaton <[email-masked]>
Date: Sun, 4 Oct 2009 12:52:42 -0700

On Sat, Oct 3, 2009 at 8:13 PM, Manger, James H
<[email-masked]> wrote:
> One very real benefit is that established authentication schemes, such as BASIC
>  are already supported by frameworks/libraries/systems/infrastructure/plumbing.
> I think Eran stated that one aim of the current OAuth work was to get OAuth
> Consider a networking library (eg java.net.URLConnection) that adds support for
> TOKEN XXX WWW-Auth schemes (in addition to existing support for BASIC etc). The
> library has no way of knowing if a caller is making a request in a "direct" or a
> "delegated" context so it has no way of knowing if it should react to BASIC or TOKEN XXX.
> All it can do is ask the caller (eg via a caller-supplied java.net.Authenticator),
> "Have you got a username/password for this address/port/protocol/realm/scheme"?

Almost nobody writes code that actually works this way today.  In
general applications know exactly what kind of authentication they are
going to provide for a particular resource, and add it in a priori.

Automatically figuring out that a particular resource requires a
particular credential from a particular authority is tantamount to
magic.  I don't think we should guide the spec based on the assumption
that someone is going to figure out how to do it.  I'd prefer to
assume that OAuth authentication starts after application code has
figured out it is necessary and provided the necessary bootstrapping.

Cheers,
Brian

---

From: Brian Eaton <[email-masked]>
Date: Sun, 4 Oct 2009 13:24:51 -0700

On Sat, Oct 3, 2009 at 10:46 PM, Eran Hammer-Lahav <[email-masked]> wrote:
> *** It would be helpful if other people chime in on this topic. This is a
> critical decision we need to make regarding new schemes. One proposal
> is to have different scheme for different type of access (direct vs. delegated).
> Another is to reusing existing scheme (with a new MAC-based one) for both
> usernames and tokens, and differentiating them on the server side using the
> credential structure (token or username) and on the client side using the
> realm parameter (and the header order). Of course, there are probably other
> proposals coming. ***

Here's how I'd divvy up the work.

1) Come up with some core set of mechanisms for authenticating a
single data request.

2) Make sure that those mechanisms are extensible, so that we can add
new cryptographic tools as necessary later.

3) Define protocol flows for combining them to cover things like
two-legged OAuth to authenticate calling applications, three-legged
OAuth, OAuth with assertions about both the identity of the calling
application and the user, etc...

For example, two-legged OAuth might look like this:

- send consumer key and secret to token issuing endpoint
- get back session token
- send session token to data endpoint
- session token expires periodically, needs to be renewed

Three-legged OAuth might look like this:

- send consumer key, consumer secret, and access token to token issuing endpoint
- get back session token
- send session token to data endpoint
- session token expires periodically, needs to be renewed

When someone invents something New and Complicated, the complexity
would get pushed to the token issuing endpoint like so:

- send New and Complicated stuff to token issuing endpoint
- get back session token
- send session token to data endpoint
- session token expires periodically, needs to be renewed

Cheers,
Brian

---

From: Brian Eaton <[email-masked]>
Date: Mon, 5 Oct 2009 11:48:55 -0700

> realm parameter (and the header order). Of course, there are probably other

Eran points out that I've posted several times to this thread without
actually answering the question he asked.  =)

I don't think we should use basic auth to send tokens.  I'd rather see
us use a new auth scheme.

- basic auth has existing semantics for "realm".  They aren't the same
semantics we need for OAuth.
- using the basic auth scheme would cripple our ability to add new
signature methods.

It is in theory possible to treat a token as a username and a token
secret as a password, but I don't think it would be a particularly
useful thing to do.  If we want to use bearer tokens, we should just
drop the token secret altogether.

Cheers,
Brian

---

From: John Panzer <[email-masked]>
Date: Tue, 6 Oct 2009 14:20:49 -0700

I agree with beaton, but I have another argument against Basic auth.
Unmodified client code and UIs will assume we're talking about regular
username and password and use that terminology (and a separate realm would
just confuse things).  If they're modified to be OAuth aware this could be
fixed, but if you assume OAuth aware code you can use a new auth scheme just
as easily.  And, it would be less confusing.

--
John Panzer / Google
[email-masked] / abstractioneer.org <http://www.abstractioneer.org/> /
@jpanzer

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 6 Oct 2009 14:36:45 -0700

How do people feel about defining two (syntactically identical) schemes: Delegated and Direct.

Both will use the same method(s) of making authenticated requests but Direct will mean use a username and password while Delegated will mean use a token obtained from a delegation endpoint.

Of course the other obvious option is to define a single scheme Token and add a parameter but that is ugly.

EHL

From: John Panzer [mailto:[email-masked]]
Sent: Tuesday, October 06, 2009 2:21 PM
To: Brian Eaton
Cc: Eran Hammer-Lahav; [email-masked]
Subject: Re: [OAUTH-WG] Proposal for a New 2617 Scheme: Token

I agree with beaton, but I have another argument against Basic auth.  Unmodified client code and UIs will assume we're talking about regular username and password and use that terminology (and a separate realm would just confuse things).  If they're modified to be OAuth aware this could be fixed, but if you assume OAuth aware code you can use a new auth scheme just as easily.  And, it would be less confusing.

--
John Panzer / Google
[email-masked]<mailto:[email-masked]> / abstractioneer.org<http://www.abstractioneer.org/> / @jpanzer

On Mon, Oct 5, 2009 at 11:48 AM, Brian Eaton <[email-masked]<mailto:[email-masked]>> wrote:

Cheers,
Brian

---

From: John Kemp <[email-masked]>
Date: Tue, 6 Oct 2009 21:15:26 -0400

On Oct 6, 2009, at 5:36 PM, Eran Hammer-Lahav wrote:

> How do people feel about defining two (syntactically identical)

What do you mean "syntactically identical"?

> schemes: Delegated and Direct.

I like this idea.

>
> Both will use the same method(s) of making authenticated requests

As in the same set of signing mechanisms can be used in either case?

> but Direct will mean use a username and password while Delegated  
> will mean use a token obtained from a delegation endpoint.

This sounds good to me.

- johnk

>
> Of course the other obvious option is to define a single scheme  
> Token and add a parameter but that is ugly.
>
> EHL
>
> I agree with beaton, but I have another argument against Basic  
> auth.  Unmodified client code and UIs will assume we're talking  
> about regular username and password and use that terminology (and a  
> separate realm would just confuse things).  If they're modified to  
> be OAuth aware this could be fixed, but if you assume OAuth aware  
> code you can use a new auth scheme just as easily.  And, it would be  
> less confusing.
>
> --
> John Panzer / Google
> [email-masked] / abstractioneer.org / @jpanzer
>
>
>
> On Sat, Oct 3, 2009 at 10:46 PM, Eran Hammer-Lahav <[email-masked] 
> > wrote:

---

From: Eran Hammer-Lahav <[email-masked]>
Date: Tue, 6 Oct 2009 18:20:20 -0700

> From: John Kemp [mailto:[email-masked]]
> Sent: Tuesday, October 06, 2009 6:15 PM

> What do you mean "syntactically identical"?

Everything the same (signature flow, parameters, etc.) but use username in one and token for another where credentials are expected (same with secret and password).
 
> As in the same set of signing mechanisms can be used in either case?

Yes.

EHL

---

From: "Manger, James H" <[email-masked]>
Date: Wed, 7 Oct 2009 13:33:54 +1100

I still feel that having two parallel groups of authentication mechanisms — one group for “direct” credentials, one group for “delegated” credential — is a very poor architectural choice.

If it is required, I suggest the schemes for delegated credentials should add “Delegate-“ to the direct scheme name and otherwise be identical. So a request signing spec would specify, say, a direct “MAC” scheme. Another spec would define the “Delegate-“ prefix that can apply to any scheme. Then we could use:

  Authorization: BASIC adghashjdgasdj   — for users with browsers

  Authorization: Delegate-BASIC adghashjdgasdj  — for clients with delegation token/secrets over HTTPS

  Authorization: Delegate-MAC …signature=”dfjghfa”  — for clients with delegation token/secrets over HTTP

  Authorization: MAC …signature=”dfjghfa”  — for clients with app credentials (eg 2-legged) over HTTP

  Authorization: Delegate-Id <token>  — for clients acting as a delegate over a separately-authenticated channel (HTTPS with client & server auth; VPN…)

> Both will use the same method(s)

Does this means the “Delegated” and “Direct” schemes are supposed to include PLAIN and HMAC (and RSA?) methods (eg “Delegated PLAIN” (like the “TOKEN PLAIN” idea)? If so, yuck! Burying the actual mechanism (PLAIN/HMAC/…) a layer down will not work well with existing libraries where one part chooses a mechanism based solely on the scheme.

I also don’t think it matches the allowed syntax for the WWW-Authenticate header: everything after the scheme has to be in name=value syntax. [RFC 2617, §1.2]

challenge   = auth-scheme 1*SP 1#auth-param

auth-scheme = token
auth-param  = token "=" ( token | quoted-string )

[Aside: regardless of prefix, stick with “BASIC base64(utf8(token) ‘:’ utf8(secret))” syntax instead of “Plain <token> <secret>”. The only restriction the former imposes is that a token cannot include a colon. The latter implies all sort of restrictions on token and secret: only ASCII, no commas, no newlines, no space, quotes (nor sure), other punctuation (not sure). It is far from clear what exactly the restrictions are as I believe the HTTP header parsing rules are quite messy — avoid this issue (and the whole debate) by sticking with the BASIC syntax.]

I did a few tests to see how Java (Sun’s v6) handled multiple WWW-Auth headers in a response. I had hoped it would pass each to the configured java.net.Authenticator until some non-null credentials were found. It does not do this. It picks one header based on a (configurable) prioritized list of schemes (by default Negotiate, Kerberos, Digest, NTLM, then BASIC). If a scheme appears multiple times it picks the last occurrence (in contrast to browsers that pick the first). I believe (Apache) HttpClient does a similar thing: new authentication mechanisms can be added, but only the scheme is consulted when choosing them.

This means returning multiple “WWW-Auth.: BASIC …” headers with different realms (one for users, one for apps with delegation tokens) would be more awkward than I hoped. I will not pursue that idea.

It also means “Token <sub-scheme>”, “Delegated <sub-scheme>” or “Direct <sub-scheme>” will not work well with existing code bases. Existing Java HTTP internals could pick the last “Delegated ” header, but could not be configured to pick, say, HMAC over PLAIN, or RSA over HMAC.

Perhaps we need some clarification over the problem the Delegated/Direct/Token idea is addressing. Eran’s original statement was:

> “It is important to make sure a server can reply to a protected resource request with more than one auth header to indicate that both usernames and tokens are welcomed.”

Eran, are you most concerned about allowing users with browsers and apps with delegated credentials to access the same URIs? Or is it apps with their own (direct) credentials and with delegated credentials needing to choose between these?

Supporting either (or both) would be nice, but I am not yet convinced that this problem is that critical (ie worth a architectural compromise).

Few sites use BASIC for users — it just doesn’t offer enough flexibility in the user interface (forgotten password links etc).

Few sites use the same URIs for users and apps — many seem to have a www.example.net<http://www.example.net> and api.example.net split, for instance. Users typically want HTML; apps typically want JSON or XML….

The extremely common FORM-based user auth does not play well with any WWW-Auth header as it is never(?) delivered with a 401 error code.

Finally, we have concentrated on WWW-Auth-based discovery for the authentication part, ignoring the delegation flow part for now. It seems quite reasonable/sensible/likely/possible that the delegation flow should indicate which protected resources the delegation can be used at. In which case, the delegation credentials can be sent proactively when requesting those resources, without any need for a WWW-Auth header (making the Delegate-specific WWW-Auth schemes unnecessary).

James Manger
[email-masked]<mailto:[email-masked]>
Identity and security team — Chief Technology Office — Telstra

---

From: "Manger, James H" <[email-masked]>
Date: Wed, 7 Oct 2009 14:44:38 +1100

Brian,

> - basic auth has existing semantics for "realm".
>   They aren't the same semantics we need for OAuth."

Could you explain this a bit more? What semantics does OAuth need?
BASIC only assumes a realm is unambiguous in the context of one site. That is probably more limited than many OAuth providers want. However, I can't see any problems with a delegation flow expanding that: eg saying "treat *.example.net and api.example.com as a single context for realm values".

> - using the basic auth scheme would cripple our ability to add new

I don't understand this one.
How does it preclude defining a separate MAC scheme or RSA scheme?

> If we want to use bearer tokens, we should just drop the token secret altogether.

I think I agree here. It would be helpful to support bearer tokens as one OAuth option (making the secret optional in the delegation flow and defining a "Authorization: Id <token>" scheme specifically for this case).

James