Auth Reference

Authentication Reference

If you are new to OCI or OCInferno, read Getting Started first.

This page is the canonical auth reference for OCInferno. It covers what each auth mode is, how to set it up, and where to retrieve credential material.

Table of Contents

• Auth Modes at a Glance
• OCInferno Startup Commands
• Config Profile (Profile Reuse)
  • Config Profile Overview
  • Config Profile Example Config Shapes
  • Config Profile Selection Logic
• API Key
  • API Key Overview
  • API Key Setup
  • API Key Tool Input Examples
  • API Key Field Mapping
  • API Key Retrieve Credentials
  • API Key UI Walkthrough
• Session Token
  • Session Token Overview
  • Session Token Setup
  • Session Token Tool Input Examples
  • Session Token Field Mapping
  • Session Token Retrieve Credentials
  • Session Token UI Walkthrough
• Instance Principal
  • Instance Principal Overview
  • Instance Principal Setup
  • Instance Principal Tool Input Examples
  • Instance Principal Reference File Schema
  • Instance Principal Field Mapping
  • Instance Principal Retrieve Credentials
  • Instance Principal Federation Flow
  • Instance Principal UI Walkthrough
• Resource Principal
  • Resource Principal Overview
  • Resource Principal Setup
  • Resource Principal Tool Input Examples
  • Resource Principal Reference File Schema
  • Resource Principal Field Mapping
  • Resource Principal Retrieve Credentials
  • Resource Principal UI Walkthrough
• Auth Operational Notes
• Common Auth Errors
• Source References

Auth Modes at a Glance

Auth Type	Supported in OCInferno	Typical Credential Source	Rotation Model	Common Use
Config Profile	Yes (profile)	~/.oci/config profile entries (for example DEFAULT, MYPROFILE)	Depends on backing profile type (API key static or session token refresh)	Fastest way to reuse existing OCI CLI/SDK auth setup
API Key	Yes (profile, api-key)	~/.oci/config + private key PEM, or direct CLI flags	Long-lived unless manually rotated	Human/operator auth and automation
Session Token	Yes (profile, session-token)	~/.oci/config + security_token_file, or direct CLI flags	Short-lived, refreshed	Human/browser-backed temporary auth
Instance Principal	Yes (instance-principal)	IMDS or local cert/key reference file	Automatically refreshed STS token	Running as an OCI compute instance principal
Resource Principal	Yes (resource-principal)	Explicit CLI values and/or reference-file RPST + private key	Token rotation handled by runtime source and reload	OCI Functions/managed workload identity

OCInferno Startup Commands

At startup, add credentials with one of the following patterns:

• profile

profile <credential_name> --filepath <file_path> [--profile <profile_name>]

• api-key

api-key <credential_name> \
  --user <user_ocid> \
  --fingerprint <fingerprint> \
  --tenancy-id <tenancy_ocid> \
  --region <oci_region> \
  (--private-key <pem_or_path> | --private-key-file <path>) \
  [--passphrase <passphrase>] [--passphrase-file <path>]

• session-token

session-token <credential_name> \
  (--token <token_or_path> | --token-file <path>) \
  --region <oci_region> \
  [--tenancy-id <tenancy_ocid>] \
  (--private-key <pem_or_path> | --private-key-file <path>) \
  [--passphrase <passphrase>] [--passphrase-file <path>]

• instance-principal

instance-principal <credential_name> \
  (--reference-file <reference_file> | --on-host) \
  [--region <oci_region>] [--imdsv1|--imdsv2] \
  [--proxy <host:port|url>] [--debug-http]

• resource-principal

resource-principal <credential_name> \
  [--reference-file <reference_file>] \
  [--token <rpst_or_path>] [--token-file <path>] \
  [--private-key <pem_or_path>] [--private-key-file <path>] \
  [--region <oci_region>] [--tenancy-id <tenancy_ocid>] \
  [--passphrase <passphrase>] [--passphrase-file <path>] \
  [--proxy <host:port|url>] [--debug-http]

