Oracle ERP Cloud Authentication Patterns

TL;DR

• Bottom line: Oracle Fusion Cloud supports four OAuth 2.0 grant types (client credentials, authorization code, resource owner password, JWT assertion), SAML 2.0 federation for SSO, and Basic Auth as a legacy fallback. JWT assertion with certificate-based trust is the most secure for unattended integrations; client credentials is the most common. [src1]
• Key limit: Access tokens default to 3,600s (1 hour), capped by identity domain session lifetime (default 8h). Refresh tokens require offline_access scope and default to 7 days. [src1, src5]
• Watch out for: Identity propagation (flowing end-user identity through middleware) requires specific OAuth configurations -- JWT User Assertion in OIC or on-behalf-of flows manually. Getting this wrong means all API calls execute as the integration user. [src3]
• Best for: Deep-dive into implementation patterns for each auth flow, certificate lifecycle, SAML federation, and multi-environment strategies.
• Authentication: OAuth 2.0 client credentials for most server-to-server; JWT assertion for zero-secret deployments; authorization code for user-delegated; SAML 2.0 for browser SSO. [src1, src2]

System Profile

Oracle ERP Cloud (Fusion Cloud Applications) centralizes all authentication through OCI IAM identity domains (the successor to Oracle Identity Cloud Service / IDCS). Every Fusion Cloud environment comes with a pre-provisioned identity domain where Fusion Applications are auto-registered as resource applications. Third-party systems must be registered as confidential client applications. This card covers the detailed implementation patterns for each authentication flow. For a high-level overview of which method to choose, see the prerequisite card (oracle-erp-cloud-authentication).

API Surfaces & Capabilities

Oracle Fusion Cloud exposes multiple API surfaces. Authentication applies uniformly -- the same OAuth token works for REST, SOAP, and UCM endpoints. The token's scope and the integration user's Fusion roles determine which operations are permitted.

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Authentication

Detailed implementation patterns for each Oracle ERP Cloud authentication flow.

Pattern 1: Client Credentials (2-Legged OAuth)

Most common pattern for server-to-server integrations. The confidential application authenticates using its client ID and client secret. All API calls execute under the integration user's identity. [src1]

Pattern 2: JWT Assertion (Certificate-Based)

Most secure pattern for machine-to-machine. Instead of a shared client secret, the application signs a JWT with a private key. The public certificate is uploaded to the confidential application. [src2]

Pattern 3: Authorization Code (3-Legged OAuth)

Used when the application needs to act on behalf of a specific user. Requires interactive browser-based authentication. Not suitable for unattended batch processing. [src1]

Pattern 4: SAML 2.0 Federation for SSO

Enables browser-based Single Sign-On with external Identity Providers (Azure AD, Okta, ADFS, PingFederate). Applies only to interactive browser-based authentication -- API-level OAuth flows bypass federation entirely. [src6, src7]

Pattern 5: Identity Propagation Through Middleware

Flows end-user identity through OIC or other middleware to Fusion Cloud for audit and security purposes. Uses OAuth JWT User Assertion security policy. [src3]

Pattern 6: External IdP Token Exchange (Azure AD)

Exchange Azure AD tokens for Oracle access tokens without requiring users to re-authenticate against the Oracle identity domain. [src7]

Authentication Gotchas

• JWT exp clock skew tolerance is ~5 minutes. Server clock drift beyond that causes invalid_grant errors. Use NTP. [src2]
• Some Oracle environments require the full certificate chain (not just the leaf cert) for production JWT flows. [src2]
• Oracle uses URN-based scopes (urn:opc:resource:consumer::all), not standard openid profile. Incorrect scope returns 400 with minimal diagnostic info. [src1]
• Token endpoint URL varies by domain type post-IDCS migration. [src1, src5]
• SAML NameID format mismatch causes SSO failure or duplicate user creation. Verify format alignment. [src6]

Constraints

