Article 16 – API Keys, Auth Tokens, OAuth2 Clients, and Service User Authentication

1. Introduction to Programmatic Authentication

While human users log into the OCI Web Console using a username, password, and MFA factor, automated applications, scripts, CLI tools, and microservices require programmatic authentication mechanisms.

Oracle Cloud Infrastructure (OCI) provides three primary non-interactive credential types:

1. API Signing Keys: RSA 2048-bit key pairs used by the OCI CLI, SDKs, and Terraform provider to sign HTTPS requests.
2. Auth Tokens: Oracle-generated secret strings used as passwords for legacy protocol authentication (such as Docker CLI logins to OCIR or Git repository access).
3. OAuth2 Client Credentials: Industry-standard OAuth2 tokens used for headless microservice-to-microservice authentication inside OCI Identity Domains.

2. Technical Comparison of Programmatic Credentials

[!IMPORTANT]
API Key Fingerprint Validation
When an SDK or CLI executes an API request, OCI validates the HTTP request signature against the fingerprint of the public API signing key uploaded to the user’s profile. If the local private key does not match the uploaded public key fingerprint, OCI returns 401 NotAuthenticated.

3. OCI Web Console (GUI) Step-by-Step Walkthrough

Generating API Keys and Auth Tokens is executed directly within the OCI Web Console GUI.

Step 1: Uploading an API Signing Key in the Console

1. Generate an RSA 2048-bit key pair on your local workstation using OpenSSL:
   bash
openssl genrsa -out ~/.oci/oci_api_key.pem 2048
openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem
2. Log in to the Oracle Cloud Console (https://cloud.oracle.com).
3. Click the Profile Icon in the top-right corner ➔ Click User Settings.
4. Scroll down to Resources in the left panel ➔ Click API Keys.
5. Click Add API Key.
6. Select Choose Public Key File ➔ Upload oci_api_key_public.pem.
7. Click Add.
8. OCI displays the generated Configuration File Preview containing your User OCID, Tenancy OCID, Fingerprint, and Home Region. Copy these values to your local ~/.oci/config file.

Step 2: Generating an Auth Token for Docker CLI (OCIR)

1. On the User Settings page, click Auth Tokens under Resources.
2. Click Generate Token.
3. Enter a description: OCIR-Docker-Login-Token.
4. Click Generate Token.
5. Copy the generated secret string immediately.

Action Warning: Copy this token now. You won't be able to see it again!

1. Use the Auth Token as your password when logging into Oracle Cloud Infrastructure Registry via Docker CLI:
   bash
docker login iad.ocir.io -u 'tenancy-namespace/username'

4. Common Architectural Misconceptions & Pitfalls

Misconception 1: “A User Account Can Have Unlimited Active API Keys”

• Reality: OCI enforces a hard limit of maximum 2 active API Signing Keys per user account. To rotate API keys, upload a second key, update application config files to use the new fingerprint, and delete the old key.

Misconception 2: “Auth Tokens Can Be Retrieved Later in the OCI Console if Lost”

• Reality: Auth Tokens are displayed exactly once at the time of creation. If an Auth Token string is lost, it cannot be recovered from OCI; it must be deleted and regenerated.

5. OCI Credentials vs. Google Cloud (GCP) Credentials

For cloud architects familiar with Google Cloud, the following table compares programmatic authentication: