Oracle ERP Cloud Authentication

TL;DR

• Bottom line: Oracle ERP Cloud supports Basic Auth, OAuth 2.0 (client credentials, authorization code, resource owner), and JWT assertion. OAuth 2.0 with JWT bearer is recommended for server-to-server integrations. [src1]
• Key limit: Access tokens default to 1 hour (3,600s) and cannot exceed the session lifetime (default 8h / 28,800s). Refresh tokens default to 7 days. [src5]
• Watch out for: IDCS has been migrated to OCI IAM identity domains (2022-2024). All IDCS configurations continue to work, but the admin console is now under OCI IAM. [src7]
• Best for: Any system-to-system integration with Oracle ERP Cloud REST or SOAP APIs -- financials, procurement, HCM, SCM modules.
• Authentication: OAuth 2.0 client credentials (2-legged) or JWT assertion for unattended integrations; authorization code (3-legged) for user-context operations. [src1, src2]

System Profile

Oracle ERP Cloud (officially "Oracle Fusion Cloud Applications") is Oracle's cloud-native ERP suite covering financials, procurement, project management, supply chain, and HCM. Authentication is handled centrally through OCI IAM identity domains (formerly Oracle Identity Cloud Service / IDCS). All Fusion Cloud Applications are auto-registered as resource applications in the identity domain, and any third-party integrating system must be registered as a confidential client application. [src1]

This card covers authentication for all Oracle Fusion Cloud REST and SOAP APIs across all editions. It does not cover Oracle NetSuite (which uses Token-Based Authentication / TBA) or Oracle E-Business Suite on-premise (which uses Oracle Access Manager). [src2]

API Surfaces & Capabilities

Oracle ERP Cloud exposes multiple API surfaces for integration. Authentication applies uniformly across all. [src2, src3]

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Authentication

Oracle ERP Cloud supports four authentication methods for API access. OAuth 2.0 is recommended; Basic Auth remains available but should be avoided for production. [src1, src2]

Token Lifetime Configuration

Access token expiry is MIN(configured_expiry, remaining_session_lifetime). Default session lifetime is 8h (28,800s). Configuring a longer token expiry has no effect beyond the session boundary. [src5]

IDCS to OCI IAM Migration

Oracle migrated all IDCS instances to OCI IAM identity domains (Feb 2022 -- mid 2024). Existing OAuth configurations, client IDs, and certificates continue to work. Admin console moved to OCI Console > Identity & Security > Domains. [src7]

Federation with External Identity Providers

Federation affects interactive (browser-based) authentication only. API-level OAuth flows operate independently. [src7]

Authentication Gotchas

• LBAC blocks integration traffic: If Location-Based Access Control is enabled, you must allowlist integration platform NAT Gateway IPs. 401/403 errors from LBAC look identical to auth failures. [src8]
• MFA can break service accounts: Sign-on policies enforcing MFA for all users break Resource Owner grant for service accounts. Exclude service accounts from MFA rules, or use Client Credentials / JWT flows. [src6]
• Token endpoint varies by domain type: Post-migration, the token endpoint depends on which identity domain your app is in. Verify which domain your confidential app belongs to. [src7]
• Certificate format matters for JWT: JWT assertion requires PEM-format certificates. PKCS12 (.p12/.pfx) must be converted. CA-signed recommended for production. [src4]
• Session lifetime caps token lifetime: Even if you configure a 24h token expiry, the token expires when the session expires (default 8h). Both settings must be aligned. [src5]

Constraints

• Basic Auth credential exposure: Sends Base64-encoded credentials in every request header. Any network intercept or log capture exposes them. Use OAuth 2.0 instead. [src3]
• Token lifetime ceiling: Access tokens cannot exceed the identity domain session lifetime (default 8h). Configuring a longer expiry has no effect beyond the session boundary. [src5]
• LBAC allowlisting required: If LBAC is active, integration platform IPs must be allowlisted or all API calls fail with 401/403. [src8]
• Confidential client registration required: All OAuth flows require registering a confidential application. Public clients cannot access ERP Cloud APIs. [src1]
• MFA exclusion for service accounts: Service accounts must be excluded from MFA sign-on policies if using Resource Owner grant. Client Credentials and JWT flows bypass MFA. [src6]
• Certificate management for JWT: JWT assertion certificates have expiration dates. Oracle does not auto-notify on certificate expiry. Monitor and rotate proactively. [src4]