• Only confidential applications can be registered -- public clients (SPAs, mobile apps) cannot directly access Fusion Cloud APIs. [src1]
• Token lifetime ceiling: MIN(configured_expiry, remaining_session_lifetime). Default session = 8h (28,800s). [src5]
• LBAC produces 401/403 indistinguishable from auth failures. Must allowlist integration platform IPs. [src4]
• MFA enforcement blocks Resource Owner Password grant for service accounts. Use Client Credentials or JWT flows. [src6]
• JWT certificates expire silently. Oracle does not send notifications. Monitor and rotate proactively. [src2]
• Each environment (prod/test/dev) has its own identity domain. OAuth registrations, certs, tokens are not portable. [src1]
• SAML federation is browser-only. Do not attempt SAML assertions with REST APIs unless using the SAML Bearer Assertion grant. [src6, src7]

Integration Pattern Decision Tree

START -- Choosing an Oracle ERP Cloud authentication pattern
|-- What type of client?
|   |-- Server/backend (unattended)
|   |   |-- Can you manage certificates and PKI lifecycle?
|   |   |   |-- YES --> Pattern 2: JWT Assertion (most secure)
|   |   |   |-- NO --> Pattern 1: Client Credentials
|   |   |-- Need user-level audit trail?
|   |       |-- YES --> Pattern 5: Identity Propagation
|   |       |-- NO --> Pattern 1: Client Credentials
|   |-- Browser-based (user-interactive)
|   |   |-- Users have existing corporate IdP credentials?
|   |   |   |-- YES, Azure AD --> Pattern 6: Token Exchange
|   |   |   |-- YES, Okta/ADFS --> Pattern 4: SAML + Pattern 3
|   |   |   |-- NO --> Pattern 3: Authorization Code
|   |-- Middleware (OIC, MuleSoft, Boomi)
|   |   |-- OIC within same identity domain?
|   |   |   |-- YES --> OAuth auto-configured
|   |   |   |-- NO --> Manual registration + Pattern 1 or 2
|   |   |-- Need identity propagation?
|   |       |-- YES --> Pattern 5
|   |       |-- NO --> Pattern 1
|   |-- Quick test / debugging
|       |-- Basic Auth (dev/test only, never production)
|-- LBAC enabled?
|   |-- YES --> Allowlist IPs FIRST
|   |-- NO --> Proceed
|-- Multi-environment?
    |-- YES --> Separate app registration per environment
    |-- NO --> Single registration

Quick Reference

OAuth 2.0 Grant Types Comparison

Token Endpoint Reference

Step-by-Step Integration Guide

1. Register a Confidential Application in OCI IAM

Create the OAuth client that all patterns depend on. Navigate to OCI Console > Identity & Security > Domains > Applications > Add Application > Confidential Application. Configure grant types, scopes, and activate. [src1]

Verify: Applications list shows Status: Active.

2. Obtain Client Credentials Token

Exchange client credentials for an access token (Pattern 1). [src1, src4]

curl -X POST \
  "https://<tenant>.identity.oraclecloud.com/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all"

Verify: Response contains "token_type": "Bearer" and "expires_in": 3600.

3. Generate and Use JWT Assertion

Create a signed JWT and exchange for access token (Pattern 2). [src2]

# Generate key pair (one-time)
openssl genrsa -out private_key.pem 4096
openssl req -new -x509 -key private_key.pem -out public_cert.pem -days 730

# Upload public_cert.pem to confidential app > Certificates tab

# Exchange signed JWT for access token
curl -X POST \
  "https://<tenant>.identity.oraclecloud.com/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<SIGNED_JWT>&scope=urn:opc:resource:consumer::all"

Verify: Response contains "access_token" without sending any client secret.

4. Configure SAML 2.0 Federation

Set up SSO with an external Identity Provider (Pattern 4). Navigate to Identity Providers in your identity domain, upload IdP metadata, configure NameID mapping. [src6, src7]

Verify: User can access Fusion Cloud via IdP login without Oracle credentials.

5. Implement Token Caching and Refresh

Prevent excessive token requests for long-running integrations. [src5]

Verify: Multiple calls within token lifetime return cached token without endpoint hit.

6. Set Up Identity Propagation

Configure middleware to flow end-user identity to Fusion Cloud for audit trail compliance. [src3]

Verify: Fusion Cloud audit trail shows end user's username, not integration service account.

Code Examples

Python: JWT Assertion with Certificate-Based Auth

# Input:  Private key PEM file, Client ID, Token endpoint
# Output: Access token via JWT assertion (no shared secret)

import time
import jwt  # PyJWT>=2.8.0
import requests  # requests>=2.31.0

