containers-auth.json - syntax for the registry authentication file
A credentials file in JSON format used to authenticate against container image
registries. The primary (read/write) file is stored at
${XDG_RUNTIME_DIR}/containers/auth.json on Linux; on Windows and macOS,
at
$HOME/.config/containers/auth.json.
When searching for the credential for a registry, the following files will be
read in sequence until the valid credential is found: first reading the
primary (read/write) file, or the explicit override using an option of the
calling application. If credentials are not present, search in
${XDG_CONFIG_HOME}/containers/auth.json (usually
~/.config/containers/auth.json),
$HOME/.docker/config.json,
$HOME/.dockercfg.
Except the primary (read/write) file, other files are read-only, unless the user
use an option of the calling application explicitly points at it as an
override.
The auth.json file stores encrypted authentication information for the user to
container image registries. The file can have zero to many entries and is
created by a
login command from a container tool such as
podman
login,
buildah login or
skopeo login. Each entry either contains
a single hostname (e.g.
docker.io) or a namespace (e.g.
quay.io/user/image) as a key and an auth token in the form of a base64
encoded string as value of
auth. The token is built from the
concatenation of the username, a colon, and the password. The registry name
can additionally contain a repository name (an image name without tag or
digest) and namespaces. The path (or namespace) is matched in its hierarchical
order when checking for available authentications. For example, an image pull
for
my-registry.local/namespace/user/image:latest will result in a
lookup in
auth.json in the following order:
- •
-
my-registry.local/namespace/user/image
- •
-
my-registry.local/namespace/user
- •
-
my-registry.local/namespace
- •
-
my-registry.local
This way it is possible to setup multiple credentials for a single registry
which can be distinguished by their path.
The following example shows the values found in auth.json after the user logged
in to their accounts on quay.io and docker.io:
{
"auths": {
"docker.io": {
"auth": "erfi7sYi89234xJUqaqxgmzcnQ2rRFWM5aJX0EC="
},
"quay.io": {
"auth": "juQAqGmz5eR1ipzx8Evn6KGdw8fEa1w5MWczmgY="
}
}
}
This example demonstrates how to use multiple paths for a single registry, while
preserving a fallback for
my-registry.local:
{
"auths": {
"my-registry.local/foo/bar/image": {
"auth": "…"
},
"my-registry.local/foo": {
"auth": "…"
},
"my-registry.local": {
"auth": "…"
},
}
}
An entry can be removed by using a
logout command from a container tool
such as
podman logout or
buildah logout.
In addition, credential helpers can be configured for specific registries and
the credentials-helper software can be used to manage the credentials in a
more secure way than depending on the base64 encoded authentication provided
by
login. If the credential helpers are configured for specific
registries, the base64 encoded authentication will not be used for operations
concerning credentials of the specified registries.
When the credential helper is in use on a Linux platform, the auth.json file
would contain keys that specify the registry domain, and values that specify
the suffix of the program to use (i.e. everything after docker-credential-).
For example:
{
"auths": {
"localhost:5001": {}
},
"credHelpers": {
"registry.example.com": "secretservice"
}
}
For more information on credential helpers, please reference the GitHub
docker-credential-helpers project
⟨
https://github.com/docker/docker-credential-helpers/releases⟩.
Feb 2020, Originally compiled by Tom Sweeney
[email protected]
⟨mailto:
[email protected]⟩