1containers-auth.json(5) File Formats Manual containers-auth.json(5)
2
6 containers-auth.json - syntax for the registry authentication file
7
11 A file in JSON format controlling authentication against container im‐
12 age registries. The primary (read/write) file is stored at ${XDG_RUN‐
13 TIME_DIR}/containers/auth.json on Linux; on Windows and macOS, at
14 $HOME/.config/containers/auth.json.
15 When searching for the credential for a registry, the following files
18 will be read in sequence until the valid credential is found: first
19 reading the primary (read/write) file, or the explicit override using
20 an option of the calling application. If credentials are not present
21 there, the search continues in ${XDG_CONFIG_HOME}/containers/auth.json
22 (usually ~/.config/containers/auth.json), $HOME/.docker/config.json,
23 $HOME/.dockercfg.
24 Except for the primary (read/write) file, other files are read-only un‐
27 less the user, using an option of the calling application, explicitly
28 points at it as an override.
29
32 The auth.json file stores, or references, credentials that allow the
33 user to authenticate to container image registries. It is primarily
34 managed by a login command from a container tool such as podman login,
35 buildah login, or skopeo login.
36 Each entry contains a single hostname (e.g., docker.io) or a namespace
39 (e.g., quay.io/user/image) as a key, and credentials in the form of a
40 base64-encoded string as value of auth. The base64-encoded string con‐
41 tains a concatenation of the username, a colon, and the password.
42 When checking for available credentials, the relevant repository is
45 matched against available keys in its hierarchical order, going from
46 most-specific to least-specific. For example, an image pull for my-
47 registry.local/namespace/user/image:latest will result in a lookup in
48 auth.json in the following order:
49 • my-registry.local/namespace/user/image
52 • my-registry.local/namespace/user
54 • my-registry.local/namespace
56 • my-registry.local
58 This way it is possible to setup multiple credentials for a single reg‐
62 istry which can be distinguished by their path.
63 The following example shows the values found in auth.json after the
66 user logged in to their accounts on quay.io and docker.io:
67 {
70 "auths": {
71 "docker.io": {
72 "auth": "erfi7sYi89234xJUqaqxgmzcnQ2rRFWM5aJX0EC="
73 },
74 "quay.io": {
75 "auth": "juQAqGmz5eR1ipzx8Evn6KGdw8fEa1w5MWczmgY="
76 }
77 }
78 }
79 This example demonstrates how to use multiple paths for a single reg‐
83 istry, while preserving a fallback for my-registry.local:
84 {
87 "auths": {
88 "my-registry.local/foo/bar/image": {
89 "auth": "…"
90 },
91 "my-registry.local/foo": {
92 "auth": "…"
93 },
94 "my-registry.local": {
95 "auth": "…"
96 },
97 }
98 }
99 An entry can be removed by using a logout command from a container tool
103 such as podman logout or buildah logout.
104 In addition, credential helpers can be configured for specific reg‐
107 istries, and the credentials-helper software can be used to manage the
108 credentials more securely than storing only base64-encoded credentials
109 in auth.json.
110 When the credential helper is in use on a Linux platform, the auth.json
113 file would contain keys that specify the registry domain, and values
114 that specify the suffix of the program to use (i.e. everything after
115 docker-credential-). For example:
116 {
119 "auths": {
120 "localhost:5001": {}
121 },
122 "credHelpers": {
123 "registry.example.com": "secretservice"
124 }
125 }
126 For more information on credential helpers, please reference the GitHub
130 docker-credential-helpers project ⟨https://github.com/docker/docker-
131 credential-helpers/releases⟩.
132
136 buildah-login(1), buildah-logout(1), podman-login(1), podman-logout(1), skopeo-login(1), skopeo-logout(1)
137
142 Feb 2020, Originally compiled by Tom Sweeney tsweeney@redhat.com
143 ⟨mailto:tsweeney@redhat.com⟩
144 containers-auth.json(5)