Use `DOCKER_AUTH_CONFIG` env as credential store #6008

Benehiko · 2025-04-15T05:37:18Z

This patch enables the CLI to natively pick up the DOCKER_AUTH_CONFIG
environment variable and use it as a credential store.

The DOCKER_AUTH_CONFIG value should be a JSON object and must store
the credentials in a base64 encoded string under the auth key.

Credentials stored in DOCKER_AUTH_CONFIG would take precedence over any
credential stored in the file store (~/.docker/config.json) or native store
(credential helper).

Destructive actions, such as deleting a credential would result in a noop if
found in the environment credential. Credentials found in the file or
native store would get removed.

- What I did

- How I did it

- How to verify it

printf "username:pat" | openssl base64 -A

Setup the DOCKER_AUTH_CONFIG environment variable

DOCKER_AUTH_CONFIG='{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "aGk6KTpkY2tyX3BhdF9oZWxsbw=="
    }
  }
}'

docker buildx bake --set binary.platform=linux/arm64

docker run -it -v ./build/docker-linux-arm64:/bin/docker -v /var/run/docker.sock:/var/run/docker.sock --env DOCKER_AUTH_CONFIG alpine:latest /bin/ash

/ # docker login
...
Login Succeeded

- Human readable description for the release notes

Use `DOCKER_AUTH_CONFIG` as a credential store

- A picture of a cute animal (not mandatory but encouraged)

Copilot

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

codecov-commenter · 2025-04-15T05:38:47Z

Codecov Report

Attention: Patch coverage is 77.68595% with 27 lines in your changes missing coverage. Please review.

Project coverage is 55.13%. Comparing base (9e50654) to head (63c990c).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6008      +/-   ##
==========================================
+ Coverage   55.03%   55.13%   +0.09%     
==========================================
  Files         361      362       +1     
  Lines       30153    30271     +118     
==========================================
+ Hits        16596    16690      +94     
- Misses      12599    12620      +21     
- Partials      958      961       +3

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

cli/config/credentials/env_store.go

cli/config/credentials/env_store_test.go

cli/config/configfile/file.go

cli/config/memory/store.go

cli/config/memorystore/store.go

cli/config/configfile/file.go

cli/config/configfile/file_test.go

cli/config/memorystore/store.go

cli/config/memorystore/store_test.go

This patch enables the CLI to natively pick up the `DOCKER_AUTH_CONFIG` environment variable and use it as a credential store. The `DOCKER_AUTH_CONFIG` value should be a JSON object and must store the credentials in a base64 encoded string under the `auth` key. For example: `printf "username:pat" | openssl base64 -A` `export DOCKER_AUTH_CONFIG='{ "auths": { "https://index.docker.io/v1/": { "auth": "aGk6KTpkY2tyX3BhdF9oZWxsbw==" } } }'` Credentials stored in `DOCKER_AUTH_CONFIG` would take precedence over any credential stored in the file store (`~/.docker/config.json`) or native store (credential helper). Destructive actions, such as deleting a credential would result in a noop if found in the environment credential. Credentials found in the file or native store would get removed. Signed-off-by: Alano Terblanche <[email protected]>

thaJeztah · 2025-06-06T12:37:13Z

cli/config/configfile/file.go

@@ -46,6 +48,49 @@ type ConfigFile struct {
 	Experimental string `json:"experimental,omitempty"`
 }

