oraclecloud-install-auth

Oracle Cloud Install & Auth

Overview

Configure API key authentication for Oracle Cloud Infrastructure (OCI). OCI auth requires a ~/.oci/config file with five mandatory fields — user OCID, fingerprint, tenancy OCID, region, and the path to an RSA private key. One wrong field produces the cryptic ConfigFileNotFound or InvalidKeyFilePath error with no hint about which field failed.

Purpose: Produce a validated ~/.oci/config file, generate an RSA key pair, upload the public key to OCI, and verify connectivity with both the Python SDK and OCI CLI.

Prerequisites

• OCI account with an active tenancy — sign up at https://cloud.oracle.com
• Python 3.8+ (the OCI Python SDK is the most mature SDK)
• OpenSSL installed (for RSA key generation)
• Your user OCID (Profile > User Settings in the OCI Console) — format: ocid1.user.oc1..aaaa...
• Your tenancy OCID (Administration > Tenancy Details) — format: ocid1.tenancy.oc1..aaaa...
• Your home region (e.g., us-ashburn-1, eu-frankfurt-1)

Instructions

Step 1: Install the OCI Python SDK and CLI

pip install oci oci-cli

Step 2: Generate an RSA Key Pair

mkdir -p ~/.oci
openssl genrsa -out ~/.oci/oci_api_key.pem 2048
chmod 600 ~/.oci/oci_api_key.pem
openssl rsa -pubout -in ~/.oci/oci_api_key.pem -out ~/.oci/oci_api_key_public.pem

Step 3: Get the Key Fingerprint

openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c
# Output: ab:cd:ef:12:34:56:78:90:ab:cd:ef:12:34:56:78:90

Step 4: Upload Public Key to OCI Console

Navigate to: Profile (top-right) > User Settings > API Keys > Add API Key > Paste Public Key

Paste the contents of ~/.oci/oci_api_key_public.pem. The console shows the fingerprint — it must match Step 3.

Step 5: Create the Config File

cat > ~/.oci/config << 'EOF'
[DEFAULT]
user=ocid1.user.oc1..aaaa_YOUR_USER_OCID
fingerprint=ab:cd:ef:12:34:56:78:90:ab:cd:ef:12:34:56:78:90
tenancy=ocid1.tenancy.oc1..aaaa_YOUR_TENANCY_OCID
region=us-ashburn-1
key_file=~/.oci/oci_api_key.pem
EOF
chmod 600 ~/.oci/config

All five fields are required. The key_file must point to the private key (not the public .pem).

Step 6: Verify with the Python SDK

import oci

config = oci.config.from_file("~/.oci/config")
oci.config.validate_config(config)

identity = oci.identity.IdentityClient(config)
user = identity.get_user(config["user"]).data
print(f"Authenticated as: {user.name} ({user.email})")
print(f"Tenancy: {config['tenancy']}")
print(f"Region: {config['region']}")

Step 7: Verify with the OCI CLI

oci iam user get --user-id "$(grep ^user ~/.oci/config | cut -d= -f2)" \
  --query 'data.name' --raw-output

Step 8: Config Validation Script

Save this as validate_oci_config.py to catch common misconfigurations:

import oci
import os

def validate():
    """Validate OCI config file and key access."""
    config_path = os.path.expanduser("~/.oci/config")
    if not os.path.exists(config_path):
        raise FileNotFoundError(f"Config not found: {config_path}")

    config = oci.config.from_file(config_path)
    oci.config.validate_config(config)

    key_path = os.path.expanduser(config.get("key_file", ""))
    if not os.path.exists(key_path):
        raise FileNotFoundError(f"Private key not found: {key_path}")

    perms = oct(os.stat(key_path).st_mode)[-3:]
    if perms != "600":
        print(f"WARNING: Key file permissions are {perms}, should be 600")

    identity = oci.identity.IdentityClient(config)
    identity.get_user(config["user"])
    print("Config is valid. Authentication successful.")

validate()

Output

Successful completion produces:

• An RSA key pair at ~/.oci/oci_api_key.pem (private) and ~/.oci/oci_api_key_public.pem (public)
• A validated ~/.oci/config with all five required fields
• The public key uploaded to your OCI user profile with a matching fingerprint
• Confirmed API connectivity via either the Python SDK or OCI CLI

Error Handling

Error	Code	Cause	Solution
NotAuthenticated	401	Wrong fingerprint or key mismatch	Verify fingerprint matches: openssl rsa -pubout -outform DER -in ~/.oci/oci_api_key.pem | openssl md5 -c
ConfigFileNotFound	—	Missing ~/.oci/config	Run oci setup config or create manually per Step 5
InvalidKeyFilePath	—	key_file points to wrong path or public key	Ensure key_file=~/.oci/oci_api_key.pem (private key, no _public)
InvalidPrivateKey	—	Key file is the public key, not private	The private key starts with -----BEGIN RSA PRIVATE KEY-----
NotAuthorizedOrNotFound	404	User OCID is wrong or IAM policy missing	Double-check user OCID in Console > Profile > User Settings
CERTIFICATE_VERIFY_FAILED	—	SSL cert issue behind corporate proxy	Set OCI_PYTHON_SDK_NO_SERVICE_IMPORTS=1 or install certifi

Examples

Quick auth test with curl (no SDK needed):

# Verify the OCI CLI can reach the API
oci iam region list --output table

Multiple profiles for dev/staging/prod:

# ~/.oci/config
[DEFAULT]
user=ocid1.user.oc1..aaaa_PROD_USER
tenancy=ocid1.tenancy.oc1..aaaa_PROD
region=us-ashburn-1
fingerprint=ab:cd:...
key_file=~/.oci/oci_api_key.pem

[STAGING]
user=ocid1.user.oc1..aaaa_STAGING_USER
tenancy=ocid1.tenancy.oc1..aaaa_STAGING
region=us-phoenix-1
fingerprint=12:34:...
key_file=~/.oci/oci_api_key_staging.pem

# Load a specific profile
config = oci.config.from_file("~/.oci/config", profile_name="STAGING")

Resources

• OCI API Key Authentication — key generation and config file format
• OCI Python SDK Reference — full API documentation
• OCI CLI Reference — command-line interface guide
• SDK Troubleshooting — common auth and connectivity issues
• OCI Console — web dashboard for key upload and OCID lookup
• Always Free Tier — free OCI resources for development

Next Steps

After authentication is working, proceed to oraclecloud-hello-world to launch your first compute instance, or see oraclecloud-common-errors if you hit authentication issues.