Skip to content

Microsoft Entra ID Setup

This guide walks through registering AgentCube as an application in Microsoft Entra ID (formerly Azure AD). You register one application; its redirect URI points at the Context Engine, which is the single endpoint the AI platform authenticates against.

  1. Navigate to Azure Portal → Microsoft Entra ID → App registrations
  2. Click New registration
  3. Configure:
    • Name: AgentCube MCP (or your preferred name)
    • Supported account types: Accounts in this organizational directory only (Single tenant)
    • Redirect URI: Select Web and enter the Context Engine’s callback URL:
      https://{ce_hostname}/auth/callback
  4. Click Register
  1. Go to Certificates & secrets → Client secrets
  2. Click New client secret
  3. Set a description and expiration period
  4. Click Add
  5. Copy the secret VALUE immediately — it will not be shown again
  1. Go to Expose an API
  2. Click Set next to Application ID URI — accept the default api://{client_id}
  3. Click Add a scope:
    • Scope name: access
    • Who can consent: Admins and users
    • Admin consent display name: Access AgentCube
    • Admin consent description: Allow the application to access AgentCube on behalf of the signed-in user
  4. Click Add scope
  1. Go to Manifest
  2. Find "requestedAccessTokenVersion" (it will be null by default)
  3. Change null to 2
  4. Click Save

You need three values from the app registration:

Entra ValueEnvironment Variable
Application (client) IDAGENTCUBE_CE_OIDC_CLIENT_ID
Client secret VALUEAGENTCUBE_CE_OIDC_CLIENT_SECRET
Directory (tenant) IDAGENTCUBE_CE_OIDC_TENANT_ID

These values are found on the app registration Overview page (client ID, tenant ID) and in Certificates & secrets (secret value).

Under the default AGENTCUBE_CE_AUTH_MODE=basic, the Context Engine refuses to start if any AGENTCUBE_CE_OIDC_* variable is set (to require sign-in, see Single Sign-On). To turn on Entra sign-in, set all six variables on the Context Engine:

AGENTCUBE_CE_AUTH_MODE=oidc
AGENTCUBE_CE_OIDC_PROVIDER=azure
AGENTCUBE_CE_OIDC_TENANT_ID={tenant_id}
AGENTCUBE_CE_OIDC_CLIENT_ID={client_id}
AGENTCUBE_CE_OIDC_CLIENT_SECRET={client_secret}
AGENTCUBE_CE_OIDC_BASE_URL=https://{ce_hostname}

AGENTCUBE_CE_OIDC_BASE_URL is the Context Engine’s public HTTPS URL. Its host must match the host in the redirect URI you entered in Step 1.

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.