Skip to content
Agentic Control Plane

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:

  1. Go to your authorization server’s Claims tab
  2. 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:

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