well-known-uri-ref-engine-discovery: Drop 'auth*' params from the Docker example #64

wking · 2018-01-26T06:00:32Z

Docker registries should include both of these in their WWW-Authenticate response, and Docker's registry does:

$ curl -I -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' https://index.docker.io/v2/library/docker/manifests/1.12.1
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Docker-Distribution-Api-Version: registry/2.0
Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:library/docker:pull"
Date: Fri, 26 Jan 2018 04:58:02 GMT
Content-Length: 157
Strict-Transport-Security: max-age=31536000

The WWW-Authenticate header is specified in RFC 7235, and the Bearer token is specified in RFC 6750. RFC 7235 defines realm and allows for per-scheme extensions:

The realm value is a string, generally assigned by the origin server, that can have additional semantics specific to the authentication scheme.

But RFC 6750 has nothing to say about its semantics, so interpreting it as the auth-server URI seems to be a Dockerism. Similarly, the service parameter seems to be a Dockerism, with no mentions of service in RFC 6750. scope is covered in RFC 6750, which delegates the definition to RFC 6749.

RFC 6749 covers supplying the scope to the auth-server as a query parameter. It also covers client_id, which Docker also mentions. RFC 6749 requires auth-requests to include response_type=code, which Docker does not mention; but Docker accepts the RFC value:

$ curl -s 'https://auth.docker.io/token?response_type=code&client_id=testing&service=registry.docker.io&scope=repository:library/docker:pull' | jq -S .
{
  "access_token": "…",
  "expires_in": 300,
  "issued_at": "2018-01-26T05:35:56.860615325Z",
  "token": "…"
}

Docker does not seem to implement RFC 6749's recommended state parameter.

With both “use realm as the auth server” and “pass through service as an auth query parameter” as Dockerisms, the RFCs are not sufficient in themselves to specify Docker's current auth protocol. These are not vanilla bearer tokens. But the information we previously supplied via authUri and authService is in the intial resource response, so we can stop supplying those ourselves.

…ker example Docker registries should include both of these in their WWW-Authenticate response [1], and Docker's registry does: $ curl -I -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' https://index.docker.io/v2/library/docker/manifests/1.12.1 HTTP/1.1 401 Unauthorized Content-Type: application/json; charset=utf-8 Docker-Distribution-Api-Version: registry/2.0 Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:library/docker:pull" Date: Fri, 26 Jan 2018 04:58:02 GMT Content-Length: 157 Strict-Transport-Security: max-age=31536000 The WWW-Authenticate header is specified in RFC 7235 [2], and the Bearer token is specified in RFC 6750 [3]. RFC 7235 defines realm and allows for per-scheme extensions [4]: The realm value is a string, generally assigned by the origin server, that can have additional semantics specific to the authentication scheme. But RFC 6750 has nothing to say about its semantics, so interpreting it as the auth-server URI seems to be a Dockerism. Similarly, the service parameter seems to be a Dockerism, with no mentions of 'service' in RFC 6750. 'scope' is covered in RFC 6750 [5], which delegates the definition to RFC 6749 [6]. RFC 6749 covers supplying the scope to the auth-server as a query parameter [7]. It also covers client_id, which Docker also mentions [8]. RFC 6749 requires auth-requests to include response_type=code [7], which Docker does not mention [8]; but Docker accepts the RFC value. $ curl -s 'https://auth.docker.io/token?response_type=code&client_id=testing&service=registry.docker.io&scope=repository:library/docker:pull' | jq -S . { "access_token": "...", "expires_in": 300, "issued_at": "2018-01-26T05:35:56.860615325Z", "token": "..." } Docker does not seem to implement RFC 6749's recommended 'state' parameter [7]. With both "use 'realm' as the auth server" and "pass through 'service' as an auth query parameter" as Dockerisms, the RFCs are not sufficient in themselves to specify Docker's current auth protocol. These are not vanilla bearer tokens. But the information we previously supplied via authUri and authService *is* in the intial resource response, so we can stop supplying those ourselves. [1]: https://github.com/docker/distribution/blob/v2.6.2/docs/spec/auth/token.md#how-to-authenticate [2]: https://tools.ietf.org/html/rfc7235#section-4.1 [3]: https://tools.ietf.org/html/rfc6750 [4]: https://tools.ietf.org/html/rfc7235#section-2.2 [5]: https://tools.ietf.org/html/rfc6750#section-3 [6]: https://tools.ietf.org/html/rfc6749#section-3.3 [7]: https://tools.ietf.org/html/rfc6749#section-4.1.1 [8]: https://github.com/docker/distribution/blob/v2.6.2/docs/spec/auth/token.md#requesting-a-token Signed-off-by: W. Trevor King <wking@tremily.us>

