Solution Patterns¶

Location: inception_core/accelerators/patterns_solution/

Solution patterns are enterprise-grade reference implementations covering identity propagation, secure token exchange, and Oracle Fusion integration. Each pattern is a self-contained, runnable starting point — copy, extend, and adapt to your domain without rebuilding the foundation.

Overview¶

Pattern	Folder	Description
User Login & Token Acquisition	`user_login_get_token/`	FastAPI + IDCS OAuth 2.0 Authorization Code flow with browser UI
Service Token Acquisition (OCI API Key)	`service_get_token/`	Headless OCI API-key signed token exchange for server-to-server and CLI flows
E2E Identity Propagation → ADB	`user_e2e_token_exchange_adb/`	Full-stack SSO token propagation: Browser → FastAPI → MCP → ADW
E2E Identity Propagation → Object Storage	`user_e2e_token_exchange_os/`	Same propagation chain targeting OCI Object Storage via `mcp_os`
E2E Identity Propagation → OIC	`user_e2e_token_exchange_oic/`	Same propagation chain targeting Oracle Integration Cloud
User Impersonation → ADB	`user_impersonation_adb/`	Delegate a user's IDCS identity to make DB calls on their behalf
User Impersonation → OIC	`user_impersonation_oic/`	Delegate a user's IDCS identity to invoke OIC workflows on their behalf
Async Fusion Agent Invocation	`async_invoke_fusion_agents/`	Async `invokeAsync` + polling client for Oracle Fusion AI Agent workflows
A2A Service Invocation	`a2a_invoke_services/`	Agent-to-agent service calls with OAuth credentials

Folder: user_login_get_token/

A minimal FastAPI application that handles IDCS OAuth 2.0 Authorization Code flow. A user visits the UI, authenticates via IDCS SSO, and receives an access token the frontend can use for downstream API calls.

Key files: - fastapi_login.py — login and logout route handlers - ui.html — single-file frontend UI

When to use: Any scenario where a human user needs to authenticate before the agent can act on their behalf.

Pattern 2 — Service Token Acquisition (OCI API Key)¶

Folder: service_get_token/

A self-contained library and CLI example for headless token acquisition using OCI API key signing (HTTP Signature / RFC 8693 token exchange). No browser, no client secret — the service authenticates with its OCI API key (RSA-SHA256) and exchanges it for a short-lived IDCS Bearer token.

Service (OCI API key) ──► IDCS token endpoint (signed POST) ──► Bearer token ──► MCP server

Key files: - src/agent_get_token/client.py — AgentTokenClient class (importable library) - examples/api_key_to_iam_token.py — CLI example reading from .env

Python usage:

from agent_get_token import AgentTokenClient

client = AgentTokenClient(
    token_url="https://<domain>.identity.oraclecloud.com/oauth2/v1/token",
    tenancy_ocid=OCI_IDENTITY_TENANCY_OCID,
    user_ocid=OCI_IDENTITY_USER_OCID,
    fingerprint=OCI_IDENTITY_FINGERPRINT,
    private_key_file="~/.oci/oci_api_key.pem",
    scope="urn:opc:idm:__myscopes__",
)
token = client.get_access_token()          # Bearer token string
header = client.get_auth_header()          # "Bearer eyJ..."

Required .env keys:

OCI_IDENTITY_TOKEN_URL=https://<domain>.identity.oraclecloud.com/oauth2/v1/token
OCI_IDENTITY_TENANCY_OCID=ocid1.tenancy.oc1..
OCI_IDENTITY_USER_OCID=ocid1.user.oc1..
OCI_IDENTITY_FINGERPRINT=xx:xx:xx:..
OCI_IDENTITY_PRIVATE_KEY_FILE=~/.oci/oci_api_key.pem

How it differs from client_credentials:

Aspect	`client_credentials`	OCI API key exchange
Authentication	Client ID + Secret	RSA-SHA256 signed request
Credential type	Symmetric (secret)	Asymmetric (private key)
Credential rotation	Secret rotation required	Key rotation via OCI IAM
Use case	Service accounts with IDCS app	OCI principals (users/instances)

When to use: CLI agents, background jobs, Node.js API gateways, or any non-interactive service that is an OCI principal and needs a short-lived MCP Bearer token without storing a client secret.

Used by the Smart Dispatch Node.js gateway and CLI to authenticate to the MCP SQLcl server without browser interaction.

Pattern 3 — End-to-End Identity Propagation → ADB¶

Folder: user_e2e_token_exchange_adb/

The most complete identity propagation reference in the platform. Demonstrates the full chain:

End User → React UI → API Gateway (IDCS SSO) → FastAPI Backend → MCP Tool → Token Exchange → ADW (Row-Level Security)

The user's IDCS token is validated at the API Gateway, injected into request headers, passed through FastAPI to the MCP tool, exchanged for a short-lived DB token, and used to connect to ADW — preserving the user's identity for Virtual Private Database (VPD) row-level security enforcement.

