Skip to content
Guides
/
/
Okta
Last updated

Okta Integration

Connect your Okta organization to Capsule Security to enrich user identities with directory profile and group membership data.

Overview

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.

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.

What Gets Synced

  • 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)

Prerequisites

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)

Installation Overview

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

Step 1: Start the Integration 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.

Steps

  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.

Step 2: Create an OAuth Service App in Okta

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

Steps

  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. (Optional) On the Admin roles tab, you can leave the app with no admin role assigned — the granted read scopes are sufficient for the read paths Capsule uses.

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

Step 3: Enter Credentials in Capsule

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

Steps

  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.

Step 4: Verify Data 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.

Troubleshooting

"Invalid Client ID or the public key has not been registered in Okta."

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

"Insufficient permissions. Ensure the OAuth app has the required scopes."

Cause: The token exchange returned 403. The OAuth service app exists but is missing one or more of the required scopes.

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. Retry the connection in Capsule

"Failed to authenticate with Okta"

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

No Users Appear After Installation

Possible causes:

  1. First sync still in progress — Wait a few minutes for the initial pagination to complete
  2. No active users — Capsule fetches users from /api/v1/users; deactivated users are not surfaced
  3. Service app scope was revoked after installation — Re-grant the required scopes and trigger a sync

Group Memberships Missing on Users

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

Security & Privacy

Authentication

  • 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

Data Access

  • 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
  • Active users only — Capsule does not enumerate deactivated accounts

Token Lifecycle

  • 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

Support

Need help with the integration?

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
Previous page
Next page