Docker Authentication

Docker Bearer Token Realm and Access to Docker Repositories

Security realms define where user identities are managed for different access methods. In Sonatype Nexus Repository, you must enable the Docker Bearer Token Realm to access Docker repositories with a Docker client or another container image manager, such as Docker Desktop, Docker Engine, or Podman. This realm is also required to allow anonymous pulls from Docker repositories.

If you plan to use a Docker client or want to allow anonymous pulls, enable the Docker Bearer Token Realm as described in the Realms help topic.

Anonymous access to Docker repository content is controlled by the nx-view read privilege. For details, refer to the Privileges documentation page.

Authenticated Access to Docker Repositories

When a repository requires authentication, Docker checks for credentials in .docker/config.json file on the client host. If credentials aren’t found, run docker login command.

Unless you use a Docker subdomain connector, the docker login command observes the following syntax for the desired repository or repository group:

docker login <nexus-hostname>:<repository-port>

If you use a subdomain connector, run:

docker login <subdomain>.<nexus-hostname>

Provide your Sonatype Nexus Repository username and password. The email address is optional.

Docker stores the credentials in ~/.docker/config.json and reuses them for later requests to that repository.

You must log in separately for each repository and repository group you access. You will need to perform a login for each repository and repository group that you wish to access.

Using Podman to Log In to Docker Repositories

Nexus Repository supports the Docker repository format and tools that comply with the Docker Registry HTTP API and OCI specifications. Podman is one example of such a tool.

Podman can be used to authenticate to Docker repositories using the same login approach.

Example

podman --log-level debug login localhost:49155

Replace localhost:49155 with your Nexus repository hostname and port.

Note

Use the repository hostname and port when logging in.
The --log-level debug option provides additional output that can help diagnose login failures.

Important Do not include a repository context path in the registry URL (for example, hostname/repository-name). Requests are made to the registry root (for example, /v2/), and using a context path can result in authentication failures.

Tip For continuous integration and other automation that push to Docker repositories, the credentials stored in ~/.docker/config.json prevents repeated logins.

Unauthenticated Access to Docker Repositories

Anonymous access lets users perform limited actions without signing in. For Docker, anonymous pulls require the Docker Bearer Token Realm to be enabled. They also require configuration in two places.

Global level: Controls whether anonymous access is allowed at all.
Repository level: Controls the anonymous Docker pulls from individual repository.

Enable the Docker Bearer Token Realm (Prerequisite)

To enable Docker Bearer Token Realm, take the following steps:

Select Settings→ Security→ Realms.
Check whether the Docker Bearer Token Realm is in the _Active_list. If it isn’t, add it to the _Active_list and select Save.

For more details on security realms, refer to Realms documentation.

Enable Anonymous Access at Global Level

To enable anonymous access at the global level, perform the following steps:

Select Settings→ Security→ Anonymous Access.
Select Allow anonymous users to access the server checkbox.

For more details on anonymous access, refer to Anonymous Access documentation.

Enable Anonymous Access at Repository Level

To enable anonymous access at the repository level, take the following steps:

Select Settings→ Repository→ Repositories.
Open the Docker repository that you want to allow anonymous access for.
Under Repository Connectors, select the Allow anonymous Docker pulls for this repository checkbox.
Select Save to update the repository settings.

Note

For group repositories, anonymous pulls are allowed through the group connector when the group is enabled for anonymous pulls. If you address a member repository connector directly, the member’s own anonymous-pull settings apply.
Anonymous access to Docker repository content is governed by the user’s nx-view role. For finer control over the roles, refer to Privileges documentation.
Clearing the repository-level anonymous access alone affects only the Docker CLI. Other Docker-compatible clients such as Podman continue to honour global anonymous access setting. To block anonymous pulls from all clients, disable global anonymous access as well.