Okta Integration

Connect your Okta organization to Capsule Security to enrich user identities with directory profile and group membership data, and to link the AI agent identities registered in Okta to the agents in your inventory.

Okta is an identity provider (IdP) integration. Unlike platform integrations that discover AI agents and conversations, the Okta integration enriches user context - pulling profile attributes (email, title, department, manager) and group memberships from your Okta directory. Capsule reconciles this data against unified identities so that activity from other connected platforms is attributed to the right person and team.

If your org uses Okta for AI Agents, Capsule also reads the AI agents registered in Okta's Universal Directory and links each one to the matching agent your other integrations discover.

The integration uses OAuth 2.0 service-to-service authentication with a signed JWT client assertion and DPoP (Demonstrating Proof-of-Possession) - no shared client secret is exchanged.

• Users - Active workspace members with profile attributes (login, email, first/last name, display name, title, department, manager)
• Group memberships - Groups each user belongs to (used for role and team attribution)
• AI agent identities - AI agents registered in Okta for AI Agents, linked to the agents your other integrations discover (optional, see AI agent identities)

Before you begin, ensure you have:

• An Okta tenant with an Okta admin role that can create OAuth service apps
• Permission to register a public key on an Okta service app
• Your Okta domain (e.g., your-org.okta.com)
• Optional, for AI agent identities: an Okta for AI Agents subscription, and an admin role for the service app that covers AI agents (see Step 2)

The installation has three steps and happens entirely in the Capsule portal alongside the Okta admin console:

1. Copy the public key generated by Capsule
2. Create an OAuth service app in Okta and register the public key
3. Enter your credentials (Okta domain + Client ID) in Capsule

Capsule generates a unique RSA key pair scoped to your tenant. The private key never leaves Capsule's Secret Manager - only the public key (in JWK format) is shown to you.

1. Go to Integrations in the Capsule portal

2. Find Okta and click Install

3. Capsule will generate an RSA key pair and display the public key (JWK) in the installation card under Step 1

4. Click the copy button next to the JWK to copy the full public key to your clipboard

Keep the Capsule installation card open. You'll come back to it in Step 3 to enter your Okta domain and Client ID.

Create an API Services OAuth app in Okta and register Capsule's public key on it.

1. Sign in to your Okta Admin Console as an admin

2. Go to Applications → Applications, then click Create App Integration

3. Select API Services as the sign-in method, then click Next

4. Give the app a descriptive name (e.g., Capsule Security) and click Save

5. On the new app's General tab:

   a. Under Client Credentials, change Client authentication to Public key / Private key

   b. Under Public Keys, click Add key → Add

   c. Paste the JWK you copied from Capsule into the JWK field

   d. Click Save

   e. Note the Client ID displayed at the top of the General tab - you'll need this for Step 3

6. Switch to the Okta API Scopes tab

7. Find each of the following scopes in the list and click Grant:

   • okta.users.read - users and their profile attributes, plus per-user group memberships via /users/{id}/groups
   • okta.groups.read - group directory data
   • okta.aiAgents.read - AI agent identities registered in Okta (Okta for AI Agents).

   All three scopes are read-only. Capsule never requests manage scopes and cannot modify anything in your Okta org.

8. On this service app, switch to the Admin roles tab, click Edit assignments, select the Read-only Administrator role, then click Save Changes and complete Okta's re-authentication prompt

   This step is required, and the role must be assigned to this service app. A role on your own admin account, or on a different app, does not apply to Capsule's requests. Okta gates Management API access twice: scopes decide which endpoints the token may call, and the admin role decides which resources it may see. Without a role, group listings fail with 403 and user listings return an empty result with no error, so Capsule ingests nothing.

   AI agent identities need a role that covers AI agents. Okta's API reference lists only Super Administrator for the AI Agents endpoints; Read-only Administrator is not listed, and Okta documents no read-only permission for AI agents. If the assigned role doesn't cover AI agents, Okta rejects the AI agent read with 403 and Capsule syncs users and groups only. A broader role doesn't widen what Capsule can do: the access token is still limited to the read-only scopes above.

For detailed Okta documentation on this flow, see the Okta OAuth Setup Guide.

Return to the Capsule installation card and provide the values from your Okta service app.

1. Back in the Capsule portal Okta installation card, fill in Step 3:

   • Okta Domain - Enter your Okta domain without a scheme (e.g., your-org.okta.com). This is the domain you use to sign in to Okta.
   • Client ID - Paste the Client ID from your Okta service app's General tab.

2. Capsule automatically tests the connection as you fill in the fields:

   • It signs a JWT client assertion with the private key, exchanges it for a DPoP-bound access token at https://<your-domain>/oauth2/v1/token, and calls /api/v1/users?limit=1 to verify the token works.
   • You'll see Connection successful when the credentials are valid.

3. Click Save to finish the installation

The integration status should now show as Connected and Capsule will begin its first sync.

After installation, Capsule begins ingesting users and their group memberships.

1. The first sync may take a few minutes depending on directory size - Capsule paginates the /users endpoint at 200 users per page and fetches group memberships per user.

2. Once complete, Okta-sourced attributes (email, title, department, manager, groups) appear on user profiles in the Users view and are used to attribute activity from other connected platforms.

3. If your org uses Okta for AI Agents, linked AI agent identities appear on the Configuration tab of the matching agent in Inventory.

When the org is subscribed to Okta for AI Agents and the service app holds okta.aiAgents.read, each sync also reads the AI agents registered in Okta from /workload-principals/api/v1/ai-agents: each agent's Okta ID, name, status, and creation and last-updated dates.

