Skip to main content

Configure OCI Repository

Configure your OCI client to connect to and authenticate to a Nexus OCI repository. Note that you must create an OCI repository in Nexus before configuration. For more details, see Create an OCI repository.

OCI clients communicate with a registry through the OCI Distribution API at the /v2/ endpoint and complete a bearer-token handshake. When a client first connects to the registry, the registry may respond with a 401 unauthorized status and a WWW-Authenticate header. This header tells the client where to request a bearer token and which permissions are required.The client then requests a scoped bearer token from the authentication service and retries the original request with the token.

OCI-compatible clients, such as Docker, Podman, Helm, and ORAS, handle this authentication flow automatically after you log in. These clients caches your login credentials locally, typically in ~/.docker/config.json or a container's auth.json file and use those credentials to request bearer tokens when needed.

Log in

To login to any of the OCI compatible clients, use the repository host (no scheme, no path) as the registry address. Replace <NexusURL> with your hostname which maybe in the format of example.nexus.com.

  • Docker

    docker login <NexusURL>

  • Podman

    podman login <NexusURL>

  • Helm

    helm registry login <NexusURL> -u <USERNAME> -p <PASSWORD>

  • ORAS

    oras login <NexusURL> -u <USERNAME> -p <PASSWORD>

  • Crane

    crane auth login <NexusURL> -u <USERNAME> -p <PASSWORD>

  • Skopeo

    skopeo login <NexusURL>

Sonatype recommends user token login for all CLI and CI usage. User token is required when single sign-on (SSO) is enabled as interactive password cannot be used. To generate a user token, navigate to Account → Access → Usertoken. Use the name code as your username and pass code as your password.

Nexus Repository Cloud does not support anonymous access and Self hosted deployments may support anonymous pulls when configured.

Routing

Routing determines how OCI clients resolve a repository endpoint. Nexus Repository supports path-based, subdomain, and port-based addresses to expose the same OCI /v2/ registry API through deployment specific URL patterns.

Mode

Client Address

Availability

Path-based

<NexusURL>/<repository-name>/<image>

All deployments. This is the only mode in Nexus Repository Cloud.

Subdomain

<repository-name>.<NexusURL>/<image>

Self-hosted, Nexus Repository Pro only. Requires the subdomain-routing license entitlement.

Port, also called Other Connectors

<NexusURL>:<port>/<image>

Self-hosted deployments.

Note

In self-hosted deployments, OCI repositories authenticate /v2/ through the OCI Bearer Token Realm. Administrators can enable this realm under Administration → Security → Realms. In Nexus Repository Cloud, Sonatype manages Realms. For more details, refer Realms documentation.

TLS

Nexus Repository Cloud is served over HTTPS with a valid certificate, so --plain-http or insecure-registry configuration is not required.

For self-hosted HTTP connectors, Helm and ORAS accept --plain-http. Docker requires the host to be listed under insecure-registries.