Okta — Integration Setup

Prerequisites

• Okta org (any edition with API access)
• Ability to create an SSWS API token (typically requires an Okta admin role)
• CMDash Essentials tier or above

Step 1: Create an API Token

1. Log in to the Okta Admin Console.
2. Go to Security → API → Tokens → Create Token.
3. Name it CMDash Integration.
4. Copy the generated token immediately — it is shown only once.

Note: Okta API tokens inherit the permissions of the admin who created them. Create the token from a dedicated admin account with the least-privileged Okta admin role that still allows reading users, factors, and system log events (a Read Only Administrator role is sufficient for this integration).

Step 2: Connect in CMDash

1. Navigate to Integrations in your CMDash dashboard.
2. Find Okta and click Connect.
3. Enter:
   • Domain — your Okta org domain (e.g., yourcompany.okta.com)
   • API Token (stored as this connection's access token, sent as Authorization: SSWS <token>)
4. Click Save & Test Connection.

What Syncs

CMDash computes an identity coverage summary from your active user population: total accounts, how many have MFA enrolled (detected via credentials.provider.type / credentials.factor.provider on the user profile), how many accounts look privileged (profile.userType = Admin or a title containing "admin"), and how many of those privileged accounts have MFA. User pagination follows Okta's Link header and stops after 5,000 users. The System Log query is filtered to user.session.start failures, user.account.lock, and policy.evaluate_sign_on events, capped at 500 events, and only failed/lockout events are turned into incidents.

Troubleshooting

• 401 Unauthorized: The SSWS token was revoked or the admin account it belongs to was deactivated.
• 403 Forbidden: The token's owning admin role doesn't have rights to /users, /users/{id}/factors, or /logs — use at least Read Only Administrator.
• MFA coverage looks low: CMDash only counts a user as MFA-enrolled if credentials.provider.type is OKTA or a factor provider is present on the profile payload returned by /users — third-party IdP-federated MFA that Okta doesn't reflect in this field will undercount.
• "Privileged account" flag looks wrong: The privileged-account heuristic is simple — profile.userType === 'Admin' or the profile title containing the substring "admin" — it is not based on actual Okta admin role assignments.

Rate Limits & Sync Behavior

Credential Rotation

Okta SSWS tokens expire after 60 days of inactivity but do not expire on a fixed schedule if used regularly (CMDash's periodic sync itself keeps the token "active"). CMDash still recommends rotating quarterly.

To rotate:

1. In Okta: Security → API → Tokens, create a new token.
2. In CMDash: Settings → Integrations → Okta → Edit.
3. Enter the new API Token and Save.
4. Revoke the old token in Okta once confirmed working.

Note: Because Okta token expiry is activity-based rather than a fixed date, CMDash cannot show a 30-day expiry warning banner for this integration.

Multiple Instances / Multi-Site

If you run more than one Okta org (e.g., a production org and a separate org for an acquired subsidiary), each org needs its own CMDash connection.

To add another org:

1. Create an API token in the additional Okta org, following Step 1.
2. In CMDash: Settings → Integrations → Add Integration → Okta.
3. Enter the domain and API token for the additional org.
4. Give the connection a descriptive name (e.g., Okta - Corp, Okta - Subsidiary).
5. Click Save & Test Connection.

Compliance Framework Coverage

The Okta integration provides evidence for the following controls. Coverage is automatically mapped when data is synced.