+type configEnvAuth struct {
+	Auth string `json:"auth"`


We should probably keep the omitempty to match the "actual" types.AuthConfig;

cli/cli/config/types/authconfig.go

Line 7 in 9e50654

Auth string `json:"auth,omitempty"`

no, we can't here. This is enforced if the environment variable is set.

thaJeztah · 2025-06-06T12:50:21Z

cli/config/configfile/file.go

+	if c.AuthConfigs == nil {
+		c.AuthConfigs = make(map[string]configEnvAuth)
+	}
+	if err := json.NewDecoder(strings.NewReader(v)).Decode(c); err != nil && !errors.Is(err, io.EOF) {


Avoid using json.NewDecoder because it was designed to handle JSON streams (multiple records). We're doing that wrong in various places (some were probably intended as optimisation), but in this case we only expect a single JSON document, so better to not use;

https://go.dev/play/p/ehHfvnCkGDL

package main import ( "encoding/json" "errors" "fmt" "io" "strings" ) type Foo struct { Name string } func main() { const data = `{"Name":"foo"}{"Name":"bar"}{"Name":"baz"}` decoder := json.NewDecoder(strings.NewReader(data)) var p Foo for { err := decoder.Decode(&p) if err != nil { if errors.Is(err, io.EOF) { fmt.Println("end of stream") break } fmt.Println(err) return } fmt.Println(p) } err := json.Unmarshal([]byte(data), &p) if err != nil { fmt.Println(err) return } fmt.Println(p) }

copied it from the current implementation -

cli/cli/config/configfile/file.go

Lines 117 to 119 in 63c990c

if err := json.NewDecoder(configData).Decode(configFile); err != nil && !errors.Is(err, io.EOF) {

return err

}

thaJeztah · 2025-06-06T12:53:31Z

cli/config/configfile/file.go

+	authConfigs := make(map[string]types.AuthConfig)
+	for addr, envAuth := range c.AuthConfigs {
+		if envAuth.Auth == "" {
+			return authConfigs, fmt.Errorf("DOCKER_AUTH_CONFIG environment variable is missing auth for %s", addr)


Maybe we should just ignore these; when using credential-stores, these will always be an empty struct;

cat ~/.docker/config.json { "auths": { "https://index.docker.io/v1/": {}, "https://index.docker.io/v1/access-token": {}, "https://index.docker.io/v1/refresh-token": {} }, "credsStore": "desktop" }

I think it's fine to ignore those; while we probably don't expect mixed credentials-store vs "plain-text" entries, I guess technically this file is valid;

{ "auths": { "env.example.test": { "auth": "ZW52X3VzZXI6ZW52X3Bhc3M=" }, "https://index.docker.io/v1/": {}, "https://index.docker.io/v1/access-token": {}, "https://index.docker.io/v1/refresh-token": {} } }

i don't agree, this is a very explicit thing to set and would be up to the user to set it correctly. I think returning an error when the config isn't what we expect would be better.

thaJeztah · 2025-06-06T12:55:18Z

cli/config/configfile/file.go

+	v := os.Getenv("DOCKER_AUTH_CONFIG")
+	if v == "" {
+		return errDockerAuthConfigNotSet


Hm... so we're always returning an error unless the env-var is set.

Wondering if we should keep the logic to construct a memory store in the first place "conditional", and only try to use these options if it's either set, or set and non-empty

thaJeztah · 2025-06-06T12:58:40Z

cli/config/configfile/file.go

+		envConfig := &configEnv{}
+		err := envConfig.LoadFromEnv()
+		if err != nil {
+			// ignore if DOCKER_AUTH_CONFIG is not set
+			if errors.Is(err, errDockerAuthConfigNotSet) {
+				return nil
+			}
+			return err
+		}
+
+		authConfigs, err := envConfig.GetAuthConfigs()


This seems a bit convoluted; in the end, what we need is;

A string containing a (valid) JSON-encoded authconfig

That's decoded to a map[string]types.AuthConfig

i.e., this could look something like;

authConfigs, err := unmarshalAuthConfig(v) if err != nil { return err } return memorystore.WithAuthConfig(authConfigs)(c)

Let me try to draw this up quickly; will post later

thaJeztah · 2025-06-06T13:01:22Z

cli/config/configfile/file_test.go

+	"auths": {
+		"env.example.test": {
+			"auth": "ZW52X3VzZXI6ZW52X3Bhc3M="
+		}
+	}


See my other comment about "empty" values here; perhaps we should have that as a test-case to verify that behavior;

Suggested change

"auths": {

"env.example.test": {

"auth": "ZW52X3VzZXI6ZW52X3Bhc3M="

}

}

"auths": {

"env.example.test": {

"auth": "ZW52X3VzZXI6ZW52X3Bhc3M="

},

"https://index.docker.io/v1/": {},

"https://index.docker.io/v1/access-token": {},

"https://index.docker.io/v1/refresh-token": {}

}

thaJeztah · 2025-06-06T13:17:39Z

quick draw up; simplify unmarshaling, and other nits Benehiko/docker-cli#2

Benehiko requested a review from Copilot April 15, 2025 05:37

Copilot AI reviewed Apr 15, 2025

View reviewed changes

Benehiko added impact/changelog area/authentication labels Apr 15, 2025

Benehiko force-pushed the env-credentials-store branch 2 times, most recently from 866c70a to eb43744 Compare April 15, 2025 06:27

Benehiko requested review from thaJeztah and a team April 15, 2025 06:27

Benehiko marked this pull request as ready for review April 15, 2025 06:27

Benehiko mentioned this pull request Apr 15, 2025

run: flag to include the docker socket #5858

Merged

4 tasks

thaJeztah reviewed Apr 15, 2025

View reviewed changes

cli/config/credentials/env_store.go Outdated Show resolved Hide resolved

thaJeztah reviewed Apr 15, 2025

View reviewed changes

cli/config/credentials/env_store.go Outdated Show resolved Hide resolved

thaJeztah reviewed Apr 15, 2025

View reviewed changes

cli/config/credentials/env_store_test.go Outdated Show resolved Hide resolved

thaJeztah mentioned this pull request Apr 17, 2025

cli/command/container: --use-api-socket: support DOCKER_AUTH_CONFIG #6019

Merged

thaJeztah reviewed Apr 17, 2025

View reviewed changes

cli/config/configfile/file.go Outdated Show resolved Hide resolved

Benehiko force-pushed the env-credentials-store branch from e7c6f4d to b3aa07f Compare May 27, 2025 08:21

thaJeztah reviewed May 27, 2025

View reviewed changes

Benehiko force-pushed the env-credentials-store branch from de90f77 to b7770d7 Compare May 27, 2025 12:36

Benehiko requested a review from thaJeztah May 27, 2025 13:02

thaJeztah reviewed May 27, 2025

View reviewed changes

cli/config/memorystore/store.go Outdated Show resolved Hide resolved

Benehiko force-pushed the env-credentials-store branch 2 times, most recently from d801989 to 0417f99 Compare June 3, 2025 08:19

Benehiko requested a review from thaJeztah June 3, 2025 08:45

thaJeztah reviewed Jun 3, 2025

View reviewed changes

Benehiko force-pushed the env-credentials-store branch from 0417f99 to 5e95a08 Compare June 6, 2025 09:30

Benehiko force-pushed the env-credentials-store branch from 5e95a08 to 63c990c Compare June 6, 2025 11:15

Benehiko requested a review from thaJeztah June 6, 2025 11:35

thaJeztah reviewed Jun 6, 2025

View reviewed changes

thaJeztah mentioned this pull request Jun 6, 2025

simplify unmarshaling, and other nits Benehiko/docker-cli#2

Open

	if err := json.NewDecoder(configData).Decode(configFile); err != nil && !errors.Is(err, io.EOF) {
	return err
	}

Use DOCKER_AUTH_CONFIG env as credential store #6008

Are you sure you want to change the base?

Use DOCKER_AUTH_CONFIG env as credential store #6008

Uh oh!

Conversation

Benehiko commented Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

codecov-commenter commented Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Jun 6, 2025

Uh oh!

Uh oh!

Use `DOCKER_AUTH_CONFIG` env as credential store #6008

Use `DOCKER_AUTH_CONFIG` env as credential store #6008

Benehiko commented Apr 15, 2025 •

edited

Loading

codecov-commenter commented Apr 15, 2025 •

edited

Loading