Update OAuth spec to add support for authorization code

[dmcgowan]

Summary

Add support for the authorization_code grant type as specified in the OAuth2 spec at https://tools.ietf.org/html/rfc6749#section-4.1. Additional changes involve communicating the necessary OAuth2 parameters to the client so that it can direct the user to the oauth provider's URL for authorization.

Changes

• Add support for authorization_code grant type
• Add WWW-Authenticate challenge response to token endpoint
• Specify HEAD request to token endpoint to get challenge
• Clarify use of GET as a compatibility only endpoint
• Diagrams added to clarify entire flows in each scenario

Work in Progress

This PR has been submitted before completion to get initial feedback on design. While this does add more support for the OAuth2 spec, additional clarification may be needed to specify what is specific to the token server and what differences exist here between more common OAuth2 implementations. Additionally this is specifying a non-standard use of the WWW-Authenticate header which may prove more confusing than necessary.

[codecov-io]

Current coverage is 54.75%

Merging #1708 into master will decrease coverage by -12.83%

1. 2 files (not in diff) in ...ge/driver/middleware were modified. more
   • Partials +4
   • Hits -4
2. 2 files (not in diff) in ...rage/driver/inmemory were modified. more
   • Partials +23
   • Hits -23
3. 6 files (not in diff) in ...istry/storage/driver were modified. more
   • Misses +807
   • Partials +68
   • Hits -903
4. 13 files (not in diff) in registry/storage were modified. more
   • Partials +54
   • Hits -54
5. 6 files (not in diff) in registry/proxy were modified. more
   • Partials +41
   • Hits -41
6. 9 files (not in diff) in registry/handlers were modified. more
   • Partials +116
   • Hits -116
7. 2 files (not in diff) in ...try/client/transport were modified. more
   • Misses +6
   • Partials +10
   • Hits -16
8. 3 files (not in diff) in registry/client/auth were modified. more
   • Partials +23
   • Hits -23
9. 3 files (not in diff) in registry/client were modified. more
   • Partials +70
   • Hits -70
10. 2 files (not in diff) in registry/auth/token were modified. more
    • Partials +33
    • Hits -33

@@             master      #1708   diff @@
==========================================
  Files           121        120      -1   
  Lines         10578      10493     -85   
  Methods           0          0           
  Messages          0          0           
  Branches          0          0           
==========================================
- Hits           7149       5745   -1404   
- Misses         3429       4240    +811   
- Partials          0        508    +508   

Powered by Codecov. Last updated by 4ecea4b...f3adb12

[marcellodesales]

@dmcgowan do you have an ETA for when this feature will be GA?

[dmcgowan]

@marcellodesales the difficult part is going to be getting web login support within the docker client. I have everything else prototyped and working based on this specification. This specification will likely not get merged until it is supported within Docker which would be 1.13 at the soonest.

[stevvooe]

Might need a few examples of valid scopes for this use case.

[aurelijusbanelis]

According to https://tools.ietf.org/html/rfc6749#section-3.3 and http://stackoverflow.com/questions/8449544/multiple-scope-values-to-oauth2, this should work:

scope=repository:org1/repo1:pull repository:org1/repo2:pull

But with current registry Docker-Distribution-Api-Version: registry/2.0 it does not 😞

{"errors":[{"code":"UNAUTHORIZED","message":"authentication required","detail":[{"Type":"repository","Class":"","Name":"org1/repo1","Action":"pull"}]}]}

So, I need to call auth.docker.io for every repository 😞 Wildcard is also not supported (#1308)

P.S. org1,repo1, repo1 are example names for private repositories

[dmcgowan]

@aurelijusbanelis no auth.docker.io does not support this today. We would push to get that supported if we accept this proposal.

So, I need to call auth.docker.io for every repository

On auth.docker.io you can actually specify the "scope" parameter multiple times to get scopes for multiple repositories. This change is trying to update it to support allow multiple in the same scope value to align with the spec, but still possible today in a non-spec compliant way.

[stevvooe]

Let's make it clear that this should work on any endpoint and not just /v2/.

[marcellodesales]

@stevvooe @dmcgowan How is this looking for 1.13? Is it scheduled?

[dmcgowan]

This is not included in 1.13 (registry 2.6), let me tentatively add it to the 2.7 milestone

[marcellodesales]

@dmcgowan Is there an ETA for this one? We definitely would love to have this integration, as we use Github Enterprise for authentication.

[wking]

nit: "given from directly from" -> "provided by"? And you also want to keep the "server" part of "authorization server".

[TheJayMann]

Upon reviewing the updates, I notice that the spec refers to getting the authorization information by sending a HEAD request to /token. I don't know if this is correct. The RFC spec linked above does not mention a HEAD (nor even a GET) being used with /token. Also, with two OAuth2 servers I have set up, one being ADFS, the other being a custom built OAuth2/OpenIDConnect identity provider, the former appears to immediately close the connection when using HEAD on the token url, the latter response with a 400 error. Testing with various data while performing a POST doesn't seem to respond with a 401, nor show any information concerning how to challenge.

That said, both identity providers have, in addition to a token endpoint, also an authorization endpoint. And, in my experience, when connecting them to a client, the client either needs to be supplied with both the token and authorization endpoint, or a metadata endpoint which contains this information.

[dmcgowan]

@TheJayMann the original proposal is kind of old. The part that was ended to be solved by the HEAD is the zero-knowledge problem we have from Docker clients today. There may be a better way to solve it now, but that was the originally proposal. Normally oauth is performed by clients who are configured to know they are talking to an oauth server, as such they would know the various URLs and IDs need to complete the process. The problem from Docker clients is the client may only start out knowing a host and not whether it is oauth2. This a basic discovery problem and there have been various suggestions for getting that to work, there is probably a better solution than using HEAD here.