Subject: [OAUTH-WG] Authorization grant abstraction

From: "Manger, James H" <[email-masked]>
Date: Fri, 25 Mar 2011 18:12:43 +1100

OAuth2 now defines a single URI - the token endpoint - that has to be capable of processing:

*         State from a user approval interaction (encoded into a 'code' parameter);

*         User passwords;

*         Client app credentials;

*         SAML tokens;

*         JSON Web Tokens (JWT);

*         Whatever other mechanisms might emerge (perhaps Kerberos tokens).

A server might only support a subset of these modes - but it always has to support that subset from the same URI.

This is not a useful constraint.

A better approach would be to specify the format of a token response as a standalone item (eg with its own application/credential media type). Any mode get use its own URI, but link to the standardised OAuth2 processing by using the standard response format.

Alternatively, if OAuth2 insists servers supported all modes at a single token endpoint URI, it may as well take the minor extra step fixing that URI. Perhaps /.well-known/oauth2.

--(more details notes on this issue)

A service might start supporting user-delegation with some off-the-shelf software. If it later wants to support, say, JWTs using some other software it has to graft some de-multiplexing layers in front. If a service want to experiment with a new mode it needs to integrate it closely with its existing production parts.

Another consequence is the confusing "authorization grant" abstraction. The spec makes a valiant effort to describe an abstraction that covers an app orchestrating a user-to-server approval flow, plus an app swapping its secret for a temporary token, plus an app presenting say a SAML token, plus more.

Another consequence is the need for grant_types. Various hassles with these have come up in the last month - most seem minor, but they do add confusion and complexity none the less: what the labels should be (eg "code" vs "authorization_code"; "client_credentials" comments); whether there should be a registry; if http://oauth.net/grant_type URIs are stable or need some process control.

Mike Jones' recent draft "JSON Web Token (JWT) Bearer Profile for OAuth 2.0" [draft-jones-oauth-jwt-bearer] is illustrative. It defines how to swap a JSON Web Token for other credentials to access resources. It says to POST the JWT in a 'jwt' parameter, along with an optional 'scope', to the server. It also has to specify the grant type http://oauth.net/grant_type/jwt/1.0/bearer. Any implementation needs to be configured with a server's URI to POST the JWT to. It is hard to see how adding grant_type=http://oauth.net/grant_type/jwt/1.0/bearer to that URI is any simpler than the service just providing a JWT-specific URI (eg http://api.example.com/token/jwt).

