Re: [OAUTH-WG] OAuth2 scheme

["Manger, James H" <[e-mail]>]

We should define a "WWW-Authenticate: OAuth2 ..." response header - not to encompass the MAC, Bearer, and any other generic HTTP authentication scheme, but as a way for a server to tell the client that it can perform an OAuth2 get-a-token flow to gain access. When the sort of OAuth2 flow depends on the error with a current token (eg expired vs invalid) then the "WWW-Authenticate: OAuth2 ..." response header needs to reflect this. It could do so be including an error code. A better, more direct, approach is to explicitly identify "refresh flow" and/or "user-delegation flow" and/or "assertion flow" etc.



Bearer or OAuth2 WWW-Authenticate response header?

The rule should be:

#1. If the client can fix an error by sending an "Authorization: Bearer ..." request header (or the query or POST alternative) then the server should return "WWW-Authenticate: Bearer ...".



#2. If the client can fix an error by performing an OAuth2 flow at an authorization server then the resource server should return "WWW-Authenticate: OAuth2 ...".



The server can return both response headers if both options are possible.



There is no point in re-presenting a rejected Bearer token so #1 isn't that useful. It could be appropriate if no token was presented as the client might have a token, but didn't know this resource needed it. It might be appropriate if a client presented a token with insufficient scope as the client might have another token with the right scope so "WWW-Authenticate: Bearer scope=..." could help. #1 is not really necessary when a presented token is invalid or expired as the client needs to get a new one (eg using an OAuth2 flow that is outside the scope of the Bearer scheme).



I don't think an error code in a "WWW-Authenticate: Bearer ..." response helps a client retry the request with a "Authorization: Bearer ..." header that will work.

An error code might help a client choose the right OAuth2 flow (eg refresh vs new user-delegation) so it might have a place in #2, a "WWW-Authenticate: OAuth2 ..." response header.



Eran said to Mike:

> Alternatively, if you have use cases or requirements for introducing just the WWW-Authenticate side of an OAuth2 authorization scheme (your open issue), which includes an 'error' attribute for use with the proposed registry, please present those and explain how it will work alongside the Bearer and MAC schemes (as currently drafted).



The "discovery" use-case in this email warrants the WWW-Authenticate side of an OAuth2 scheme.

An error attribute (plus a registry) might help, but we need the rest of the details of the response header first.

It works well alongside Bearer and MAC schemes: a "WWW-Auth.: OAuth2" response points to OAuth2 flows the client can try; a "WWW-Auth.: MAC/Bearer" response points to retrying a request with "Authz: MAC/Bearer". Even when a client is given multiple options it will know which to choose based on its context (eg if it doesn't have another Bearer token it will ignore the "WWW-Auth: Bearer" response and follow the "WWW-Auth: OAuth2" response).





--

James Manger