This part of the sync is optional. If Okta rejects the request (no Okta for AI Agents subscription, missing scope, or an admin role that doesn't cover AI agents), Capsule skips AI agents for that run, keeps any agent identities it already stored, and syncs users as usual.

Okta's AI agent status maps to the identity status in Capsule:

Capsule links an Okta AI agent to an agent in your inventory by display name: the agent's name must match the Okta AI agent's name (case-insensitive). The portal labels these matches Inferred by name, because a display name is not a unique key. If two agents in your inventory share the name, Capsule links neither.

A linked identity appears in the portal under Inventory > agent > Configuration > Identity.

The Okta for AI Agents API is a Beta release from Okta. Its behavior may change as Okta evolves it.

Cause: The token exchange returned 401 invalid_client. This usually means the Client ID is wrong, the public key in the Okta service app doesn't match Capsule's private key, or the public key was removed.

Solution:

1. Verify the Client ID field in Capsule matches the Client ID on the Okta service app's General tab exactly
2. In Okta, open the service app → General → Public Keys and confirm a JWK is registered
3. If the JWK is missing or stale, re-paste the JWK from the Capsule installation card and click Save
4. Click the retry icon next to the Okta Domain field in Capsule to re-test

Cause: The token exchange returned 403. The OAuth service app exists but is missing one or more of the required scopes. A missing admin role does not fail the token exchange; see No Users Appear After Installation.

Solution:

1. In Okta, open the service app → Okta API Scopes
2. For each of okta.users.read, okta.groups.read, and okta.aiAgents.read, click Grant if it shows Grant instead of Revoke
3. Open the Admin roles tab and confirm Read-only Administrator is assigned to the service app - granting scopes alone is not sufficient
4. Retry the connection in Capsule

Cause: The Okta domain is unreachable, malformed, or the token endpoint returned an unexpected error.

Solution:

1. Confirm the Okta Domain is the bare host (e.g., your-org.okta.com) - no https:// prefix, no path
2. Try opening https://<your-domain>/oauth2/v1/token in a browser to confirm the host resolves (you'll see a method-not-allowed response - that's expected)
3. If your tenant uses a custom domain, use the custom domain consistently in both Okta and Capsule

Possible causes:

1. No admin role on the service app - Okta returns an empty user list, not an error, when the app has the scopes but no admin role that can see users, so the sync completes with nothing to ingest. Open the service app whose Client ID matches the one in Capsule, go to Admin roles, and confirm Read-only Administrator (or a custom role covering all users and groups) is assigned to the app itself. Users appear on the next sync; no reinstall is needed.
2. First sync still in progress - Wait a few minutes for the initial pagination to complete
3. No active users - Capsule fetches users from /api/v1/users; deactivated users are not surfaced
4. Service app scope was revoked after installation - Re-grant the required scopes and trigger a sync

Possible causes:

1. Okta for AI Agents is not available - Capsule reads AI agents only when the org is subscribed to Okta for AI Agents and the service app holds okta.aiAgents.read. Check the service app's Okta API Scopes tab.
2. Admin role doesn't cover AI agents - Read-only Administrator is enough for users and groups, but Okta's API reference lists only Super Administrator for the AI Agents endpoints. See the admin role note in Step 2.
3. Names don't match - Capsule links by display name only. An agent whose name differs from its Okta AI agent name won't be linked; rename one to align them.
4. Duplicate names - If more than one agent in your inventory has the same name, Capsule can't tell which one the Okta AI agent belongs to and links none.
5. Not synced yet - AI agents are read on the same schedule as users, so a newly registered agent appears on the next sync.

Cause: Capsule fetches groups per user via /users/{id}/groups. If a user is in zero groups in Okta, no memberships will appear for them.

Solution:

1. Verify in Okta Admin Console → Directory → People that the user has expected group memberships
2. If groups are present in Okta but missing in Capsule, trigger a re-sync from the integration settings

• Service-to-service OAuth 2.0 using the client_credentials grant
• JWT client assertion signed with an RSA private key - no shared client secret
• DPoP (Demonstrating Proof-of-Possession) binds the access token to Capsule's key pair, preventing token replay
• Per-tenant key pair - each Capsule tenant gets a unique RSA key pair; the private key is stored encrypted in Google Cloud Secret Manager and never leaves Capsule's infrastructure

• Read-only - Capsule cannot create, modify, or delete users, groups, or app configuration
• Scope-limited to read-only directory scopes (okta.users.read, okta.groups.read, okta.aiAgents.read) - Capsule cannot read security policies, system logs, application assignments, or any data outside the directory
• AI agent registration metadata only - For AI agents, Capsule reads what is registered (ID, name, status, dates). It does not read agent credentials, resource connections, or what an agent did at runtime.
• Read-only admin role - the Read-only Administrator role the service app requires grants view access only; it cannot change anything in your org. If you prefer tighter resource limits, a custom role with view permissions for users and groups also works, as long as its resource set includes all users and all groups; Capsule only sees the users and groups the role covers. If you assign a broader role so Capsule can read AI agents, the access token is still limited to the read-only scopes.
• Active users only - Capsule does not enumerate deactivated accounts

• Access tokens are short-lived (5-minute client assertion lifetime) and minted per ingestion run
• Tokens are never persisted; only the long-lived RSA private key is stored
• Rotating the public key in Okta immediately invalidates Capsule's access - re-register a new JWK from Capsule to restore the connection

Need help with the integration?

• Documentation: docs.capsule.security
• Email Support: support@capsule.security

When contacting support, please include:

• Your Okta domain
• The Client ID of the Okta service app (not the JWK)
• Screenshots of any error messages from the Capsule installation card
• Timestamp when the issue occurred