Integration Pattern Decision Tree

START -- Authenticating with Oracle ERP Cloud
|-- What type of integration?
|   |-- Server-to-server (unattended, scheduled, middleware)
|   |   |-- Can you manage certificates?
|   |   |   |-- YES --> JWT Assertion flow (most secure, no shared secrets)
|   |   |   |-- NO --> OAuth 2.0 Client Credentials (simpler setup)
|   |   |-- Need to act as a specific user?
|   |       |-- YES --> Client Credentials + service user mapping
|   |       |-- NO --> Client Credentials with integration user
|   |-- User-initiated (interactive, delegated access)
|   |   |-- Browser-based UI?
|   |   |   |-- YES --> OAuth 2.0 Authorization Code (3-legged)
|   |   |   |-- NO --> Not recommended; use server-side proxy
|   |   |-- Need SSO with corporate IdP?
|   |       |-- YES --> SAML 2.0 federation + Authorization Code flow
|   |       |-- NO --> Authorization Code with identity domain login
|   |-- Quick test / debugging
|       |-- YES --> Basic Auth (dev/test only, never production)
|       |-- NO --> Use OAuth 2.0
|-- Using Oracle Integration Cloud (OIC)?
|   |-- YES --> OAuth configured automatically via Fusion Apps identity domain
|   |-- NO --> Manual confidential app registration required
|-- LBAC enabled on Fusion Apps?
    |-- YES --> Allowlist integration platform NAT Gateway IPs FIRST
    |-- NO --> Proceed with auth setup

Quick Reference

OAuth 2.0 Token Endpoints

Confidential App Registration Checklist

Step-by-Step Integration Guide

1. Register a Confidential Application in OCI IAM

Create the OAuth client that will authenticate with Oracle ERP Cloud. [src1]

1. Log in to OCI Console > Identity & Security > Domains
2. Select the appropriate identity domain (usually "OracleIdentityCloudService")
3. Click Applications > Add Application > Confidential Application
4. Name the application (e.g., "ERP Integration Client")
5. Under Client Configuration, select the grant types you need
6. Under Resources, add Oracle Fusion Cloud Applications as an allowed scope
7. Record the Client ID and Client Secret
8. Click Activate

Verify: In the Applications list, confirm Status: Active.

2. Obtain an Access Token (Client Credentials)

Exchange client credentials for an access token. [src1, src3]

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. Obtain an Access Token (JWT Assertion)

Use a signed JWT to request a token without sharing a client secret. [src4]

# Generate JWT with claims: iss=CLIENT_ID, sub=CLIENT_ID,
# aud=token_endpoint, exp=now+300, iat=now. Sign with RS256.

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 "token_type": "Bearer". No client secret transmitted.

4. Call an Oracle ERP Cloud REST API

Use the access token to invoke any Fusion Cloud REST endpoint. [src3]

curl -X GET \
  "https://<erp-host>.fa.ocs.oraclecloud.com/fscmRestApi/resources/latest/invoices" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json"

Verify: HTTP 200 with JSON payload. If 401, check token expiry and LBAC allowlisting.

5. Implement Token Refresh

For long-running integrations, refresh the token before expiry. [src5]

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=refresh_token&refresh_token=<REFRESH_TOKEN>"

Verify: New access_token and refresh_token in response.

6. Configure MFA Exclusion for Service Accounts

Ensure integration accounts are not blocked by MFA sign-on policies. [src6]

1. Navigate to OCI Console > Identity & Security > Domains > Security > Sign-on policies
2. Edit the sign-on policy rule that enforces MFA
3. Add exclusion for integration user (by username or group)
4. Or create a dedicated no-MFA rule for service accounts with higher priority

Verify: Service account authenticates via Client Credentials without MFA challenge.

Code Examples

Python: OAuth 2.0 Client Credentials Token Request

# Input:  Oracle ERP Cloud tenant URL, Client ID, Client Secret
# Output: Access token string for API calls

import requests  # requests>=2.31.0

def get_oracle_erp_token(tenant_url, client_id, client_secret):
    """Obtain OAuth 2.0 access token from Oracle OCI IAM."""
    token_url = f"{tenant_url}/oauth2/v1/token"
    response = requests.post(
        token_url,
        auth=(client_id, client_secret),
        data={
            "grant_type": "client_credentials",
            "scope": "urn:opc:resource:consumer::all"
        },
        headers={"Content-Type": "application/x-www-form-urlencoded"},
        timeout=30
    )
    response.raise_for_status()
    return response.json()["access_token"]