Some services will be able to side-step the "one token endpoint" rule by acting as multiple authorization servers - simply document different token endpoints (eg use http://example.com/token/delegate, http://idp.example.com/oauth2, and http://example.com/token/jwt as the token endpoint for "normal", SAML, and JWT flows). In such a scenario grant_types look superfluous. However, a server doing this risks clashing with some future discovery protocol that assumes the "one token endpoint" rule.

About the only potential benefit from the single token endpoint is that a client app (using some future discovery protocol) only needs to discover one URI. But that is not realistic. A client app will also need to discover whether or not a particular mode is supported (and probably more details about that mode) so it may as well discover a mode-specific URI.

--

James Manger

---

From: Justin Richer <[email-masked]>
Date: Mon, 28 Mar 2011 12:51:27 -0400

I like the organization of the spec with its grant types structure. In
my reading of it, the two endpoints are logical and may be presented
from different URLs and crunched on by several processing engines in the
background. The important thing is the logical distinction between
"place where the client goes" and "place where the client sends an end
user", and that those don't get folded into each other. As you say
below, there's nothing stopping a provider from defining several
concrete endpoints to handle different configuration sets. 

I think that in practice we'll see people writing a dispatch point to
process their different supported configurations.  I don't think further
abstraction at the specification level will help things.

 -- Justin

On Fri, 2011-03-25 at 03:12 -0400, Manger, James H wrote:
> OAuth2 now defines a single URI – the token endpoint – that has to be
> capable of processing:
> 
> ·        State from a user approval interaction (encoded into a ‘code’
> parameter);
> 
> ·        User passwords;
> 
> ·        Client app credentials;
> 
> ·        SAML tokens;
> 
> ·        JSON Web Tokens (JWT);
> 
> ·        Whatever other mechanisms might emerge (perhaps Kerberos
> tokens).
> 
> A server might only support a subset of these modes – but it always
> has to support that subset from the same URI.
> 
>  
> 
> A better approach would be to specify the format of a token response
> as a standalone item (eg with its own application/credential media
> type). Any mode get use its own URI, but link to the standardised
> OAuth2 processing by using the standard response format.
> 
>  
> 
> Alternatively, if OAuth2 insists servers supported all modes at a
> single token endpoint URI, it may as well take the minor extra step
> fixing that URI. Perhaps /.well-known/oauth2.
> 
>  
> 
>  
> 
> A service might start supporting user-delegation with some
> off-the-shelf software. If it later wants to support, say, JWTs using
> some other software it has to graft some de-multiplexing layers in
> front. If a service want to experiment with a new mode it needs to
> integrate it closely with its existing production parts.
> 
>  
> 
> Another consequence is the confusing “authorization grant”
> abstraction. The spec makes a valiant effort to describe an
> abstraction that covers an app orchestrating a user-to-server approval
> flow, plus an app swapping its secret for a temporary token, plus an
> app presenting say a SAML token, plus more.
> 
>  
> 
> Another consequence is the need for grant_types. Various hassles with
> these have come up in the last month – most seem minor, but they do
> add confusion and complexity none the less: what the labels should be
> (eg “code” vs “authorization_code”; “client_credentials” comments);
> whether there should be a registry; if http://oauth.net/grant_type
> URIs are stable or need some process control.
> 
>  
> 
> Mike Jones’ recent draft “JSON Web Token (JWT) Bearer Profile for
> OAuth 2.0” [draft-jones-oauth-jwt-bearer] is illustrative. It defines
> how to swap a JSON Web Token for other credentials to access
> resources. It says to POST the JWT in a ‘jwt’ parameter, along with an
> optional ‘scope’, to the server. It also has to specify the grant type
> http://oauth.net/grant_type/jwt/1.0/bearer. Any implementation needs
> to be configured with a server’s URI to POST the JWT to. It is hard to
> see how adding grant_type=http://oauth.net/grant_type/jwt/1.0/bearer
> to that URI is any simpler than the service just providing a
> JWT-specific URI (eg http://api.example.com/token/jwt).
> 
>  
> 
> Some services will be able to side-step the “one token endpoint” rule
> by acting as multiple authorization servers – simply document
> different token endpoints (eg use http://example.com/token/delegate,
> http://idp.example.com/oauth2, and http://example.com/token/jwt as the
> token endpoint for “normal”, SAML, and JWT flows). In such a scenario
> grant_types look superfluous. However, a server doing this risks
> clashing with some future discovery protocol that assumes the “one
> token endpoint” rule.
> 
>  
> 
> About the only potential benefit from the single token endpoint is
> that a client app (using some future discovery protocol) only needs to
> discover one URI. But that is not realistic. A client app will also
> need to discover whether or not a particular mode is supported (and
> probably more details about that mode) so it may as well discover a
> mode-specific URI.
> 
>  
> 
> --
> 
> James Manger
> 
>  
> 
>

---

From: "Manger, James H" <[email-masked]>
Date: Tue, 29 Mar 2011 10:39:52 +1100

Justin,

> The important thing is the logical distinction between
> user", and that those don't get folded into each other.

I certainly don't want to fold those two together.
The issue is whether the spec should fold together all the reasons
different clients can call an authorization server into a single place.

> As you say below, there's nothing stopping a provider from defining
> several concrete endpoints to handle different configuration sets.

Yes & no.
If there is truly nothing stopping a server from using several
token endpoints then what is the point of the spec bother defining
just part of that endpoint: the grant_type parameter & its extensibility?
The only reason I can guess is so a future discovery spec can
assume there is a single "place where the client goes",
eg specify a Link relation that points to THE token endpoint
(which won't work with providers using several concrete endpoints).

> process their different supported configurations.

So people write extra code (the dispatch point) for what benefit?

> I don't think further abstraction at the specification level will help things.

I want less abstraction, not more. I am suggesting the spec can ditch
the artificial "grant_type" abstraction.

--
James Manger