GET /v2/registry/auth about openapi HOT 3 CLOSED

This is not currently documented explicitly. It is used for authentication by Docker clients.

https://docs.docker.com/registry/spec/auth/token/

from openapi.

If it's exposed publicly and works (as opposed to the metrics endpoint), I think we should add it to the spec. What do you think @andrewsomething?

from openapi.

Thinking about this some more, I don't think it is useful to include in the spec. It is only meant to be used by Docker clients as part of their JWT flow. While there might be some value in documenting it, I don't think we'd want to include it clients we create. You are much better off using an existing library for working with Docker registries.

When you run a command like docker pull registry.digitalocean.com/asb/static-example:06a447a, the Docker cli makes a request using basic auth to:

https://registry.digitalocean.com/v2/asb/static-example/manifests/06a447a

The basic auth is a DO API token as both the password and username base64, e.g. echo $DO_TOKEN:$DO_TOKEN | base64 -w 0. This request will return a 401 with a www-authenticate header, eg:

www-authenticate: Bearer realm="https://api.digitalocean.com/v2/registry/auth",service="registry.digitalocean.com",scope="repository:asb/static-example:pull"

Using the info from that response, you make a request to /v2/registry/auth. Again, using basic auth:

curl -X GET -H "Content-Type: application/json" \
    -H "Authorization: Basic $(echo $DO_TOKEN:$DO_TOKEN | base64 -w 0)" \
    "https://api.digitalocean.com/v2/registry/auth?service=registry.digitalocean.com&scope=repository:asb/doctl:pull"

This will return a token in the JSON body that can then be used repeat the initial request to registry.digitalocean.com, this time using the token for bearer auth.

So /v2/registry/auth shouldn't really be accessed unless it is first returned from the registry in the www-authenticate header. We are not necessarily making a promise to users that that path will always be used. It's dynamic.

from openapi.