Key files: - src/ — React frontend, FastAPI backend, MCP ADW server, VPD setup SQL - sample.env — all required configuration keys with descriptions - IAM-Arch.png — architecture diagram

Tech stack: React + Vite, FastAPI, FastMCP, OCI IDCS, Oracle ADW, Oracle VPD

When to use: Any enterprise application requiring auditable, user-specific data access through a multi-tier stack.

See API Gateway Setup for detailed OCI API Gateway deployment steps.

Pattern 4 — End-to-End Identity Propagation → Object Storage¶

Folder: user_e2e_token_exchange_os/

Same end-to-end propagation model as Pattern 3, targeting OCI Object Storage instead of ADW. The user's IDCS token is validated by the MCP Object Storage server and exchanged for an OCI TokenExchangeSigner via TokenFactory to perform signed Object Storage API calls on behalf of the user.

Browser → FastAPI (port 8000) → MCP OS server (port 3002) → OCI Object Storage
              IDCS OAuth2            OCITokenAuthMiddleware
                                     TokenFactory('oci-service')

MCP tools exposed:

Tool	Description
`get_os_namespace`	Get Object Storage namespace for a region
`list_objects`	List objects in a bucket
`upload_object_remote`	Upload text content as an object
`delete_object`	Delete an object
`whoami`	Return authenticated user identity

Differences from ADB pattern:

Aspect	ADB	Object Storage
MCP server	`mcp_adw` `:8003`	`mcp_os` `:3002`
TokenFactory target	`oracle-database`	`oci-service`
Return type	DB token + private key	OCI `TokenExchangeSigner`
OCI SDK client	ADW thin driver	`ObjectStorageClient`

When to use: Applications that read or write OCI Object Storage on behalf of a human user and need the storage operations attributed to that user's identity for audit.

Pattern 5 — End-to-End Identity Propagation → OIC¶

Folder: user_e2e_token_exchange_oic/

Same end-to-end propagation model as Pattern 3, but targeting Oracle Integration Cloud (OIC) instead of ADW. The user's IDCS token is propagated through the stack to authorize OIC workflow invocations on their behalf.

When to use: Applications that trigger OIC integration workflows and need the invoking user's identity to flow through for audit or access control.

Pattern 6 — User Impersonation → ADB¶

Folder: user_impersonation_adb/

Demonstrates delegated access: an agent or service uses an IDCS access token to impersonate the end user when querying ADW. The DB connection is opened under the user's mapped identity, enabling VPD and audit policies to apply correctly.

Key files: - src/common/ — shared token exchange and DB connection utilities

When to use: Scenarios where a backend service needs to query the DB as the authenticated user rather than a shared service account — critical for compliance and row-level security.

Pattern 7 — User Impersonation → OIC¶

Folder: user_impersonation_oic/

Mirrors Pattern 5 for Oracle Integration Cloud. The agent impersonates the end user when invoking OIC REST APIs, so OIC workflows run under the correct principal for role-based access and audit trails.

When to use: OIC integrations where workflow execution must be attributed to a specific user identity.

Pattern 8 — Async Fusion Agent Invocation¶

Folder: async_invoke_fusion_agents/

A CLI and library for invoking Oracle Fusion AI Agent workflows asynchronously. The client:

Fetches an OAuth 2.0 token via IDCS Client Credentials
Calls /invokeAsync to submit the workflow
Polls /status/{jobId} until a terminal state is reached

Client → IDCS (token) → Fusion /invokeAsync → jobId
                                    ↓ poll
                         /status/{jobId} → COMPLETE / FAILED

Key files: - src/ping_fusion_agents.py — main orchestration logic - src/config/settings.py — environment-driven configuration

When to use: Any integration with Oracle Fusion AI Agents where fire-and-poll is preferable to synchronous blocking calls.

Pattern 9 — Agent-to-Agent (A2A) Service Invocation¶

Folder: a2a_invoke_services/

A reference skeleton for agent-to-agent (A2A) calls — one agent invoking another agent's API endpoint using OAuth credentials. Covers token acquisition and authenticated HTTP invocation.

When to use: Multi-agent architectures where a coordinator agent needs to delegate subtasks to specialized downstream agents over HTTP.

Common Setup¶

All patterns read credentials from environment variables. Copy sample.env (where present) to .env and fill in your OCI-specific values before running.

Shared prerequisites:

OCI tenancy with IDCS configured
Python 3.13+
A virtual environment per pattern: python3.13 -m venv venv && source venv/bin/activate
Dependencies: pip install -r requirements.txt

For patterns targeting ADW, an Oracle Wallet is required. See the Getting Started — Core Setup guide for ADB wallet configuration.

Agentic Accelerators — the 7 canonical agent design patterns
MCP Servers — tool execution layer these patterns invoke
Architecture — how identity propagation fits in the platform stack