OCI Identity Domain Setup
The OCI Identity Domain enables AgentCube to exchange user identities for Oracle-scoped access tokens. This is required for SSO deployments regardless of which identity provider you use. In the Context Engine model this exchange is Layer 2 and runs in the connector: the Context Engine validates the inbound user identity at its edge (Layer 1), then the connector exchanges that identity here for an Oracle-scoped token.
Step 1: Create or Identify Your Identity Domain
Section titled “Step 1: Create or Identify Your Identity Domain”- Navigate to OCI Console → Identity & Security → Domains
- Select an existing domain or create a new one
- Note the domain URL — you will need it later
Step 2: Create a Confidential Application
Section titled “Step 2: Create a Confidential Application”- In your identity domain, go to Integrated applications → Add application
- Select Confidential Application
- Configure the application:
- Name:
AgentCube(or your preferred name) - Grant types: Enable both:
- Client Credentials
- JWT Assertion
- Name:
- Under App roles, assign the Identity Domain Administrator role
- Activate the application
- Record the Client ID and Client secret
Step 3: Create Users
Section titled “Step 3: Create Users”Users must exist in the OCI Identity Domain with usernames that match their corporate email addresses.
For example, if a user authenticates via Entra as [email protected], a user must exist in the identity domain with username [email protected].
Users can be created:
- Manually — Identity Domain → Users → Create user
- SAML JIT provisioning — Automatically on first login via federated SAML
- Directory sync — Automated synchronization from your corporate directory
Step 4: Import the Signing Certificate
Section titled “Step 4: Import the Signing Certificate”- Generate the signing key pair if you haven’t already — see Signing Key Generation
- In your identity domain, go to Security → Trusted partner certificates
- Click Import certificate
- Upload the public certificate file (
.cer) - Set an alias — for example,
agentcube-mcp
Step 5: Verify OIDC Discovery
Section titled “Step 5: Verify OIDC Discovery”Confirm the identity domain supports JWT bearer assertion:
# PowerShell(Invoke-RestMethod "https://{identity_domain_url}/.well-known/openid-configuration").grant_types_supported# bashcurl https://{identity_domain_url}/.well-known/openid-configurationIn the response, verify that grant_types_supported includes:
urn:ietf:params:oauth:grant-type:jwt-bearerSet OCI_TOKEN_ENDPOINT to the identity domain base URL: the token_endpoint with /oauth2/v1/token removed (for example https://idcs-{guid}.identity.oraclecloud.com:443). AgentCube appends the token path itself, so pasting the full token_endpoint breaks every token exchange.
Step 6: Scope Tokens to Your EPM Service (Planning and FCCS only)
Section titled “Step 6: Scope Tokens to Your EPM Service (Planning and FCCS only)”Oracle’s EPM Cloud business processes (Planning, FCCS) validate that an access token carries the target service’s audience. With the default wildcard scope (urn:opc:idm:__myscopes__), the token exchange succeeds but the Planning or FCCS REST API rejects the token with 401.
- Configure your identity domain and EPM environment for resource-specific OAuth 2 scopes, following Oracle’s EPM Cloud OAuth 2 documentation (the confidential app must be allowed to request a scope for your EPM service instance)
- Note your EPM service instance ID
- Set
OCI_RESOURCE_SCOPEon the Planning or FCCS user-lane connector:
OCI_RESOURCE_SCOPE=urn:opc:serviceInstanceID={service_instance_id}urn:opc:resource:consumer::allEssbase does not need this. Leave OCI_RESOURCE_SCOPE unset on an Essbase connector.
Configuration Values
Section titled “Configuration Values”| OCI Value | Environment Variable |
|---|---|
| Confidential app client ID | OCI_CLIENT_ID |
| Confidential app client secret | OCI_CLIENT_SECRET |
Identity domain base URL (no /oauth2/v1/token suffix) | OCI_TOKEN_ENDPOINT |
| Certificate alias | AGENTCUBE_SIGNING_KID |
| Signing private key (from Signing Key Generation) | AGENTCUBE_SIGNING_KEY_BASE64 (or AGENTCUBE_SIGNING_KEY_PATH) |
| EPM resource scope (Planning/FCCS only; leave unset for Essbase) | OCI_RESOURCE_SCOPE |
Give each connector its own token audience
Section titled “Give each connector its own token audience”The Context Engine signs a token for every call it makes to a connector in internal mode. Give each connector its own audience, set the same value as that connector’s AGENTCUBE_INTERNAL_AUDIENCE, and a token made for one connector is refused by the others. A connector with no audience of its own receives tokens with the audience shared by every internal connector, and the Context Engine flags it as shared. The steps, including how to move a running connector without downtime, are in Upgrades.
Next Steps
Section titled “Next Steps”- Generate the signing key (if you haven’t already)
- Deploy the container
- Configure environment variables