Okta
Connector maturity: Beta. See Connector maturity.
Description
The Okta connector uses the Okta Management REST API to discover user accounts, groups, and group memberships in an Okta organisation. Authentication uses an Okta SSWS API token — no OAuth flow is required. Pagination follows Okta's Link header (rel="next") pattern.
System Type Classification
| Field | Value |
|---|---|
| System Type | Identity Provider |
| Default Scan Priority | 10 (scanned first) |
Version Support
| OrbisID Edition | Supported |
|---|---|
| Community | No |
| Pro | Yes |
| Enterprise | Yes |
Supported Protocol
| Protocol | Port | Notes |
|---|---|---|
| Okta Management REST API (HTTPS) | 443 TCP | SSWS token authentication |
What OrbisID Discovers
| Data | Source |
|---|---|
| User accounts | GET /api/v1/users (all statuses) |
| User status | status field (ACTIVE, SUSPENDED, DEPROVISIONED, etc.) |
| Groups | GET /api/v1/groups (all types) |
| Group memberships | GET /api/v1/groups/{id}/users |
| Group type | OKTA_GROUP, APP_GROUP, BUILT_IN — recorded as entitlement type |
| Applications and their assigned users and groups (optional) | GET /api/v1/apps, /api/v1/apps/{id}/users, /api/v1/apps/{id}/groups — see Detected Applications |
Connection Requirements
Okta API Token
Create an API token in the Okta Admin Console under Security → API → Tokens. The token inherits the permissions of the admin user who created it.
The token must be created by an admin with at minimum:
- Read Users permission — to list users and their profiles
- Read Groups permission — to list groups and group memberships
Recommended: Create a dedicated read-only admin account (e.g., orbisid-scanner@company.com) with the minimum required admin role and generate the API token from that account.
Credential Mapping
| OrbisID Field | Okta Value |
|---|---|
credential.password | Okta SSWS API token (the full 00... string) |
system.ipAddress (the IP Address / Hostname field) | Okta domain (e.g., company.okta.com) |
Network Requirements
The OrbisID server (or On-Premise Agent) must have outbound HTTPS access to https://<company>.okta.com on port 443.
Configuration Steps
- Log in to the Okta Admin Console with a read-only admin account
- Navigate to Security → API → Tokens → Create Token
- Give the token a name (e.g.,
OrbisID Scanner) and copy the token value - Create a Credential in OrbisID:
- Username: (leave blank or use the admin email for reference)
- Password: The Okta API token
- Navigate to Systems → Add System
- Fill in the fields:
| Field | Value |
|---|---|
| Name | Descriptive name (e.g., Okta – company.okta.com) |
| IP Address / Hostname | Your Okta domain (e.g., company.okta.com) — not a URL, and not the descriptive Name |
| OS Type | Okta |
| System Type | Identity Provider |
| Credential | The API token credential |
- Click Test Connection to verify the API token
- Click Save
For Okta preview sandbox environments, set the hostname to your preview domain (e.g., company.oktapreview.com).
Okta API tokens expire after 30 days of inactivity. Set a calendar reminder to refresh the token before it expires to avoid scan failures.
Detected Applications
Turn on Detect Applications (in the system's settings, under Detected Applications) to bring in the applications your users are assigned to in Okta.
- Each active Okta application is added to the System Inventory as a child system named
<this system> - <application>, for example Okta - OrbisID, listed under the Okta system ("3 detected applications"). - Each application gets an access entitlement (for example OrbisID access). Its members are the Okta users assigned to the application, either directly or through an assigned group, in which case the group is shown as the path.
- The username each user has in the application (Okta's application username) is recorded, so access can be matched against the application's own accounts.
- Access to the Okta Admin Console application is marked privileged.
Detected applications are maintained by the Okta system's scans: they are refreshed on every scan, archived when an application is removed in Okta (and restored if it comes back), and archived when Detect Applications is turned off. They are not scanned, edited or offboarded on their own.
Linking and reconciliation. If you also scan the application directly (for example an OrbisID system for OrbisID itself), use Link on the detected application to link it to that system, then Reconcile access to compare the two sides:
- accounts with access through Okta that match an account in the application (on the application username, the account name or the email address);
- accounts with access through Okta that have no account in the application;
- application accounts that are not assigned through Okta.
This needs the okta.apps.read permission (an API token from an admin with read access to applications). If the token cannot list applications, the scan carries on and previously detected applications are left unchanged.
Real-Time Account & Entitlement Events
Beyond periodic full scans, OrbisID can poll the Okta System Log API on a short interval to detect account and group-membership changes near-real-time, or (opt-in) receive Okta Event Hooks for true push delivery. See Real-Time Events — Pro/Enterprise only.
Troubleshooting
| Symptom | Likely Cause | Resolution |
|---|---|---|
Okta API authentication failed | Invalid or expired API token | Regenerate the API token in the Okta Admin Console |
Okta API access denied (403) | Token lacks required permissions | Verify the admin role has Read Users and Read Groups permissions |
| No users returned | Wrong domain, or domain entered in the wrong field | Ensure the IP Address / Hostname field (not the descriptive Name field) is set to the correct Okta domain — a bare domain, not a URL |
Illegal character in authority scan error | A descriptive label or full URL was entered in the IP Address / Hostname field | Set that field to just the domain (e.g. company.okta.com), with no scheme, spaces, or parentheses |
| Some groups missing members | Rate limiting on group member calls | Large Okta tenants may hit rate limits; OrbisID does not currently implement rate-limit backoff — contact support |