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:
- Set the Application ID URI to
api://your-client-id(or a custom URI likehttps://api.agenticcontrolplane.com/your-slug) - 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:
- Token type: Access token
- Add these claims:
email: the user’s email addresspreferred_username: the user’s UPNgroups: 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:
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
irm https://agenticcontrolplane.com/install.ps1 | iex