def get_oracle_token_jwt(token_url, client_id, private_key_path):
    with open(private_key_path, "r") as f:
        private_key = f.read()
    now = int(time.time())
    claims = {
        "iss": client_id, "sub": client_id,
        "aud": token_url, "iat": now, "exp": now + 300,
    }
    signed_jwt = jwt.encode(claims, private_key, algorithm="RS256")
    resp = requests.post(token_url, data={
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "assertion": signed_jwt,
        "scope": "urn:opc:resource:consumer::all",
    }, headers={"Content-Type": "application/x-www-form-urlencoded"}, timeout=30)
    resp.raise_for_status()
    return resp.json()["access_token"]

JavaScript/Node.js: Authorization Code with PKCE

// Input:  Client ID, Redirect URI, endpoints
// Output: Access token via authorization code + PKCE

import crypto from "crypto";

function generatePKCE() {
  const verifier = crypto.randomBytes(32).toString("base64url");
  const challenge = crypto.createHash("sha256")
    .update(verifier).digest("base64url");
  return { verifier, challenge };
}

async function exchangeCodeForToken(tokenEndpoint, clientId,
    clientSecret, code, redirectUri, codeVerifier) {
  const credentials = Buffer.from(
    `${clientId}:${clientSecret}`).toString("base64");
  const resp = await fetch(tokenEndpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Basic ${credentials}`,
    },
    body: new URLSearchParams({
      grant_type: "authorization_code", code,
      redirect_uri: redirectUri, code_verifier: codeVerifier,
    }),
  });
  if (!resp.ok) throw new Error(`Failed: ${resp.status}`);
  return resp.json();
}

cURL: Test Each Authentication Pattern

# Pattern 1: Client Credentials
curl -X POST \
  "https://<tenant>.identity.oraclecloud.com/oauth2/v1/token" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all"

# Pattern 2: JWT Assertion
curl -X POST \
  "https://<tenant>.identity.oraclecloud.com/oauth2/v1/token" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<JWT>&scope=urn:opc:resource:consumer::all"

# Verify token against Fusion Cloud
curl "https://<erp-host>.fa.ocs.oraclecloud.com/fscmRestApi/resources/latest" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" -w "\nHTTP: %{http_code}\n"

Data Mapping

Authentication Configuration Mapping

Data Type Gotchas

• Token endpoint URL format: IDCS-migrated = <tenant>.identity.oraclecloud.com; Default domain = <region>.identity.oraclecloud.com. Use OpenID Discovery as authoritative source. [src1]
• Scope URN is Oracle-specific (urn:opc:resource:consumer::all). Standard OAuth scopes like openid profile return 400. [src1]
• JWT exp requires seconds-precision Unix timestamps. Millisecond timestamps cause invalid_grant. [src2]
• Certificate format: Oracle requires PEM. Convert PKCS12: openssl pkcs12 -in cert.p12 -out cert.pem -nodes. [src2]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Certificate expiry breaks JWT silently: Oracle does not send notifications. Fix: Automate certificate expiry monitoring; rotate 30 days before expiry. [src2]
• LBAC false positives after IP changes: Cloud platforms change NAT Gateway IPs during maintenance. Fix: Use CIDR blocks in LBAC allowlist; monitor for 401 spikes. [src4]
• MFA policy change breaks service accounts: Admin enables MFA for "all users" including service accounts. Fix: Dedicated sign-on policy rule for service accounts above MFA rule. [src6]
• Token endpoint URL mismatch post-migration: Teams hardcode old IDCS URL. Fix: Use OpenID Discovery to dynamically resolve token URL. [src1]
• Redirect URI mismatch in Auth Code flow: Trailing slash or HTTP/HTTPS difference. Fix: Copy URI directly from app into OCI IAM; verify exact match. [src1]
• Refresh token silent expiry: 7-day default; monthly batch jobs fail. Fix: Request new token each run for infrequent jobs. [src5]

Anti-Patterns

Wrong: Using Basic Auth for production integrations

# BAD -- credentials in every request, exposed in logs
response = requests.get(url, auth=("user", "P@ssw0rd"))

Correct: Use OAuth 2.0 with vault-stored credentials

# GOOD -- token-based, credentials from vault, token cached
token = token_mgr.get_token()
response = requests.get(url, headers={"Authorization": f"Bearer {token}"})

Wrong: Requesting a new token for every API call

# BAD -- 1000 invoices = 1000 token requests (200-500ms each)
for inv_id in ids:
    token = get_fresh_token(...)
    requests.get(f"{base}/invoices/{inv_id}", headers={"Authorization": f"Bearer {token}"})

Correct: Cache token and reuse until near expiry

# GOOD -- one token per hour, reused across all calls
token_mgr = OracleTokenManager(...)
for inv_id in ids:
    token = token_mgr.get_token()  # cached or refreshes if <60s left
    requests.get(f"{base}/invoices/{inv_id}", headers={"Authorization": f"Bearer {token}"})

Wrong: Hardcoding token endpoint URLs

# BAD -- breaks on IDCS migration or domain changes
TOKEN_URL = "https://idcs-abc123.identity.oraclecloud.com/oauth2/v1/token"

Correct: Use OpenID Discovery for endpoint resolution

# GOOD -- resilient to endpoint changes
disco = requests.get(f"{domain}/.well-known/openid-configuration").json()
TOKEN_URL = disco["token_endpoint"]

Wrong: Sharing one certificate across all environments

# BAD -- compromised dev cert exposes production

Correct: Separate certificates per environment

# GOOD -- each environment has own key pair
# prod: CA-signed, 2-year | test/dev: self-signed, 1-year
openssl genrsa -out prod_key.pem 4096
openssl req -new -x509 -key prod_key.pem -out prod_cert.pem -days 730

Common Pitfalls

• Resource Owner Password in production: Does not support MFA, deprecated in OAuth 2.1. Fix: Migrate to Client Credentials or JWT Assertion immediately. [src4]
• Not monitoring certificate expiry: JWT flow fails silently on expiry. Fix: Automate monitoring; alert 30/14/7 days before expiry. [src2]
• Wrong identity domain for app registration: App in Default domain lacks Fusion resource permissions. Fix: Register in OracleIdentityCloudService domain. [src1]
• Ignoring LBAC when debugging auth failures: 401/403 from LBAC looks identical to auth failures. Fix: Check LBAC first; test from allowlisted IP. [src4]
• Not using PKCE with Authorization Code: Auth codes can be intercepted. Fix: Always use PKCE (S256) even with confidential clients. [src5]
• Assuming SAML applies to API calls: SAML is browser-only SSO. Fix: Use OAuth grant types for all API auth. [src6, src7]

Diagnostic Commands

# Discover all identity domain endpoints
curl -s "https://<domain>.identity.oraclecloud.com/.well-known/openid-configuration" | python3 -m json.tool

# Test Client Credentials token request
curl -v -X POST "https://<domain>.identity.oraclecloud.com/oauth2/v1/token" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all"

# Decode JWT payload (inspect without verification)
echo "<TOKEN>" | cut -d'.' -f2 | base64 -d 2>/dev/null | python3 -m json.tool

# Verify token against Fusion Cloud
curl -w "\nHTTP: %{http_code}\n" \
  "https://<erp-host>.fa.ocs.oraclecloud.com/fscmRestApi/resources/latest" \
  -H "Authorization: Bearer <TOKEN>"

# Check certificate expiry
openssl x509 -in cert.pem -noout -enddate

# Test LBAC (compare from two IPs)
curl -s -o /dev/null -w "%{http_code}" "https://<erp-host>.fa.ocs.oraclecloud.com/fscmRestApi/resources/latest" \
  -H "Authorization: Bearer <TOKEN>"

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Oracle does not publish fixed API rate limits. Throttling is adaptive per tenant/pod. HTTP 429 is your only signal for both token and API request rate limiting.
• Token lifetime = MIN(configured_expiry, remaining_session_lifetime). Default session = 8h. Align both settings if you need longer tokens.
• Post-IDCS migration, tenants have multiple identity domains. Some Oracle docs still reference IDCS terminology. Functionality is identical in OCI IAM identity domains.
• SAML federation only affects interactive browser login. API-level OAuth flows bypass federation entirely.
• Each Fusion Cloud environment has its own identity domain. OAuth registrations, certificates, tokens, and SAML configs are completely separate per environment.
• Oracle recommends Client Credentials for most machine-to-machine and JWT Assertion for high-security. Authorization Code only when user-context is genuinely needed.