1# `authn`
2
3[](https://godoc.org/github.com/google/go-containerregistry/pkg/authn)
4
5This README outlines how we acquire and use credentials when interacting with a registry.
6
7As much as possible, we attempt to emulate `docker`'s authentication behavior and configuration so that this library "just works" if you've already configured credentials that work with `docker`; however, when things don't work, a basic understanding of what's going on can help with debugging.
8
9The official documentation for how authentication with `docker` works is (reasonably) scattered across several different sites and GitHub repositories, so we've tried to summarize the relevant bits here.
10
11## tl;dr for consumers of this package
12
13By default, [`pkg/v1/remote`](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/remote) uses [`Anonymous`](https://godoc.org/github.com/google/go-containerregistry/pkg/authn#Anonymous) credentials (i.e. _none_), which for most registries will only allow read access to public images.
14
15To use the credentials found in your Docker config file, you can use the [`DefaultKeychain`](https://godoc.org/github.com/google/go-containerregistry/pkg/authn#DefaultKeychain), e.g.:
16
17```go
18package main
19
20import (
21 "fmt"
22
23 "github.com/google/go-containerregistry/pkg/authn"
24 "github.com/google/go-containerregistry/pkg/name"
25 "github.com/google/go-containerregistry/pkg/v1/remote"
26)
27
28func main() {
29 ref, err := name.ParseReference("registry.example.com/private/repo")
30 if err != nil {
31 panic(err)
32 }
33
34 // Fetch the manifest using default credentials.
35 img, err := remote.Get(ref, remote.WithAuthFromKeychain(authn.DefaultKeychain))
36 if err != nil {
37 panic(err)
38 }
39
40 // Prints the digest of registry.example.com/private/repo
41 fmt.Println(img.Digest)
42}
43```
44
45The `DefaultKeychain` will use credentials as described in your Docker config file -- usually `~/.docker/config.json`, or `%USERPROFILE%\.docker\config.json` on Windows -- or the location described by the `DOCKER_CONFIG` environment variable, if set.
46
47If those are not found, `DefaultKeychain` will look for credentials configured using [Podman's expectation](https://docs.podman.io/en/latest/markdown/podman-login.1.html) that these are found in `${XDG_RUNTIME_DIR}/containers/auth.json`.
48
49[See below](#docker-config-auth) for more information about what is configured in this file.
50
51## Emulating Cloud Provider Credential Helpers
52
53[`pkg/v1/google.Keychain`](https://pkg.go.dev/github.com/google/go-containerregistry/pkg/v1/google#Keychain) provides a `Keychain` implementation that emulates [`docker-credential-gcr`](https://github.com/GoogleCloudPlatform/docker-credential-gcr) to find credentials in the environment.
54See [`google.NewEnvAuthenticator`](https://pkg.go.dev/github.com/google/go-containerregistry/pkg/v1/google#NewEnvAuthenticator) and [`google.NewGcloudAuthenticator`](https://pkg.go.dev/github.com/google/go-containerregistry/pkg/v1/google#NewGcloudAuthenticator) for more information.
55
56To emulate other credential helpers without requiring them to be available as executables, [`NewKeychainFromHelper`](https://pkg.go.dev/github.com/google/go-containerregistry/pkg/authn#NewKeychainFromHelper) provides an adapter that takes a Go implementation satisfying a subset of the [`credentials.Helper`](https://pkg.go.dev/github.com/docker/docker-credential-helpers/credentials#Helper) interface, and makes it available as a `Keychain`.
57
58This means that you can emulate, for example, [Amazon ECR's `docker-credential-ecr-login` credential helper](https://github.com/awslabs/amazon-ecr-credential-helper) using the same implementation:
59
60```go
61import (
62 ecr "github.com/awslabs/amazon-ecr-credential-helper/ecr-login"
63 "github.com/awslabs/amazon-ecr-credential-helper/ecr-login/api"
64
65 "github.com/google/go-containerregistry/pkg/authn"
66 "github.com/google/go-containerregistry/pkg/v1/remote"
67)
68
69func main() {
70 // ...
71 ecrHelper := ecr.ECRHelper{ClientFactory: api.DefaultClientFactory{}}
72 img, err := remote.Get(ref, remote.WithAuthFromKeychain(authn.NewKeychainFromHelper(ecrHelper)))
73 if err != nil {
74 panic(err)
75 }
76 // ...
77}
78```
79
80Likewise, you can emulate [Azure's ACR `docker-credential-acr-env` credential helper](https://github.com/chrismellard/docker-credential-acr-env):
81
82```go
83import (
84 "github.com/chrismellard/docker-credential-acr-env/pkg/credhelper"
85
86 "github.com/google/go-containerregistry/pkg/authn"
87 "github.com/google/go-containerregistry/pkg/v1/remote"
88)
89
90func main() {
91 // ...
92 acrHelper := credhelper.NewACRCredentialsHelper()
93 img, err := remote.Get(ref, remote.WithAuthFromKeychain(authn.NewKeychainFromHelper(acrHelper)))
94 if err != nil {
95 panic(err)
96 }
97 // ...
98}
99```
100
101<!-- TODO(jasonhall): Wrap these in docker-credential-magic and reference those from here. -->
102
103## Using Multiple `Keychain`s
104
105[`NewMultiKeychain`](https://pkg.go.dev/github.com/google/go-containerregistry/pkg/authn#NewMultiKeychain) allows you to specify multiple `Keychain` implementations, which will be checked in order when credentials are needed.
106
107For example:
108
109```go
110kc := authn.NewMultiKeychain(
111 authn.DefaultKeychain,
112 google.Keychain,
113 authn.NewKeychainFromHelper(ecr.ECRHelper{ClientFactory: api.DefaultClientFactory{}}),
114 authn.NewKeychainFromHelper(acr.ACRCredHelper{}),
115)
116```
117
118This multi-keychain will:
119
120- first check for credentials found in the Docker config file, as describe above, then
121- check for GCP credentials available in the environment, as described above, then
122- check for ECR credentials by emulating the ECR credential helper, then
123- check for ACR credentials by emulating the ACR credential helper.
124
125If any keychain implementation is able to provide credentials for the request, they will be used, and further keychain implementations will not be consulted.
126
127If no implementations are able to provide credentials, `Anonymous` credentials will be used.
128
129## Docker Config Auth
130
131What follows attempts to gather useful information about Docker's config.json and make it available in one place.
132
133If you have questions, please [file an issue](https://github.com/google/go-containerregistry/issues/new).
134
135### Plaintext
136
137The config file is where your credentials are stored when you invoke `docker login`, e.g. the contents may look something like this:
138
139```json
140{
141 "auths": {
142 "registry.example.com": {
143 "auth": "QXp1cmVEaWFtb25kOmh1bnRlcjI="
144 }
145 }
146}
147```
148
149The `auths` map has an entry per registry, and the `auth` field contains your username and password encoded as [HTTP 'Basic' Auth](https://tools.ietf.org/html/rfc7617).
150
151**NOTE**: This means that your credentials are stored _in plaintext_:
152
153```bash
154$ echo "QXp1cmVEaWFtb25kOmh1bnRlcjI=" | base64 -d
155AzureDiamond:hunter2
156```
157
158For what it's worth, this config file is equivalent to:
159
160```json
161{
162 "auths": {
163 "registry.example.com": {
164 "username": "AzureDiamond",
165 "password": "hunter2"
166 }
167 }
168}
169```
170
171... which is useful to know if e.g. your CI system provides you a registry username and password via environment variables and you want to populate this file manually without invoking `docker login`.
172
173### Helpers
174
175If you log in like this, `docker` will warn you that you should use a [credential helper](https://docs.docker.com/engine/reference/commandline/login/#credentials-store), and you should!
176
177To configure a global credential helper:
178```json
179{
180 "credsStore": "osxkeychain"
181}
182```
183
184To configure a per-registry credential helper:
185```json
186{
187 "credHelpers": {
188 "gcr.io": "gcr"
189 }
190}
191```
192
193We use [`github.com/docker/cli/cli/config.Load`](https://godoc.org/github.com/docker/cli/cli/config#Load) to parse the config file and invoke any necessary credential helpers. This handles the logic of taking a [`ConfigFile`](https://github.com/docker/cli/blob/ba63a92655c0bea4857b8d6cc4991498858b3c60/cli/config/configfile/file.go#L25-L54) + registry domain and producing an [`AuthConfig`](https://github.com/docker/cli/blob/ba63a92655c0bea4857b8d6cc4991498858b3c60/cli/config/types/authconfig.go#L3-L22), which determines how we authenticate to the registry.
194
195## Credential Helpers
196
197The [credential helper protocol](https://github.com/docker/docker-credential-helpers) allows you to configure a binary that supplies credentials for the registry, rather than hard-coding them in the config file.
198
199The protocol has several verbs, but the one we most care about is `get`.
200
201For example, using the following config file:
202```json
203{
204 "credHelpers": {
205 "gcr.io": "gcr",
206 "eu.gcr.io": "gcr"
207 }
208}
209```
210
211To acquire credentials for `gcr.io`, we look in the `credHelpers` map to find
212the credential helper for `gcr.io` is `gcr`. By appending that value to
213`docker-credential-`, we can get the name of the binary we need to use.
214
215For this example, that's `docker-credential-gcr`, which must be on our `$PATH`.
216We'll then invoke that binary to get credentials:
217
218```bash
219$ echo "gcr.io" | docker-credential-gcr get
220{"Username":"_token","Secret":"<long access token>"}
221```
222
223You can configure the same credential helper for multiple registries, which is
224why we need to pass the domain in via STDIN, e.g. if we were trying to access
225`eu.gcr.io`, we'd do this instead:
226
227```bash
228$ echo "eu.gcr.io" | docker-credential-gcr get
229{"Username":"_token","Secret":"<long access token>"}
230```
231
232### Debugging credential helpers
233
234If a credential helper is configured but doesn't seem to be working, it can be
235challenging to debug. Implementing a fake credential helper lets you poke around
236to make it easier to see where the failure is happening.
237
238This "implements" a credential helper with hard-coded values:
239```
240#!/usr/bin/env bash
241echo '{"Username":"<token>","Secret":"hunter2"}'
242```
243
244
245This implements a credential helper that prints the output of
246`docker-credential-gcr` to both stderr and whatever called it, which allows you
247to snoop on another credential helper:
248```
249#!/usr/bin/env bash
250docker-credential-gcr $@ | tee >(cat 1>&2)
251```
252
253Put those files somewhere on your path, naming them e.g.
254`docker-credential-hardcoded` and `docker-credential-tee`, then modify the
255config file to use them:
256
257```json
258{
259 "credHelpers": {
260 "gcr.io": "tee",
261 "eu.gcr.io": "hardcoded"
262 }
263}
264```
265
266The `docker-credential-tee` trick works with both `crane` and `docker`:
267
268```bash
269$ crane manifest gcr.io/google-containers/pause > /dev/null
270{"ServerURL":"","Username":"_dcgcr_1_5_0_token","Secret":"<redacted>"}
271
272$ docker pull gcr.io/google-containers/pause
273Using default tag: latest
274{"ServerURL":"","Username":"_dcgcr_1_5_0_token","Secret":"<redacted>"}
275latest: Pulling from google-containers/pause
276a3ed95caeb02: Pull complete
2774964c72cd024: Pull complete
278Digest: sha256:a78c2d6208eff9b672de43f880093100050983047b7b0afe0217d3656e1b0d5f
279Status: Downloaded newer image for gcr.io/google-containers/pause:latest
280gcr.io/google-containers/pause:latest
281```
282
283## The Registry
284
285There are two methods for authenticating against a registry:
286[token](https://docs.docker.com/registry/spec/auth/token/) and
287[oauth2](https://docs.docker.com/registry/spec/auth/oauth/).
288
289Both methods are used to acquire an opaque `Bearer` token (or
290[RegistryToken](https://github.com/docker/cli/blob/ba63a92655c0bea4857b8d6cc4991498858b3c60/cli/config/types/authconfig.go#L21))
291to use in the `Authorization` header. The registry will return a `401
292Unauthorized` during the [version
293check](https://github.com/opencontainers/distribution-spec/blob/2c3975d1f03b67c9a0203199038adea0413f0573/spec.md#api-version-check)
294(or during normal operations) with
295[Www-Authenticate](https://tools.ietf.org/html/rfc7235#section-4.1) challenge
296indicating how to proceed.
297
298### Token
299
300If we get back an `AuthConfig` containing a [`Username/Password`](https://github.com/docker/cli/blob/ba63a92655c0bea4857b8d6cc4991498858b3c60/cli/config/types/authconfig.go#L5-L6)
301or
302[`Auth`](https://github.com/docker/cli/blob/ba63a92655c0bea4857b8d6cc4991498858b3c60/cli/config/types/authconfig.go#L7),
303we'll use the token method for authentication:
304
305
306
307### OAuth 2
308
309If we get back an `AuthConfig` containing an [`IdentityToken`](https://github.com/docker/cli/blob/ba63a92655c0bea4857b8d6cc4991498858b3c60/cli/config/types/authconfig.go#L18)
310we'll use the oauth2 method for authentication:
311
312
313
314This happens when a credential helper returns a response with the
315[`Username`](https://github.com/docker/docker-credential-helpers/blob/f78081d1f7fef6ad74ad6b79368de6348386e591/credentials/credentials.go#L16)
316set to `<token>` (no, that's not a placeholder, the literal string `"<token>"`).
317It is unclear why: [moby/moby#36926](https://github.com/moby/moby/issues/36926).
318
319We only support the oauth2 `grant_type` for `refresh_token` ([#629](https://github.com/google/go-containerregistry/issues/629)),
320since it's impossible to determine from the registry response whether we should
321use oauth, and the token method for authentication is widely implemented by
322registries.
View as plain text