containers-auth.json(5)

1containers-auth.json(5)       File Formats Manual      containers-auth.json(5)
2
3
4

NAME

6       containers-auth.json - syntax for the registry authentication file
7
8
9

DESCRIPTION

11       A  credentials  file  in  JSON format used to authenticate against con‐
12       tainer image registries.  The primary (read/write) file  is  stored  at
13       ${XDG_RUNTIME_DIR}/containers/auth.json on Linux; on Windows and macOS,
14       at $HOME/.config/containers/auth.json.
15
16
17       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       search  in  ${XDG_CONFIG_HOME}/containers/auth.json  (usually   ~/.con‐
22       fig/containers/auth.json), $HOME/.docker/config.json, $HOME/.dockercfg.
23
24
25       Except the primary (read/write) file, other files are read-only, unless
26       the user use an option of the calling application explicitly points  at
27       it as an override.
28
29

FORMAT

31       The  auth.json  file  stores, or references, credentials that allow the
32       user to authenticate to container image registries.  The file can  have
33       zero to many entries and is created by a login command from a container
34       tool such as podman login, buildah login or skopeo  login.  Each  entry
35       either contains a single hostname (e.g. docker.io) or a namespace (e.g.
36       quay.io/user/image) as a key and an auth token in the form of a  base64
37       encoded string as value of auth. The token is built from the concatena‐
38       tion of the username, a colon, and the password. The registry name  can
39       additionally  contain  a  repository name (an image name without tag or
40       digest) and namespaces. The path (or namespace) is matched in its hier‐
41       archical  order  when checking for available authentications. For exam‐
42       ple, an image  pull  for  my-registry.local/namespace/user/image:latest
43       will result in a lookup in auth.json in the following order:
44
45
46              • my-registry.local/namespace/user/image
47
48              • my-registry.local/namespace/user
49
50              • my-registry.local/namespace
51
52              • my-registry.local
53
54
55
56       This way it is possible to setup multiple credentials for a single reg‐
57       istry which can be distinguished by their path.
58
59
60       The following example shows the values found  in  auth.json  after  the
61       user logged in to their accounts on quay.io and docker.io:
62
63
64              {
65                   "auths": {
66                        "docker.io": {
67                             "auth": "erfi7sYi89234xJUqaqxgmzcnQ2rRFWM5aJX0EC="
68                        },
69                        "quay.io": {
70                             "auth": "juQAqGmz5eR1ipzx8Evn6KGdw8fEa1w5MWczmgY="
71                        }
72                   }
73              }
74
75
76
77       This  example  demonstrates how to use multiple paths for a single reg‐
78       istry, while preserving a fallback for my-registry.local:
79
80
81              {
82                   "auths": {
83                        "my-registry.local/foo/bar/image": {
84                             "auth": "…"
85                        },
86                        "my-registry.local/foo": {
87                             "auth": "…"
88                        },
89                        "my-registry.local": {
90                             "auth": "…"
91                        },
92                   }
93              }
94
95
96
97       An entry can be removed by using a logout command from a container tool
98       such as podman logout or buildah logout.
99
100
101       In  addition,  credential  helpers  can be configured for specific reg‐
102       istries and the credentials-helper software can be used to  manage  the
103       credentials  in  a more secure way than depending on the base64 encoded
104       authentication provided by login.  If the credential helpers  are  con‐
105       figured for specific registries, the base64 encoded authentication will
106       not be used for operations concerning credentials of the specified reg‐
107       istries.
108
109
110       When the credential helper is in use on a Linux platform, the auth.json
111       file would contain keys that specify the registry  domain,  and  values
112       that  specify  the  suffix of the program to use (i.e. everything after
113       docker-credential-).  For example:
114
115
116              {
117                  "auths": {
118                      "localhost:5001": {}
119                  },
120                  "credHelpers": {
121                        "registry.example.com": "secretservice"
122                   }
123              }
124
125
126
127       For more information on credential helpers, please reference the GitHub
128       docker-credential-helpers   project  ⟨https://github.com/docker/docker-
129       credential-helpers/releases⟩.
130
131
132

HISTORY

140       Feb  2020,  Originally  compiled  by  Tom  Sweeney  tsweeney@redhat.com
141       ⟨mailto:tsweeney@redhat.com⟩
142
143
144
145                                                       containers-auth.json(5)

NAME

DESCRIPTION

FORMAT

SEE ALSO

HISTORY