NAME

       containers-auth.json - syntax for the registry authentication file

DESCRIPTION

       A  file  in  JSON  format  controlling  authentication  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 there, the search continues in
       ${XDG_CONFIG_HOME}/containers/auth.json             (usually             ~/.config/containers/auth.json),
       $HOME/.docker/config.json, $HOME/.dockercfg.

       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.

FORMAT

       The auth.json file stores, or references, credentials that allow the user to  authenticate  to  container
       image registries.  It is primarily managed by a login command from a container tool such as podman login,
       buildah login, or skopeo login.

       Each  entry  contains  a single hostname (e.g., docker.io) or a namespace (e.g., quay.io/user/image) as a
       key, and credentials in the form of a base64-encoded string as value of auth. The  base64-encoded  string
       contains a concatenation of the username, a colon, and the password.

       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 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 more securely than storing only base64-encoded credentials
       in auth.json.

       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⟩.

SEE ALSO

       buildah-login(1), buildah-logout(1), podman-login(1), podman-logout(1), skopeo-login(1), skopeo-logout(1)

HISTORY

       Feb 2020, Originally compiled by Tom Sweeney tsweeney@redhat.com ⟨mailto:tsweeney@redhat.com⟩

                                                                                         containers-auth.json(5)