Quick startup examples:

profile MY_PROFILE --filepath ~/.oci/config --profile MY_PROFILE

api-key TEST_API_KEY --user ocid1.user.oc1..aaaa... --fingerprint 12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef --tenancy-id ocid1.tenancy.oc1..aaaa... --region us-phoenix-1 --private-key-file ~/.oci/oci_api_key.pem

After startup:

• creds / creds me / creds me-full
• creds list / creds list-full
• creds swap [<credname>]

Input handling note:

• For --token, --private-key, and similar fields, OCInferno accepts either:
  • an inline value (JWT / PEM string), or
  • a file path (including file://...) that it will read.
• If a value points to an existing file path, the file content is loaded automatically.
• Startup credential parsing uses shell-style tokenization, so quoted values are supported.
• OCID values must be valid OCI IDs (for example, ocid1.user..., ocid1.tenancy...).

Config Profile (Profile Reuse)

Config Profile Overview

If you already maintain OCI CLI profiles, this is the fastest path for OCInferno. In practice, profile <credname> --filepath <config> [--profile <name>] lets you reuse the same ~/.oci/config profiles used by OCI CLI and SDK tooling.

Config Profile Example Config Shapes

API key backed profile:

[DEFAULT]
user=ocid1.user.oc1..example
fingerprint=11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00
tenancy=ocid1.tenancy.oc1..example
region=us-phoenix-1
key_file=/home/user/.oci/oci_api_key.pem

Session-token backed profile:

[SESSION]
fingerprint=aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
key_file=/home/user/.oci/sessions/SESSION/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..example
region=us-phoenix-1
security_token_file=/home/user/.oci/sessions/SESSION/token

Config Profile Selection Logic

Profile Signal	Effective Auth Path
security_token_file present	Session token profile logic
security_token_file absent	API key profile logic

Command pattern:

profile mycred --filepath ~/.oci/config --profile DEFAULT

API Key

API Key Overview

API key auth uses an OCI user key pair (public key uploaded to the user, private key kept locally). This is typically static and does not expire by default.

API Key Setup

1. Generate a key pair and protect the private key file.
2. Upload the public key to OCI IAM user credentials.
3. Build or update a profile in ~/.oci/config.

Example ~/.oci/config profile:

[DEFAULT]
user=ocid1.user.oc1..aaaa...
fingerprint=12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef
tenancy=ocid1.tenancy.oc1..aaaa...
region=us-phoenix-1
key_file=/home/user/.oci/oci_api_key.pem

You can also gather these values directly from OCI Console during API key generation:

• tenancy
• user
• fingerprint
• region
• local private key file path (key_file)

API Key Tool Input Examples

Profile-based (reuse existing ~/.oci/config profile):

profile my-api-profile --filepath ~/.oci/config --profile DEFAULT

Direct API-key mode (no profile required):

api-key my-api-direct \
  --user ocid1.user.oc1..aaaaexampleuser \
  --fingerprint 12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef \
  --tenancy-id ocid1.tenancy.oc1..aaaaexampletenancy \
  --region us-phoenix-1 \
  --private-key-file ~/.oci/oci_api_key.pem

Direct API-key mode with inline private key value:

api-key my-api-inline \
  --user ocid1.user.oc1..aaaaexampleuser \
  --fingerprint 12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef \
  --tenancy-id ocid1.tenancy.oc1..aaaaexampletenancy \
  --region us-phoenix-1 \
  --private-key "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"

API Key Field Mapping

Field	Required	Source
user	Yes	OCI user OCID
tenancy	Yes	Tenancy OCID
fingerprint	Yes	Uploaded API key fingerprint
Private key (key_file or inline key content)	Yes	Local PEM file or inline PEM
region	Yes for direct api-key mode; recommended for profile mode	Profile region or CLI flag

API Key UI Walkthrough

Example IAM/API-key UI flow (adapted from OCISigner wiki):

1. Open your identity domain and user details.
2. Use the API key action on the user.
3. Capture generated config values and key files.

Reference:

• https://github.com/NetSPI/OCISigner/wiki/Auth-API-Key

Session Token

Session Token Overview

Session token auth is temporary user auth. In practice, you authenticate interactively and the OCI CLI writes a profile that references a token file in the background on your system. To use session based auth you just need to point to the config entry or the specific token and private key on disk.

Session Token Setup

Generate session credentials:

oci session authenticate

This writes:

• A profile entry in ~/.oci/config
• A token file under ~/.oci/sessions/<profile>/token

Example ~/.oci/config session profile:

[MYPROFILE]
fingerprint=8e:50:1d:be:cc:2e:66:6d:b3:b5:e5:4a:1c:f4:f5:03
key_file=/home/user/.oci/sessions/MYPROFILE/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..aaaa...
region=us-phoenix-1
security_token_file=/home/user/.oci/sessions/MYPROFILE/token

Session Token Tool Input Examples

Profile-based session token:

profile mysession --filepath ~/.oci/config --profile MYSESSIONPROFILE

Direct session-token mode (token + key files):

session-token mysession-direct \
  --token-file ~/.oci/sessions/MYSESSIONPROFILE/token \
  --private-key-file ~/.oci/sessions/MYSESSIONPROFILE/oci_api_key.pem \
  --region us-phoenix-1

Direct session-token mode (inline token string):

session-token mysession-inline \
  --token "<JWT_TOKEN_VALUE>" \
  --private-key-file ~/.oci/sessions/MYSESSIONPROFILE/oci_api_key.pem \
  --region us-phoenix-1 \
  --tenancy-id ocid1.tenancy.oc1..aaaaexampletenancy

Notes:

• --tenancy-id is optional if tenancy can be extracted from the token claims.
• If tenancy cannot be extracted, --tenancy-id is required.

Session Token Field Mapping

Field	Required	Source
Session token (security_token_file or inline token content)	Yes	Token file path or --token value
Private key (key_file or inline key content)	Yes	Key file path or --private-key value
tenancy	Yes (explicit or auto-extracted from token claims)	--tenancy-id or JWT claims
region	Yes for direct session-token mode; recommended for profile mode	Profile region or CLI flag
fingerprint	Profile mode only	Session profile fingerprint

Session Token Refresh

Refresh near expiry:

oci session refresh --profile MYPROFILE

Session Token UI Walkthrough

Example session token UI flow (adapted from OCISigner wiki):

1. Start browser-based auth from oci session authenticate.
2. Complete callback and profile creation.

Reference:

• https://github.com/NetSPI/OCISigner/wiki/Auth-Security-Token

Instance Principal

Instance Principal Overview

Instance principal auth lets code call OCI APIs as a compute instance identity. Effective permissions come from dynamic-group membership and IAM policy grants for that dynamic group. Note all other resources fall under resource principal auth, instance principal is just a unique workflow SPECIFICALLY for compute instance resources.

Note: We currently just support commerical OCI accounts, but gov support is trivial and will be added in V1.0 release.

Instance Principal Setup

Use one of two modes:

1. On-host mode (--on-host): run on OCI compute and it will try to curl all the relevant IMDS endponits and auto-setup your auth profile.
2. Reference-file mode (--reference-file): Run on one's local filesystem using the cert/key/intermediate material from the compute instance (gathered via SSRF, command execution, SSH access, etc.).

Instance Principal Retrieve Credentials

The following shows how to retrieve metadata and identity material endpoints (cert, key, intermediate files) from the compute system istelf. Note IMDSv2 requires the "Authorization" hardcoded header while V1 does not. To then use the cert/intermediate/key PEM files locally you just copy stdout to your local system:

# Metadata
curl -s -H "Authorization: Bearer Oracle" http://169.254.169.254/opc/v2/instance/
curl -s -H "Authorization: Bearer Oracle" http://169.254.169.254/opc/v2/instance/regionInfo/
curl -s -H "Authorization: Bearer Oracle" http://169.254.169.254/opc/v2/instance/tenantId

# Idenetity Material
curl -sSL http://169.254.169.254/opc/v2/identity/cert.pem -o cert.pem
curl -sSL http://169.254.169.254/opc/v2/identity/intermediate.pem -o intermediate.pem
curl -sSL http://169.254.169.254/opc/v2/identity/key.pem -o key.pem

Instance Principal Reference File Mode Schema

Minimal JSON example for --reference-file:

{
  "leaf_cert_file": "./certs/leaf_cert.pem",
  "leaf_key_file": "./certs/leaf_key.pem",
  "intermediate_cert_file": "./certs/intermediate.pem",
  "region": "us-phoenix-1",
  "tenancy_id": "ocid1.tenancy.oc1..aaaaexampletenancy"
}

JSON example with multiple intermediates and TLS bundle for reference-file:

{
  "leaf_cert_file": "./certs/leaf_cert.pem",
  "leaf_key_file": "./certs/leaf_key.pem",
  "intermediate_cert_files": [
    "./certs/intermediate_1.pem",
    "./certs/intermediate_2.pem"
  ],
  "passphrase_file": "./certs/leaf_key.passphrase",
  "ca_bundle_file": "./certs/ca_bundle.pem",
  "region": "us-phoenix-1",
  "tenancy_id": "ocid1.tenancy.oc1..aaaaexampletenancy",
  "log_requests": true
}

key=value example:

# instance principal reference file
leaf_cert_file=./certs/leaf_cert.pem
leaf_key_file=./certs/leaf_key.pem
intermediate_cert_file=./certs/intermediate.pem
region=us-phoenix-1
tenancy_id=ocid1.tenancy.oc1..aaaaexampletenancy
ca_bundle_file=./certs/ca_bundle.pem

Instance Principal Tool Input Examples

On-host mode:

instance-principal myip --on-host --region us-phoenix-1 --imdsv2

Reference-file mode:

instance-principal myip-ref --reference-file ./auth/instance_principal.json --region us-phoenix-1

Reference-file mode with proxy + debug:

instance-principal myip-ref --reference-file ./auth/instance_principal.env --proxy http://127.0.0.1:8080 --debug-http

--debug-http note:

• Enables additional federation debug logging during auth setup (for example endpoint/preflight diagnostics).

Instance Principal Field Mapping

Field	Required	Source
leaf_cert_file	Yes for reference-file mode	Local file (often sourced from IMDS cert.pem)
leaf_key_file	Yes for reference-file mode	Local file (often sourced from IMDS key.pem)
intermediate_cert_file / intermediate_cert_files	Yes for reference-file mode	Local file(s) (often sourced from IMDS intermediate.pem)
region	Required unless auto-detected via IMDS	CLI --region, reference file, or IMDS
tenancy_id	Required unless auto-detected via IMDS	Reference file or IMDS

Instance Principal Federation Flow (in case your curious)

1. Signer reads leaf cert/key/intermediate material.
2. Signer sends signed request to https://auth.<region>.oraclecloud.com/v1/x509 (Note Gov support is on the Roadmap for v1.0)
3. OCI returns short-lived federation token in tool.
4. Subsequent module requests use that token-backed signing context.

Note: You can use the --proxy flag as shown in an example command to see the exchange of certificates for a JWT used in future module requests. This is one of the few APIs that would not be covered by the workspace proxy configuration.

IMPORTANT (PROXY ENV BEHAVIOR): During instance-principal federation setup, OCInferno temporarily sets HTTP_PROXY, HTTPS_PROXY, http_proxy, and https_proxy in the process environment while initializing signer traffic, then restores previous values immediately after setup completes.

Instance Principal UI Walkthrough

Example instance-principal flow (adapted from OCISigner wiki):

1. Start from a compute instance host.

Reference:

• https://github.com/NetSPI/OCISigner/wiki/Auth-Instance-Principal

Resource Principal

Resource Principal Overview

Resource principal auth is identity for OCI-managed runtimes (for example, Functions). Credentials are generally supplied to the runtime via environment variables and exchanged for temporary tokens. You can pull the private key and token (Resource Principal Session Token - RPST) from the environment variables and feed them into ocinferno to call things as that resource.

Resource Principal Setup

In OCI workloads, configure runtime and policy so the resource principal can assume required permissions.

OCInferno supports resource-principal credential loading. You can provide material directly (--token, --private-key) or via --reference-file.

A practical setup path is OCI Data Science notebook sessions (or other OCI managed runtimes) where RPST and key material are exposed to the workload environment.

Resource Principal Reference File Mode Schema

Accepted file formats:

• JSON object
• plain key=value lines (# comments allowed)

Minimal JSON example:

{
  "rpst_file": "./token/rpst.jwt",
  "private_pem_file": "./keys/rp_private.pem",
  "region": "us-phoenix-1",
  "tenancy_id": "ocid1.tenancy.oc1..aaaaexampletenancy"
}

Inline JSON example:

{
  "rpst_content": "<JWT_TOKEN_VALUE>",
  "private_pem_content": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "region": "us-phoenix-1",
  "version": "2.2"
}

key=value example:

# resource principal reference file
token_file=./token/rpst.jwt
private_key_file=./keys/rp_private.pem
region=us-phoenix-1
tenancy_id=ocid1.tenancy.oc1..aaaaexampletenancy
passphrase_file=./keys/rp_key.passphrase

Resource Principal Tool Input Examples

Reference-file driven:

resource-principal myrp --reference-file ./auth/resource_principal.json

Direct values/paths only (no reference file):

resource-principal myrp-direct \
  --token-file /etc/ssl/security.token \
  --private-key-file /etc/ssl/rp_key.pem \
  --region us-phoenix-1 \
  --tenancy-id ocid1.tenancy.oc1..aaaaexampletenancy

Mixed mode (file + CLI override):

resource-principal myrp-mixed \
  --reference-file ./auth/resource_principal.env \
  --region us-ashburn-1

Resource Principal Field Mapping

Field	Required	Source
RPST	Yes	--token / --token-file or reference-file token keys
Private key	Yes	--private-key / --private-key-file or reference-file key keys
Region	Recommended	--region or reference-file region
Version	Optional context	--version or reference-file version

Note: OCInferno does not auto-load resource-principal credential material from OS environment variables during credential add/load.

Resource Principal Retrieve Credentials

In OCI-managed runtimes, resource-principal material is often exposed through environment variables and/or mounted files. Use those values as input sources, then pass them explicitly to OCInferno via CLI flags or a reference file.

Resource Principal UI Walkthrough

Example resource-principal flow (adapted from OCISigner wiki):

1. Create/open a managed runtime (example: Data Science notebook session).
2. Open terminal on the workload host and inspect RP env vars/files.
3. Observe the token and key values from the env variables

(base) bash-4.4$ env | grep Resource -i
OCI_RESOURCE_PRINCIPAL_VERSION=2.2
OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM=/etc/ssl/rp_key.pem
OCI_RESOURCE_PRINCIPAL_RPT_PATH=/20190101/notebookSessions/{id}/actions/getResourcePrincipalToken
OCI_RESOURCE_PRINCIPAL_RPST=/etc/ssl/security.token
OCI_RESOURCE_PRINCIPAL_REGION=us-phoenix-1
OCI_RESOURCE_PRINCIPAL_RPT_ID=ocid1.datasciencenotebooksession.oc1.phx.amaaa[REDACTED]
OCI_RESOURCE_PRINCIPAL_RPT_ENDPOINT=https://datascience.us-phoenix-1.oci.oraclecloud.com

(base) bash-4.4$ cat /etc/ssl/security.token
eyJraWQ[REDACTED]ro_KZIRoarqUOtADMaNw

(base) bash-4.4$ cat /etc/ssl/rp_key.pem
-----BEGIN RSA PRIVATE KEY-----
MIIEoQIBAAKCAQEAxFfjALziuL+KvRq33YI0p1tteYkj+BjlQzp1Kdd+dv9nE4Lv
[REDACTED]
-----END RSA PRIVATE KEY-----

Reference:

• https://github.com/NetSPI/OCISigner/wiki/Auth-Resource-Principal

Auth Operational Notes

• Startup supports ocinferno --auth-proxy <host:port|url> (or python -m ocinferno --auth-proxy <host:port|url>) for credential auth exchanges during startup add/load.
• Legacy/internal startup path python -m cli.main is deprecated.

Common Auth Errors

Use this section to quickly map startup auth failures to likely causes and fixes.

Error Message (or prefix)	Likely Cause	Quick Fix
[X] Loaded profile config failed validation: {'tenancy': 'malformed', 'fingerprint': 'malformed'}	Tenancy OCID and/or fingerprint format is invalid (for example typo like cid1... instead of ocid1..., or copied extra characters).	Re-copy values from OCI config/console. Confirm OCIDs start with ocid1. and fingerprint is colon-delimited hex.
[X] Failed to parse credentials. Check for unmatched quotes.	Startup command has unbalanced quotes.	Close/remove stray quotes and retry.
[X] Missing user OCID for api-key auth... (or missing fingerprint/tenancy/region/private key variants)	Required api-key argument missing.	Supply all required fields: --user, --fingerprint, --tenancy-id, --region, and key (--private-key or --private-key-file).
[X] Could not initialize api-key credentials from supplied settings.	Input passed basic checks but signer/profile validation failed (bad key file, wrong passphrase, malformed IDs, invalid fingerprint).	Validate key file content/permissions, passphrase, OCIDs, and fingerprint formatting.
[X] Missing session token... / [X] Missing private key for session-token auth...	Direct session-token mode missing token or key material.	Provide token (--token or --token-file) and key (--private-key or --private-key-file).
[X] Missing tenancy for session-token auth...	Tenancy was not supplied and could not be extracted from JWT claims.	Add --tenancy-id <tenancy_ocid>.
[X] Missing instance-principal mode. Use --on-host or --reference-file.	Neither mode selector supplied.	Provide exactly one: --on-host or --reference-file.
[X] Failed loading instance-principal reference file: ...	Reference file path invalid, unreadable, or missing required keys/cert files.	Check path and required keys: leaf_cert_file, leaf_key_file, and intermediate cert (intermediate_cert_file or intermediate_cert_files).
[X] Missing region. Provide --region when using --on-host.	Region not set and metadata lookup failed.	Pass --region explicitly.
[X] Failed loading resource-principal reference file: ...	Resource-principal reference file path invalid or unreadable.	Confirm file exists and is readable.
[X] Missing resource principal token (RPST)...	No RPST found from CLI args or reference file.	Provide --token / --token-file / --reference-file.
[X] Missing resource principal private key...	No private key found from CLI args or reference file.	Provide --private-key / --private-key-file / --reference-file.
[X] Use only one resource-principal reference file path.	Multiple reference-file paths were provided with conflicting values.	Provide only one reference file source for the command.

Source References

OCISigner wiki pages (structure and workflows):

• https://github.com/NetSPI/OCISigner/wiki/Auth-API-Key
• https://github.com/NetSPI/OCISigner/wiki/Auth-Security-Token
• https://github.com/NetSPI/OCISigner/wiki/Auth-Instance-Principal
• https://github.com/NetSPI/OCISigner/wiki/Auth-Resource-Principal

Oracle docs:

• https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm
• https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm
• https://docs.oracle.com/en-us/iaas/Content/Compute/Tasks/gettingmetadata.htm