Okta connector (OAuth admin consent)

When to use OAuth admin consent

• Your Okta org disables API tokens by policy, or your security team requires every integration to go through an admin-consent flow.
• You want refresh-token rotation handled automatically (Okta rotates the refresh token on each exchange — ITDR persists the new one encrypted).
• You want a user-visible audit record of the consent: the Okta admin sees one consent prompt with the exact scopes ITDR will use.

Scopes to grant in Okta admin

• okta.users.read — Pull identity inventory into /identities.
• okta.users.manage — Required for containment bundles (deactivate user, clear sessions).
• okta.logs.read — Pull the system log (sign-ins, MFA verification, lifecycle).
• okta.policies.read — Read sign-on, password, and lockout policies for posture findings.
• okta.factors.read — Read enrolled MFA factors per user for MFA-coverage posture finding.
• okta.userTypes.read — Resolve admin role assignments cleanly across user types.

Register the OAuth app in Okta

1. Sign in to your Okta admin console as a Super Admin.
2. Navigate to Applications > Applications and click "Create App Integration".
3. Choose "OIDC - OpenID Connect" and "Web Application", then Next.
4. Name it something like "ITDR Platform (OAuth)" and set the redirect URI to the value ITDR displays in the connector form (typically https://backend-production-1254.up.railway.app/api/v1/connectors/okta/oauth/callback). Save.
5. In the General tab → Grant type section, check BOTH "Authorization Code" AND "Refresh Token". REQUIRED: without the Refresh Token grant type enabled, Okta refuses to issue a refresh token even when offline_access is requested, and ITDR errors with "Okta did not return access_token + refresh_token".
6. Open the new app's Assignments tab → Assign → Assign to Groups → pick "Everyone" (or assign to People → pick yourself as Super Admin). REQUIRED: without an assignment, Okta returns "User is not assigned to the client application" at the consent step.
7. Open the "Okta API Scopes" tab and grant: okta.users.read, okta.users.manage, okta.logs.read, okta.policies.read, okta.factors.read, okta.userTypes.read AND offline_access. The offline_access scope is what gives ITDR a refresh token to mint short-lived access tokens later.
8. In the General tab copy the Client ID. If the app type is "Web" with a client secret, copy the Client Secret too. For PKCE-only public clients, leave the secret blank in ITDR.
9. When you paste the Okta org URL into ITDR, use the org URL (e.g. https://acme.okta.com), NOT the admin URL (https://acme-admin.okta.com). ITDR strips the trailing "-admin" automatically since 2026-05-21, but it's clearer to paste the right one.

Add the connector in ITDR

1. Open /connectors in ITDR.
2. Click "Add connector", then in the Okta pill row pick "OAuth (Admin consent)".
3. Fill in: Connector name, Okta org URL, OAuth client_id, and (optionally) client_secret.
4. Click "Continue with Okta admin consent". You are redirected to Okta. Sign in as Super Admin and approve the scopes prompt.
5. Okta redirects back to ITDR. The backend exchanges the authorization code for access + refresh tokens, persists them encrypted under CONNECTOR_CREDENTIALS_KEY, and probes /api/v1/users?limit=1 to confirm the scopes work end-to-end.
6. On success you are redirected back to /connectors with okta_oauth=success in the URL. The first sync runs within five minutes.

Lifecycle and rotation

• Refresh-token rotation: Okta issues a new refresh_token on each access-token exchange. ITDR persists the rotated token back to connector.configuration (Fernet-encrypted) inside the same DB transaction.
• Access-token lifetime: typically one hour. The OktaClient transparently refreshes when expired (or on 401), retries the request once, and persists the new token.
• Revocation: revoke either the refresh token or the entire OAuth app in Okta admin. ITDR will surface this as sync_error="credentials_rejected" on the next sync. Recreate the connector via the same flow to reauthorize.
• Scope drift: if the Okta admin removes a granted scope later, the sync starts failing with a 403 on the affected endpoint and the connector flips to sync_status="error" with a clear message.

OAuth vs API token vs Service App

• API token = single static credential, inherits the granting user permissions, no rotation. OAuth = refreshable access tokens scoped to specific operations, admin-consent audited.
• API token is faster to ship (no Okta admin console app registration). OAuth is more durable for long-lived integrations and matches enterprise security policy.
• Both modes ingest the same data and run the same containment + posture surface. Choose based on policy and operations team preference.