OCI Container Registry (OCIR) is private by default. Any client that pulls or pushes container images must authenticate.

OCI supports multiple authentication mechanisms. Each method fits different runtime models and security needs.
This post explains three supported authentication options and how they work.

Option 1: OCI User Auth Token

This is the most basic authentication method for OCIR.

How it works

• An Auth Token is generated for an OCI user.
• Docker uses the token as a password.
• The token remains valid until it is rotated or revoked.

Example

docker login phx.ocir.io \
  -u <tenancy-namespace>/<oci-username> \
  -p <auth-token>

This method does not rely on API keys or security tokens.

Option 2: Short-Lived Bearer Token Using API Key–Based Authentication

In this method, OCIR issues a short-lived bearer token (JWT). The token is generated on behalf of the OCI user defined by an API key–based profile.

Key behavior

• Bearer token generation is tied to the OCI user identity
• Authentication uses long-term API keys
• The bearer token itself is short-lived and auto-expires

Step 1: Generate Bearer Token

oci raw-request \
  --http-method GET \
  --target-uri https://phx.ocir.io/20180419/docker/token

Replace phx with the region where your OCIR repository exists.

Step 2: Authenticate Docker Using Bearer Token

docker login phx.ocir.io \
  -u BEARER_TOKEN \
  -p eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.XXXX

Step 3: Use Docker Normally

docker pull phx.ocir.io/namespace/repo:tag
docker push phx.ocir.io/namespace/repo:tag

The bearer token expires automatically and must be regenerated.

Option 3: Short-Lived Bearer Token Using Security Token (WIF)

This option also generates a short-lived OCIR bearer token, but authentication is based on a
Security Token (UPST) instead of long-term API keys.

How it works

• An external identity (OIDC, service account, CI system) is exchanged using Workload Identity Federation
• OCI IAM issues a User Principal Security Token (UPST)
• The bearer token request uses this security token for authentication

The OCIR bearer token generation flow is identical to Option 2.
Only the authentication mechanism changes.

Step 1: Generate Security Token (UPST)

• Exchange an external JWT using WIF
• Save the security token and private key in a profile

Step 2: Continue with Bearer Token Generation

Use the same bearer token generation and Docker login steps described in Option 2,
but authenticated using the security token–based profile.

Summary of Authentication Options

Final Note

Pick the authentication mechanism based on:

• The service you are using
• The authentication models it supports
• Your security and rotation requirements

OCI supports both key-based and token-based models. Design your registry access to align with how your workloads authenticate.