Authenticate with OCI-compliant registries

You can use notation to authenticate to an OCI-compliant registry. This is useful for inspecting artifacts in registries that do not offer a web frontend for view artifacts.

When you authenticate to an OCI-compliant registry, notation, by default, uses a credentials store to store your credentials in a secure manner. It is possible to store your credentials in environment variables or as base64 encoded values in a configuration file, but these approaches are not secure and are not recommended for production environments. It is strongly recommended that you use a credentials store to authenticate to an OCI-compliant registry.

Configure a credentials store

A credentials store is a secure location that stores your credentials, such as usernames and passwords. Operating systems often include a default credentials store, such as osxkeychain on macOS or wincred on Windows. You can also use a third-party credentials store, such as pass.

By default, notation uses a credentials store during the following operations:

• Store credentials when you log in to a registry
• Read credentials when accessing a registry to sign, verify, or display artifacts
• Delete credentials from the credentials store when you log out of a registry

You have three options for configuring a credentials store:

1. Use the notation config.json file.
2. Use the Docker configuration file, which is located at ~/.docker/config.json.
3. Use the default credentials store for your operating system.

notation will resolve the credentials store in the order shown above. If no credential store is available and no other method is used for credentials, such as environment variables, notation login will not store the credentials and the command will fail.

To configure a credentials store in the notation configuration file, add a credStore to the notation config.json file. The following example shows osxkeychain as the configured credentials store.

{
  ...
  "credStore": "osxkeychain"
  ...
}

To configure a credentials store in the Docker configuration file, add a credStore to ~/.docker/config.json. The following example shows pass as the configured credentials store.

{
  ...
  "credsStore": "pass"
  ...
}

Configure environment variables to authenticate to an OCI-compliant registry

Set the NOTATION_USERNAME and NOTATION_PASSWORD environment variables to authenticate to an OCI-compliant registry.

export NOTATION_USERNAME="YOUR_REGISTRY_USERNAME"
export NOTATION_PASSWORD="YOUR_REGISTRY_PASSWORD"

After the environment variables are set, you can use Notation with your registry without notation login.

For security reasons, unset the environment variables after you are done interacting with the OCI-compliant registry. For example:

unset NOTATION_USERNAME
unset NOTATION_PASSWORD

Configure config.json to authenticate to an OCI-compliant registry

You can configure the notation config.json file to store the credentials for your OCI-compliant registry as base64 encoded values. For example:

{
  "auths": {
    "<registry>": {
      "auth": "<base64encoded>",
    }
  },
}

Use notation login to authenticate to an OCI-compliant registry

To authenticate to an OCI-compliant registry, use the notation login command with your registry, username, and password. For example:

notation login -u <username> -p <password> <registry>

Use notation logout to log out of an OCI-compliant registry

To log out of an OCI-compliant registry, use the notation logout command with your registry. For example:

notation logout <registry>

OCI-compliant registries

For a full list of OCI-compliant registries compatible with notation, see OCI-compliant registries.