Docker's use of Bearer requires information beyond what's covered in RFC 6749 and 6750 [1]. So folks writing a client that will interact with a Docker registry that uses that auth approach will need a "Docker registry's 'Bearer' additions" spec to follow. While I prefer off-the-shelf RFCs for HTTP auth, the Docker registry additions are small enough, and widely used. This change adds the client side of their specification to the new distribution-spec project. The docker/distribution repository also includes docs for scope [3] and the JWT token semantics [4]. The scope docs are borderline useful for clients, but I've left them out because clients can extract the required scope from WWW-Authenticate in 401ed responses: $ curl -IH 'Accept: application/vnd.docker.distribution.manifest.v2+json' https://index.docker.io/v2/library/docker/manifests/1.12.1 HTTP/1.1 401 Unauthorized Content-Type: application/json; charset=utf-8 Docker-Distribution-Api-Version: registry/2.0 Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:library/docker:pull" ... Clients can consider them opaque, so I've left them out of the distribution-spec project for now. If distribution-spec maintainers feel that clients could benefit by explicitly crafting their own scope strings, they can pull in the scope specification after the project forms. JWT token semantics [4] are part of the interface between the auth server and the registry. Clients can consider them opaque, so I've left them out of the distribution-spec project. [1]: xiekeyang/oci-discovery#64 (comment) [2]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/oauth.md [3]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/scope.md [4]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/jwt.md Signed-off-by: W. Trevor King <wking@tremily.us>

Docker's use of Bearer requires information beyond what's covered in RFC 6749 and 6750 [1]. So folks writing a client that will interact with a Docker registry that uses that auth approach will need a "Docker registry's 'Bearer' additions" spec to follow. While I prefer off-the-shelf RFCs for HTTP auth, the Docker registry additions are small enough, and widely used. This change adds the client side of their specification to the new distribution-spec project. The docker/distribution repository also includes docs for scope [3] and the JWT token semantics [4]. The scope docs are borderline useful for clients, but I've left them out because clients can extract the required scope from WWW-Authenticate in 401ed responses: $ curl -IH 'Accept: application/vnd.docker.distribution.manifest.v2+json' https://index.docker.io/v2/library/docker/manifests/1.12.1 HTTP/1.1 401 Unauthorized Content-Type: application/json; charset=utf-8 Docker-Distribution-Api-Version: registry/2.0 Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:library/docker:pull" ... Clients can consider them opaque, so I've left them out of the distribution-spec project for now. If distribution-spec maintainers feel that clients could benefit by explicitly crafting their own scope strings, they can pull in the scope specification after the project forms. JWT token semantics [4] are part of the interface between the auth server and the registry. Clients can consider them opaque, so I've left them out of the distribution-spec project. Also pin the docker/registry links to a specific version so the links will survive future docker/registry changes (including removing the docs after the OCI picks them up). As long as the TOB-selected version isn't far behind (how far will the spec move during a week of voting?), it should be easy for the new maintainets to catch up on any subsequent drift. The signing scope language is from Stephen in [5]. The discovery scope language is from Derek [6]. [1]: xiekeyang/oci-discovery#64 (comment) [2]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/oauth.md [3]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/scope.md [4]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/jwt.md [5]: opencontainers#35 (comment) [6]: opencontainers#34 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

Docker's use of Bearer requires information beyond what's covered in RFC 6749 and 6750 [1]. Folks writing a client that will interact with a Docker registry that uses that auth approach will need a "Docker registry's 'Bearer' additions" spec to follow, but Derek believes the situation is salvageable with external work [2]. Also pin the docker/registry links to a specific version so the links will survive future docker/registry changes (including removing the docs after the OCI picks them up). As long as the TOB-selected version isn't far behind (how far will the spec move during a week of voting?), it should be easy for the new maintainets to catch up on any subsequent drift. The signing scope language is from Stephen in [3]. The discovery scope language is from Derek [4]. [1]: xiekeyang/oci-discovery#64 (comment) [2]: opencontainers#37 (comment) [3]: opencontainers#35 (comment) [4]: opencontainers#34 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

