Skip to content

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”
  1. Navigate to OCI Console → Identity & Security → Domains
  2. Select an existing domain or create a new one
  3. Note the domain URL — you will need it later
  1. In your identity domain, go to Integrated applications → Add application
  2. Select Confidential Application
  3. Configure the application:
    • Name: AgentCube (or your preferred name)
    • Grant types: Enable both:
      • Client Credentials
      • JWT Assertion
  4. Under App roles, assign the Identity Domain Administrator role
  5. Activate the application
  6. Record the Client ID and Client secret

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
  1. Generate the signing key pair if you haven’t already — see Signing Key Generation
  2. In your identity domain, go to Security → Trusted partner certificates
  3. Click Import certificate
  4. Upload the public certificate file (.cer)
  5. Set an alias — for example, agentcube-mcp

Confirm the identity domain supports JWT bearer assertion:

Terminal window
# PowerShell
(Invoke-RestMethod "https://{identity_domain_url}/.well-known/openid-configuration").grant_types_supported
Terminal window
# bash
curl https://{identity_domain_url}/.well-known/openid-configuration

In the response, verify that grant_types_supported includes:

urn:ietf:params:oauth:grant-type:jwt-bearer

Set 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.

  1. 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)
  2. Note your EPM service instance ID
  3. Set OCI_RESOURCE_SCOPE on the Planning or FCCS user-lane connector:
OCI_RESOURCE_SCOPE=urn:opc:serviceInstanceID={service_instance_id}urn:opc:resource:consumer::all

Essbase does not need this. Leave OCI_RESOURCE_SCOPE unset on an Essbase connector.

OCI ValueEnvironment Variable
Confidential app client IDOCI_CLIENT_ID
Confidential app client secretOCI_CLIENT_SECRET
Identity domain base URL (no /oauth2/v1/token suffix)OCI_TOKEN_ENDPOINT
Certificate aliasAGENTCUBE_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.