Skip to content

Entra ID to OCI Federation

This guide covers establishing federated SSO between Microsoft Entra ID and an OCI Identity Domain for AgentCube SSO deployments. This is required when your users authenticate via Entra and your data sources are hosted on Oracle Cloud Infrastructure.

Time estimate

The complete setup takes approximately 60–90 minutes for an experienced administrator on the first deployment. Subsequent deployments are faster since the Entra app registration is reusable.

Prerequisites

  • Entra ID: Global Administrator or Application Administrator role
  • OCI: Identity Domain Administrator privileges
  • AgentCube: Connector deployed with a public HTTPS URL
  • OpenSSL: Installed locally for certificate generation

SAML Federation (Optional)

SAML federation enables browser-based SSO login to Oracle applications (Essbase Web UI, Planning Web UI) using Entra credentials. This is separate from the JWT assertion flow used by AgentCube and is optional.

If your organization also wants browser-based Oracle login via Entra:

Configure Entra as a SAML IdP in OCI

  1. In the OCI Identity Domain, go to the Federation tab
  2. Click + Add Identity Provider → Add SAML IdP
  3. Name: A descriptive name for this federation (e.g., Corporate SSO)
  4. Upload the Entra Federation Metadata XML
    • Download from: Entra → Enterprise Applications → your app → Single sign-on → Federation Metadata XML link

Configure User Mapping

Under the IdP's User mapping section:

Setting Value
Requested Name ID format Email address
Identity provider user attribute SAML assertion Name ID
Maps to (Identity domain user attribute) Username

This ensures Entra sends the user's email as the Name ID, and OCI maps it to the username field.

  1. Activate the IdP
  2. Test by navigating to the Oracle application login page and selecting the federated IdP option

Note

SAML federation and the AgentCube JWT assertion flow coexist independently. SAML uses Entra's SAML signing certificate, while the JWT assertion flow uses AgentCube's own signing certificate. These are different trust relationships.

Enterprise App Assignments

If your Entra app registrations have Assignment required set to Yes, each user must be explicitly assigned to both applications:

  1. AgentCube MCP app: Enterprise Applications → AgentCube MCP → Users and groups → Add user/group
  2. OCI Identity Domain app (if SAML federation is configured): Enterprise Applications → OCI Identity Domain → Users and groups → Add the same users/groups

Both assignments are required

The AgentCube MCP app controls access to the connector (Layer 1). The OCI Identity Domain app controls access to Oracle (SAML federation). Missing either one blocks the user.

Deployment Checklist

Use this checklist for each new SSO deployment:

Entra ID

  • [ ] App registration created with single-tenant access
  • [ ] Client secret generated and stored securely
  • [ ] Redirect URI(s) added for all connector URLs
  • [ ] Application ID URI set to connector's public URL
  • [ ] Custom scope (access) created under Expose an API
  • [ ] Token version set to 2 in the manifest
  • [ ] Admin consent granted for the organization
  • [ ] User assignments completed (if assignment-required is enabled)

OCI Identity Domain

  • [ ] Confidential application created with JWT Assertion and Client Credentials grant types
  • [ ] Identity Domain Administrator app role assigned to the confidential app
  • [ ] Application activated
  • [ ] AgentCube signing certificate imported with known alias
  • [ ] Users provisioned with usernames matching Entra email/UPN
  • [ ] Users assigned to appropriate groups for application access

AgentCube Connector

  • [ ] All Layer 1 and Layer 2 environment variables set
  • [ ] AGENTCUBE_AUTH_MODE set to oidc
  • [ ] Health endpoint confirms auth_mode: oidc
  • [ ] Container deployed and accessible via public URL

Validation

  • [ ] Admin user can connect, complete Entra login, and execute tool calls
  • [ ] Tool calls return data scoped to the authenticated user's security profile
  • [ ] A second user with different permissions sees different data through the same connector

Common Errors

Error Cause Fix
AADSTS9010010: resource parameter doesn't match scopes Entra Application ID URI does not match the connector's public URL Change Application ID URI under Expose an API to match the connector URL
AADSTS7000215: Invalid client secret Using the Secret ID instead of the Secret Value, or secret has expired Copy the Value (not ID); generate new if expired
OCI: Certificate does not exist in key store Signing certificate not imported, or alias mismatch Import .cer to Trusted partner certificates; verify alias matches AGENTCUBE_SIGNING_KID
OCI: invalid_grant — user name invalid JWT subject does not match any OCI username Create user in OCI with username matching the email/UPN from Entra
OCI: invalid_client — client auth failed OCI confidential app credentials incorrect Verify OCI_CLIENT_ID and OCI_CLIENT_SECRET
User blocked: not a member of a group with access Enterprise app assignment required but user not assigned Add user to both AgentCube MCP and OCI Identity Domain enterprise apps in Entra