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