Python: JWT Assertion Token Request

# Input:  Private key (PEM), Client ID, Token endpoint
# Output: Access token obtained via JWT assertion

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

def get_oracle_erp_token_jwt(token_endpoint, client_id, private_key_pem):
    """Obtain token using JWT assertion (no shared secret)."""
    now = int(time.time())
    claims = {
        "iss": client_id, "sub": client_id,
        "aud": token_endpoint,
        "iat": now, "exp": now + 300,
    }
    signed_jwt = jwt.encode(claims, private_key_pem, algorithm="RS256")
    response = requests.post(
        token_endpoint,
        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,
    )
    response.raise_for_status()
    return response.json()["access_token"]

JavaScript/Node.js: Client Credentials with Token Caching

// Input:  Oracle tenant URL, Client ID, Client Secret
// Output: Cached access token with automatic refresh

class OracleERPAuth {
  constructor(tenantUrl, clientId, clientSecret) {
    this.tokenUrl = `${tenantUrl}/oauth2/v1/token`;
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.token = null;
    this.expiresAt = 0;
  }
  async getToken() {
    if (this.token && Date.now() < this.expiresAt - 60000) return this.token;
    const credentials = Buffer.from(
      `${this.clientId}:${this.clientSecret}`
    ).toString("base64");
    const response = await fetch(this.tokenUrl, {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        Authorization: `Basic ${credentials}`,
      },
      body: "grant_type=client_credentials&scope=urn:opc:resource:consumer::all",
    });
    if (!response.ok) throw new Error(`Token failed: ${response.status}`);
    const data = await response.json();
    this.token = data.access_token;
    this.expiresAt = Date.now() + data.expires_in * 1000;
    return this.token;
  }
}

cURL: Quick Authentication Test

# Test Client Credentials flow
curl -v -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"

# Expected: {"access_token":"eyJ0eXAiOi...","token_type":"Bearer","expires_in":3600}

# Test token against Fusion REST API
curl -X GET \
  "https://<erp-host>.fa.ocs.oraclecloud.com/fscmRestApi/resources/latest" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Data Mapping

Authentication Credential Mapping

Data Type Gotchas

• Token endpoint URL format varies: IDCS-migrated domains use <tenant>.identity.oraclecloud.com; newer domains may use <region>.identity.oraclecloud.com. [src7]
• Scope URN is Oracle-specific: Unlike standard scopes (openid profile), Oracle uses URN-based scopes. Incorrect scope returns 400 with minimal diagnostics. [src1]
• Base64 encoding for Basic Auth header: client_id:client_secret must be Base64-encoded as a single string. Some HTTP clients handle this automatically. [src3]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Certificate expiry breaks JWT flow silently: Oracle does not send expiry notifications. Fix: Monitor certificate dates; set reminders 30 days before; automate rotation via OCI Certificate Service. [src4]
• LBAC false positives after IP change: Cloud platforms can change NAT Gateway IPs during maintenance. Fix: Use CIDR blocks in LBAC allowlist rather than individual IPs. [src8]
• Sign-on policy changes break integrations: Admin enabling MFA for "all users" includes service accounts. Fix: Dedicated sign-on policy rule for service accounts positioned above MFA rule. [src6]
• Token endpoint URL mismatch after migration: Teams use old IDCS URL while app moved to different domain. Fix: Verify app's identity domain in OCI Console; use token endpoint from domain config. [src7]
• Refresh token silent expiry: Defaults to 7-day lifetime. Monthly batch jobs fail silently. Fix: Request new token each run for infrequent jobs; or increase refresh token lifetime. [src5]

Anti-Patterns

Wrong: Hardcoding Basic Auth credentials in integration code

# BAD -- credentials in every request, exposed in logs
response = requests.get(
    "https://erp.fa.ocs.oraclecloud.com/fscmRestApi/resources/latest/invoices",
    auth=("admin_user", "P@ssw0rd123"),  # Credentials in source code!
)

Correct: Use OAuth 2.0 with credentials from a vault

