.nh
.TH containers-auth.json 5

.SH NAME
.PP
containers-auth.json - syntax for the registry authentication file


.SH DESCRIPTION
.PP
A file in JSON format controlling authentication against container image registries.
The primary (read/write) file is stored at \fB${XDG_RUNTIME_DIR}/containers/auth.json\fR on Linux;
on Windows and macOS, at \fB$HOME/.config/containers/auth.json\fR\&.

.PP
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 there,
the search continues in \fB${XDG_CONFIG_HOME}/containers/auth.json\fR (usually \fB~/.config/containers/auth.json\fR), \fB$HOME/.docker/config.json\fR, \fB$HOME/.dockercfg\fR\&.

.PP
Except for the primary (read/write) file, other files are read-only unless the user, using an option of the calling application, explicitly points at it as an override.

.SH FORMAT
.PP
The auth.json file stores, or references, credentials that allow the user to authenticate
to container image registries.
It is primarily managed by a \fBlogin\fR command from a container tool such as \fBpodman login\fR,
\fBbuildah login\fR, or \fBskopeo login\fR\&.

.PP
Each entry contains a single hostname (e.g., \fBdocker.io\fR) or a namespace (e.g., \fBquay.io/user/image\fR) as a key,
and credentials in the form of a base64-encoded string as value of \fBauth\fR\&. The
base64-encoded string contains a concatenation of the username, a colon, and the
password.

.PP
When checking for available credentials, the relevant repository is matched
against available keys in its hierarchical order, going from most-specific to least-specific.
For example, an image pull for \fBmy-registry.local/namespace/user/image:latest\fR will
result in a lookup in \fBauth.json\fR in the following order:

.RS
.IP \(bu 2
\fBmy-registry.local/namespace/user/image\fR
.IP \(bu 2
\fBmy-registry.local/namespace/user\fR
.IP \(bu 2
\fBmy-registry.local/namespace\fR
.IP \(bu 2
\fBmy-registry.local\fR

.RE

.PP
This way it is possible to setup multiple credentials for a single registry
which can be distinguished by their path.

.PP
The following example shows the values found in auth.json after the user logged in to
their accounts on quay.io and docker.io:

.EX
{
	"auths": {
		"docker.io": {
			"auth": "erfi7sYi89234xJUqaqxgmzcnQ2rRFWM5aJX0EC="
		},
		"quay.io": {
			"auth": "juQAqGmz5eR1ipzx8Evn6KGdw8fEa1w5MWczmgY="
		}
	}
}

.EE

.PP
This example demonstrates how to use multiple paths for a single registry, while
preserving a fallback for \fBmy-registry.local\fR:

.EX
{
	"auths": {
		"my-registry.local/foo/bar/image": {
			"auth": "…"
		},
		"my-registry.local/foo": {
			"auth": "…"
		},
		"my-registry.local": {
			"auth": "…"
		},
	}
}

.EE

.PP
An entry can be removed by using a \fBlogout\fR command from a container
tool such as \fBpodman logout\fR or \fBbuildah logout\fR\&.

.PP
In addition, credential helpers can be configured for specific registries, and the credentials-helper
software can be used to manage the credentials more securely than storing only base64-encoded credentials in \fBauth.json\fR\&.

.PP
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:

.EX
{
    "auths": {
        "localhost:5001": {}
    },
    "credHelpers": {
		"registry.example.com": "secretservice"
	}
}

.EE

.PP
For more information on credential helpers, please reference the GitHub docker-credential-helpers project
\[la]https://github.com/docker/docker\-credential\-helpers/releases\[ra]\&.


.SH SEE ALSO
.EX
buildah-login(1), buildah-logout(1), podman-login(1), podman-logout(1), skopeo-login(1), skopeo-logout(1)

.EE


.SH HISTORY
.PP
Feb 2020, Originally compiled by Tom Sweeney tsweeney@redhat.com
\[la]mailto:tsweeney@redhat.com\[ra]