Skip to content
Agentic Control Plane

Set Up ACP with Microsoft Entra ID

Microsoft Entra ID (formerly Azure AD) is the identity provider for most Microsoft 365 organizations. This guide sets up Entra ID to issue tokens that ACP can verify, so every tool call from your agents carries the user’s real identity.

One thing to know up front: ACP checks required scopes against a scope string or a permissions array in the token. It does not read Entra’s scp or roles claims for scope checks. Step 5 explains what that means for your setup.


What you need

  • A Microsoft Entra ID tenant (any tier, Free works)
  • An ACP Cloud workspace (sign up)

Step 1: Register an application

In the Azure portal, go to Microsoft Entra ID → App registrations → New registration.

Field Value
Name ACP Gateway
Supported account types Accounts in this organizational directory only

You don’t need a redirect URI for ACP. ACP only validates tokens, so it never receives a sign-in callback.

After registration, note the Application (client) ID and Directory (tenant) ID.


Step 2: Expose an API

Go to your app’s Expose an API section:

  1. Set the Application ID URI to api://your-client-id (or a custom URI like https://api.agenticcontrolplane.com/your-slug)
  2. Add scopes:
Scope Admin consent display name Who can consent
salesforce.read Read Salesforce data Admins and users
salesforce.write Write Salesforce data Admins only
github.read Read GitHub data Admins and users
github.write Write GitHub data Admins only

Step 3: Define app roles

Go to App roles → Create app role:

Display name Value Allowed member types
Sales Read Only Sales.Read Users/Groups
Sales Full Access Sales.ReadWrite Users/Groups
Developer Developer Users/Groups
Admin Admin Users/Groups

Then go to Enterprise applications → your app → Users and groups to assign users and groups to roles. App roles appear in the roles claim of the token.


Step 4: Configure token claims

Go to Token configuration → Add optional claim:

  1. Token type: Access token
  2. Add these claims:
    • email: the user’s email address
    • preferred_username: the user’s UPN
    • groups: group memberships (if you prefer groups over app roles)

If a user is in many groups, Entra returns a groups overage claim with a Graph API URL instead of the list. App roles don’t have this limit, so prefer them for production.


Step 5: Configure ACP

In your ACP dashboard, go to Settings → Identity Providers and enter:

Field Value
Issuer https://login.microsoftonline.com/{tenant-id}/v2.0
Audience api://your-client-id
JWKS URI https://login.microsoftonline.com/{tenant-id}/discovery/v2.0/keys

Set the JWKS URI yourself. ACP does not run OIDC discovery. If the field is blank, ACP looks for keys at <issuer>/.well-known/jwks.json, and Entra doesn’t serve them there, so tokens would fail to verify.

There are no claim-mapping fields.

What ACP reads from an Entra token

Entra claim What ACP does with it
sub Identifies the user on every log row
iss, aud Must match the issuer and audience you entered above
scope string or permissions array Checked against a tool’s required scopes
scp Not used for scope checks
roles Not used for scope checks. Available to ABAC rule conditions
tid Not used

Entra puts delegated scopes in scp, which ACP does not read for scope enforcement. Scope checks only pass if the token carries a scope string or a permissions array. Until your tokens do, use ABAC rules on roles to control who can call what.


Step 6: Configure tool scopes

In Policies → Tool Scopes, map scopes to tools:

{
  "salesforce.query": ["salesforce.read"],
  "salesforce.createRecord": ["salesforce.write"],
  "github.listRepos": ["github.read"],
  "github.createIssue": ["github.write"]
}

If a token lacks a required scope, the call is rejected with a JSON-RPC error, code -32004 Insufficient scope. The error.data field lists the required, have and missing scopes.


Multiple Entra tenants

Entra includes a tid (tenant ID) claim in every token, but ACP does not use it.

Separation is by workspace. A token must carry your workspace’s configured issuer and audience to be accepted, and a workspace has one issuer. If you have several Entra tenants, they need separate ACP workspaces.


Troubleshooting

“Invalid token: unexpected iss claim” Entra v2.0 tokens use https://login.microsoftonline.com/{tenant-id}/v2.0 as the issuer. v1.0 tokens use https://sts.windows.net/{tenant-id}/. Your ACP issuer must match the version your app issues.

“Insufficient scope” ACP didn’t find the required scope in the token’s scope string or permissions array. Entra’s scp claim doesn’t count (see Step 5).

Tokens fail to verify Check that the JWKS URI is set to the Entra keys URL from Step 5.

“roles claim missing” App roles must be assigned to users or groups in the Enterprise Application blade. A user with no assignments gets no roles claim.

“groups claim returns a URL instead of groups” You’ve hit the groups overage limit (about 200 groups). Switch to app roles, or use the Graph API URL in _claim_sources to fetch the groups.


Back to guides · Set up Okta → · Set up Auth0 →

Running coding agents? ACP records each tool call its hook sees and makes the dangerous shell commands (a force-push, destructive SQL, curl | sh) wait for you. One command, free up to 5 agents:

macOS · Linux · WSL
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
Windows · PowerShell
irm https://agenticcontrolplane.com/install.ps1 | iex

What the installer writes  ·  Getting started