Docker's use of Bearer requires information beyond what's covered in RFC 6749 and 6750 [1]. Folks writing a client that will interact with a Docker registry that uses that auth approach will need a "Docker registry's 'Bearer' additions" spec to follow, but Derek believes the situation is salvageable with external work [2]. Also pin the docker/registry links to a specific version so the links will survive future docker/registry changes (including removing the docs after the OCI picks them up). As long as the TOB-selected version isn't far behind (how far will the spec move during a week of voting?), it should be easy for the new maintainets to catch up on any subsequent drift. The signing scope is from Stephen in [3]. The discovery scope is from Derek [4]. The content-management scope is from Stephen [5] and Liang [6]. [1]: xiekeyang/oci-discovery#64 (comment) [2]: opencontainers#37 (comment) [3]: opencontainers#35 (comment) [4]: opencontainers#34 (comment) [5]: opencontainers#35 (comment) [6]: opencontainers#37 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

Docker's use of Bearer requires information beyond what's covered in RFC 6749 and 6750 [1]. Folks writing a client that will interact with a Docker registry that uses that auth approach will need a "Docker registry's 'Bearer' additions" spec to follow, but Derek believes the situation is salvageable with external work [2]. Also pin the docker/registry links to a specific version so the links will survive future docker/registry changes (including removing the docs after the OCI picks them up). As long as the TOB-selected version isn't far behind (how far will the spec move during a week of voting?), it should be easy for the new maintainets to catch up on any subsequent drift. The signing scope is from Stephen in [3]. The discovery scope is from Derek [4]. The content-management scope is from Stephen [5] and Liang [6]. This commit also add's Mike's interoperability statement [7], which mentions one reason for the OCI inclusion is the implementation-agnostic location where implementers can collaborating on a common specification. The project scoping is open to drift with the limits imposed by the TOB's scope table. If the TOB thinks subsequent drift is excessive, they are free to make further scope-table adjustments in follow-up proposals. [1]: xiekeyang/oci-discovery#64 (comment) [2]: opencontainers#37 (comment) [3]: opencontainers#35 (comment) [4]: opencontainers#34 (comment) [5]: opencontainers#35 (comment) [6]: opencontainers#37 (comment) [7]: opencontainers#35 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

Docker's use of Bearer requires information beyond what's covered in RFC 6749 and 6750 [1]. Folks writing a client that will interact with a Docker registry that uses that auth approach will need a "Docker registry's 'Bearer' additions" spec to follow, but Derek believes the situation is salvageable with external work [2]. Also pin the docker/registry links to a specific version so the links will survive future docker/registry changes (including removing the docs after the OCI picks them up). As long as the TOB-selected version isn't far behind (how far will the spec move during a week of voting?), it should be easy for the new maintainets to catch up on any subsequent drift. The signing scope is from Stephen in [3]. The discovery scope is from Derek [4]. The content-management scope is from Stephen [5] and Liang [6]. This commit also add's Mike's interoperability statement [7], which mentions one reason for the OCI inclusion is the implementation-agnostic location where implementers can collaborating on a common specification. The project scoping is open to drift with the limits imposed by the TOB's scope table. If the TOB thinks subsequent drift is excessive, they are free to make further scope-table adjustments in follow-up proposals. I've also added Mike's library/busybox scoping example [8]. [1]: xiekeyang/oci-discovery#64 (comment) [2]: opencontainers#37 (comment) [3]: opencontainers#35 (comment) [4]: opencontainers#34 (comment) [5]: opencontainers#35 (comment) [6]: opencontainers#37 (comment) [7]: opencontainers#35 (comment) [8]: opencontainers#37 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

wking force-pushed the docker-auth-uri branch from 6a42b01 to 4312f71 Compare January 26, 2018 06:00

wking mentioned this pull request Jan 26, 2018

distribution: Add in-scope and out-of-scope wording opencontainers/tob#37

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

well-known-uri-ref-engine-discovery: Drop 'auth*' params from the Docker example #64

well-known-uri-ref-engine-discovery: Drop 'auth*' params from the Docker example #64

wking commented Jan 26, 2018

well-known-uri-ref-engine-discovery: Drop 'auth*' params from the Docker example #64

Are you sure you want to change the base?

well-known-uri-ref-engine-discovery: Drop 'auth*' params from the Docker example #64

Conversation

wking commented Jan 26, 2018