Manual Docker Distribution Registry Authentication & Token Acquisition / Usage

._README.md

Docker DTR V2 Distribution Registry: Manual Authentication

In this #HOWTO, we'll use a set of user:password credentials to obtain an auth token from an enterprise Docker Trusted Registry DTR (archived page snapshot of docs.docker.com/ee/dtr).

Required information

• Registry hostname
• Account username and password

Use credentials to obtain an auth token

Endpoint: /20180419/docker/token

REGISTRY='registry-hostname.example.com'
USER='my.username'
PASSWORD='my.sekrit.password'

BASE_DOMAIN="$(echo "${REGISTRY}" | sed 's/^.*\.\([^\.]\{0,\}\.[^\.]\{0,\}$\)/\1/')"
BASE64_CREDS="$(echo -n "${USER}:${PASSWORD}" | base64)"

# Note: Without `echo -n' above, the newline ends up incorporated
#       into the base64 output and can lead to cases where
#       authentication succeeds and returns a token, but the
#       token never works.  Manifests as "anonymous access not
#       allowed" errors.

curl \
    -H "Host: ${REGISTRY}" \
    -H 'User-Agent: docker/17.09.0-ce go/go1.8.3 git-commit/afdb6d4 kernel/4.9.49-moby os/linux arch/amd64 UpstreamClient(Docker-Client/17.09.0-ce \(darwin\))' \
    -H "Authorization: Basic ${BASE64_CREDS}" \
    "https://${REGISTRY}/20180419/docker/token?account=${USER}&client_id=docker&offline_token=true&service=${BASE_DOMAIN}"

If everything is in order and authentication succeeded, the curl request to the token endpoint returns a response payload along the lines of:

{
    "token": "..t.o.k.e.n..c.o.n.t.e.n.t..",
    "scope": "",
    "expires_in": 3600
}

If jq is installed and you've set the requisite environment variables (see above), here is a copy-pastable command for obtaining an auth token and loading it into the $TOKEN environment variable:

TOKEN="$(curl \
    -H "Host: ${REGISTRY}" \
    -H 'User-Agent: docker/17.09.0-ce go/go1.8.3 git-commit/afdb6d4 kernel/4.9.49-moby os/linux arch/amd64 UpstreamClient(Docker-Client/17.09.0-ce \(darwin\))' \
    -H "Authorization: Basic ${BASE64_CREDS}" \
    "https://${REGISTRY}/20180419/docker/token?account=${USER}&client_id=docker&offline_token=true&service=${BASE_DOMAIN}" \
    | jq -r '.token'
)"

Use newly acquired token

The token will work for an hour, and so now it's time to execute some docker trusted registry / docker distribution API requests!

Examples

List all images

curl \
    -v \
    -H "Authorization: Bearer ${TOKEN}" \
    "https://${REGISTRY}/v2/_catalog"

Download a raw image layer as a file

IMAGE='mobpaas1/bots/bots-intent-server-dependencies'
LAYER='21983d0e36dfe8229924ac51a270520199af6a769aa1ec457800211f6544bd75'

curl \
    -v \
    -O \
    -H "Authorization: Bearer ${TOKEN}" \
    "https://${REGISTRY}/v2/${IMAGE}/blobs/sha256:${LAYER}"

Authenticating to a "regular" non-DTR docker distribution registry

Endpoint: /auth

REGISTRY='registry-hostname.example.com'
USER='my.username'
PASSWORD='my.sekrit.password'
SERVICE='Oracle+Registry'

BASE64_CREDS="$(echo "${USER}:${PASSWORD}" | base64)"

TOKEN="$(curl \
    -H "Authorization: Basic ${BASE64_CREDS}' \
    'https://${REGISTRY}/auth?account=${USER}&client_id=docker&offline_token=true&service=${SERVICE}'
)"

Appendix

Keywords / Phrases

• Docker get auth token private registry
• How do I authenticate with the V2 API?
• Docker V2 REST API
• Multi-tenant Docker Registry

Things that didn't pan out

Article: How do I authenticate with the v2 API - Only applies to hub.docker.com.