Set Up ACP with Okta
This guide sets up an Okta authorization server to issue tokens that ACP can verify, so every tool call carries the user’s identity.
One thing to know up front: ACP reads a scope string or a permissions array from the token. It does not read Okta’s scp or groups claims for scope checks. Step 5 covers what to do about that.
What you need
- An Okta organization (developer or production)
- An ACP Cloud workspace (sign up)
Step 1: Create an authorization server
In the Okta Admin Console, go to Security → API → Authorization Servers.
You can use the default authorization server or create a custom one:
| Field | Value |
|---|---|
| Name | ACP Gateway |
| Audience | https://api.agenticcontrolplane.com/your-slug |
| Description | Authorization server for ACP-governed tools |
The audience must match what you enter in ACP. It appears as the aud claim in every token.
Step 2: Add scopes
Under your authorization server, go to Scopes → Add Scope. Create scopes for each tool category:
salesforce:read
salesforce:write
github:read
github:write
slack:read
slack:write
For each scope:
- Name: the scope string (for example
salesforce:read) - Include in public metadata: Yes
- Default scope: No (require an explicit request)
Step 3: Create access policies
Go to Access Policies → Add Policy on your authorization server. Create a policy that applies to your application, then add rules:
| Rule | Scopes | Groups |
|---|---|---|
| Sales Read | salesforce:read |
Sales Team |
| Sales Full | salesforce:read, salesforce:write |
Sales Managers |
| Dev Access | github:read, github:write, slack:read |
Engineering |
| Admin | All scopes | IT Admins |
Rules decide which scopes a user can request, based on their group.
Step 4: Add a groups claim (optional)
Okta doesn’t put groups in access tokens by default. ACP does not use groups for scope checks, but it is handy to have in the token for your own records. To add it:
- Go to your authorization server’s Claims tab
- Click Add Claim
| Field | Value |
|---|---|
| Name | groups |
| Include in token type | Access Token |
| Value type | Groups |
| Filter | Matches regex .* (or filter to specific groups) |
| Include in | Any scope |
Step 5: Configure ACP
In your ACP dashboard, go to Settings → Identity Providers and enter:
| Field | Value |
|---|---|
| Issuer | https://your-org.okta.com/oauth2/your-auth-server-id |
| Audience | https://api.agenticcontrolplane.com/your-slug |
| JWKS URI | https://your-org.okta.com/oauth2/your-auth-server-id/v1/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 Okta doesn’t serve them there, so tokens would fail to verify.
There are no claim-mapping fields.
What ACP reads from an Okta token
| Okta 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 (space-separated string) |
Checked against a tool’s required scopes |
permissions array |
Checked against a tool’s required scopes |
scp |
Not read |
groups |
Not used for scope checks |
Okta puts scopes in an scp array, which ACP does not read. Scope checks only pass if the token carries a scope string or a permissions array. To get one, add a custom claim named scope or permissions to your authorization server that carries the granted scopes.
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"]
}
When a user calls a tool, ACP checks the token’s scope string and permissions array against the required scopes. If a scope is missing, 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 organizations
ACP does not read a tenant claim. Separation is by workspace: a token must carry your workspace’s configured issuer and audience to be accepted.
If a token has an org_id claim, ACP passes it to your ABAC rules. You can write a rule that allows or blocks a tool based on it.
Troubleshooting
“Invalid token: unexpected iss claim”
Okta authorization server URLs include the server ID, like https://your-org.okta.com/oauth2/aus1234567. The issuer in ACP must match exactly, including whether you use the default server (/oauth2/default) or a custom one.
Tokens fail to verify
Check that the JWKS URI is set to <issuer>/v1/keys (Step 5).
“Insufficient scope”
ACP didn’t find the required scope in the token’s scope string or permissions array. Also check that the scope exists on the authorization server, that an access policy rule grants it to the user’s group, and that the client requests it at sign-in.
“Token expired” Okta’s default access token lifetime is 1 hour. You can change it in your access policy rules under Token Lifetime.
Back to guides · Set up Auth0 → · Set up Entra ID →
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