# GOOD -- token-based auth, credentials from environment/vault
import os
token = get_oracle_erp_token(
    os.environ["ORACLE_TENANT_URL"],
    os.environ["ORACLE_CLIENT_ID"],
    os.environ["ORACLE_CLIENT_SECRET"],
)
response = requests.get(url, headers={"Authorization": f"Bearer {token}"})

Wrong: Requesting a new token for every API call

# BAD -- unnecessary token requests, wastes latency
for invoice_id in invoice_ids:
    token = get_oracle_erp_token(tenant, client_id, secret)  # New token each time!
    response = requests.get(f"{url}/invoices/{invoice_id}",
        headers={"Authorization": f"Bearer {token}"})

Correct: Cache token and reuse until near expiry

# GOOD -- single token reused, refreshed proactively
auth = OracleTokenCache(tenant, client_id, secret)
for invoice_id in invoice_ids:
    token = auth.get_valid_token()  # Cached, auto-refreshes if near expiry
    response = requests.get(f"{url}/invoices/{invoice_id}",
        headers={"Authorization": f"Bearer {token}"})

Wrong: Applying MFA to all users without service account exclusion

-- BAD sign-on policy:
Rule 1: "All Users" --> Require MFA (no exceptions)
-- Service accounts cannot authenticate via OAuth Resource Owner grant

Correct: Separate sign-on policy rule for service accounts

-- GOOD sign-on policy:
Rule 1 (higher priority): "Integration Service Accounts" group --> Allow, no MFA
Rule 2 (lower priority): "All Users" --> Require MFA
-- Service accounts work; human users still require MFA

Common Pitfalls

• Using Resource Owner grant in production: Passes username/password directly, does not support MFA. Fix: Migrate to Client Credentials or JWT Assertion for all production integrations. [src3]
• Not configuring token caching: Each token request adds 200-500ms latency. Fix: Cache tokens with expiry tracking; refresh 60s before expiry. [src5]
• Ignoring LBAC when troubleshooting auth failures: 401/403 from LBAC looks identical to auth failures. Fix: Check LBAC settings first; test from an allowlisted IP to isolate. [src8]
• Wrong identity domain after IDCS migration: Post-migration, tenants have 2+ domains. Wrong domain = valid tokens with no Fusion permissions. Fix: Register apps in domain containing Fusion resource apps (typically "OracleIdentityCloudService"). [src7]
• Not rotating client secrets or certificates: Leaked credentials remain valid indefinitely. Fix: 90-day rotation schedule; use OCI Vault for storage and automation. [src4]
• Assuming sandbox = production identity domain: Each environment has separate identity domains and client registrations. Fix: Maintain separate OAuth client registrations per environment; use env vars to switch. [src2]

Diagnostic Commands

# Test token endpoint connectivity
curl -v -X POST \
  "https://<tenant>.identity.oraclecloud.com/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>"

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

# Test Fusion Cloud API access with token
curl -w "\nHTTP Status: %{http_code}\n" \
  -X GET "https://<erp-host>.fa.ocs.oraclecloud.com/fscmRestApi/resources/latest" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

# Verify identity domain OpenID configuration
curl "https://<tenant>.identity.oraclecloud.com/.well-known/openid-configuration" \
  | python3 -m json.tool

# Check if LBAC is causing auth failures (test from known-good IP)
curl -X GET "https://<erp-host>.fa.ocs.oraclecloud.com/fscmRestApi/resources/latest" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -w "\nHTTP: %{http_code}, Remote IP: %{remote_ip}\n"

Version History & Compatibility

Deprecation Policy: Oracle has not announced a formal deprecation date for Basic Authentication on Fusion Cloud APIs, but all documentation strongly recommends OAuth 2.0. Plan for eventual deprecation. [src1, src2]

When to Use / When Not to Use

Important Caveats

• Oracle does not publish fixed API rate limits for Fusion Cloud. Throttling is adaptive and varies by tenant, pod, and load. HTTP 429 is your only signal. [src3]
• Token lifetime configuration applies per-application within a single identity domain. Different confidential apps can have different lifetimes. [src5]
• Post-IDCS migration, some Oracle documentation still references "IDCS" terminology. Functionality is identical in OCI IAM identity domains. [src7]
• Federation with external IdPs (Azure AD, Okta) affects browser-based SSO only. API-level OAuth flows operate independently. [src7]
• Oracle ERP Cloud environments (production, test, dev) have separate identity domains. OAuth registrations are not portable across environments. [src2]