Connect Okta

Reads users, MFA factors, groups, admin role assignments and application assignments from the Okta Management API, through a read-only OAuth service app in your Okta org.

For the general flow of adding a source, see Connect Data Sources.

Prerequisites

• An Okta administrator account allowed to create app integrations

• How the app is created decides how HARVEN authenticates: an API Services Integration created with the Okta Integration Wizard uses a client secret (steps 1 to 3); an API Services app created through the classic experience uses a private key (see the alternative below), because Okta refuses a client secret from it for Okta API scopes

• HARVEN connects as an OAuth service app, with a client secret or a private key: SSWS API tokens are not accepted, because they carry every right of the admin who created them

Setup

Step 1 - Create the API Service Integration

1. In the Okta Admin Console, open Applications → Applications → Create App Integration

2. Keep the Okta Integration Wizard tab and click Next

3. Create an API Services Integration named e.g. HARVEN

4. Grant exactly these read-only scopes: okta.users.read, okta.groups.read, okta.roles.read, okta.apps.read, okta.policies.read, okta.logs.read and okta.apiTokens.read

5. Deploy it to your org

Step 2 - Copy the credentials

1. Open the integration's General tab

2. Copy the Okta Domain and the Client ID

3. Under Client Secrets, click Generate new secret and copy it immediately — Okta shows it only once

Step 3 - Fill the parameters in HARVEN

1. Open Workspace → Data sources → Add → Okta

2. Paste the Okta domain, e.g. acme.okta.com (the admin console address acme-admin.okta.com works too)

3. Keep Client secret as the authentication, and paste the Client ID and the client secret

4. Click Save. HARVEN does not test the credentials on save: the connector opens on its Tables tab, where each table is checked, so a missing scope shows up there as failing tables

Alternative - Classic experience app with a private key

Instead of steps 1 and 2, for an API Services app created through the classic experience rather than the Okta Integration Wizard. Okta accepts only a private key from such an app for Okta API scopes — a client secret is refused — and the app needs two admin roles on top of its scopes. Creating the second one takes a super administrator.

1. In Applications → Applications → Create App Integration, use the classic experience rather than the Okta Integration Wizard, choose API Services, name it (e.g. HARVEN) and save

2. Under Client Credentials, click Edit and select Public key / Private key, then Add key → Generate new key and copy the private key (PEM or JSON) — Okta shows it only once

3. Under General Settings, clear Require Demonstrating Proof of Possession (DPoP) header in token requests — it is enabled by default and HARVEN does not send DPoP proofs

4. In the Okta API Scopes tab, grant the seven scopes listed in step 1

5. In the Admin roles tab, click Edit assignments and assign Read-only Administrator — scopes alone are not enough, and Okta never assigns a role to an app automatically

6. Read-only Administrator cannot read admin role assignments, which the three admin-role tables need. In Security → Administrators → Resources, click Create new resource set, add the Identity and access management resource type (all identity and access management resources) and create it

7. In Security → Administrators → Roles, click Create new role and grant it only the permission to view roles, resources and admin assignments

8. Back in the app's Admin roles tab, add an assignment of that custom role on that resource set, next to Read-only Administrator

9. In HARVEN, choose Private key as the authentication, then paste the Client ID and the private key (or drop the key file)

How the tables are queried

Okta exposes MFA factors, group members, group roles, application assignments and policy rules only under their user, group, application or policy. Those tables are always read for specific parents — joined to Users, Groups, Applications or Policies. A query without that filter is refused rather than run, because it would call the API once per object of the org.

User admin roles is the exception: read without a filter, it lists only the users holding an admin role, one call per admin.

MFA events reads only MFA event types from the System Log, over the last 30 days unless the query names a date range. Okta keeps 90 days.

Fields to fill in HARVEN

Collected data

• users — User directory, deprovisioned users included: Identification and join keys (user_id, login, email), Lifecycle state (status, status_changed), Dormancy and password age (last_login, password_changed)

• user_factors — Enrolled MFA factors (queried by user): Which factor, for whom (user_id, factor_type, provider), ACTIVE when usable (status)

• groups — Group directory: Identification (group_id, name, type)

• group_members — Group membership (queried by group): Join keys (group_id, user_id)

• user_role_assignments — Admin roles held by each user, directly or through a group: Who holds which role (user_id, role_type, label), USER (direct) or GROUP (inherited) (assignment_type)

• group_role_assignments — Admin roles assigned to groups (queried by group): Which group grants which role (group_id, role_type, label)

• apps — Application integrations: Identification (app_id, label, status), Federated SSO or not (sign_on_mode), Its sign-in policy (access_policy_id)

• app_user_assignments — Application assignments (queried by application): Who can reach which application (app_id, user_id, status)

• policies — Password, global session, app sign-in and MFA enrollment policies: Which policy applies to whom (type, status, priority, include_group_ids), Password rules (password_max_age_days, password_min_length)

• policy_rules — Rules of each policy (queried by policy): Whether sign-in needs MFA (access, factor_mode), Phishing-resistant factor required (phishing_resistant_required), Session and network scope (session_max_lifetime_minutes, network_connection)

• custom_role_permissions — What each custom admin role grants: One row per permission (role_id, role_label, permission)

• api_tokens — Active legacy API tokens: Owner and lifetime (user_id, expires_at, token_window), Network restriction (network_connection)

• mfa_events — MFA events from the System Log (last 30 days by default, 90 kept): Verification, failure or bypass (event_type, outcome_result, factor), Who, when, from where (user_id, published, country)

Official documentation

• Okta Integration Wizard overview

• API Service Integrations

• Implement OAuth for Okta with a service app

Need help? Contact [email protected].