Okta
Okta is an identity and access management service. Owlie syncs Okta users, groups, applications and standard administrator roles, provisions user accounts, and manages five access relationships: group membership, user and group application assignments, and user and group assignments for six supported standard administrator roles.
Capabilities
| Capability | Support |
|---|---|
| Sync | Yes. Users, groups, applications and standard administrator roles. |
| Incremental sync | No. |
| Account provisioning | Yes. Create, update, delete, suspend and unsuspend users. |
| Grant writes | Yes. Add and remove all five declared Grant kinds. |
| Notifications | No. |
| Custom operations | Yes. User lifecycle, factor, password and session actions; group application and role assignment actions. |
Authentication
| Option | Choose it when | App ownership |
|---|---|---|
| API Token | You use an Okta SSWS API token. | Customer-owned token. |
| OAuth 2.0 Authorization Code | You want a scoped OAuth integration with an interactive authorization flow. | Customer-owned OAuth app. |
| Private Key Auth | You use an Okta service app with a private key and client credentials. | Customer-owned service app and key. |
Get credentials from Okta
API Token
Create an API token in the Okta Admin Console as described in Create an API token. The token inherits the permissions of its administrator; use an account with only the authority needed for your selected sync and write operations. Okta sends this credential using the SSWS authorization scheme.
OAuth 2.0 Authorization Code
Create an OAuth 2.0 app integration in the Admin Console and enable the required Okta API scopes. Use the authorization code flow with PKCE. Select only the scopes your enabled features require:
| Feature | Scopes |
|---|---|
| Read users | okta.users.read |
| Create, update, delete, suspend or unsuspend users | okta.users.manage |
| Read groups and membership | okta.groups.read |
| Change group membership | okta.groups.manage |
| Read applications and assignments | okta.apps.read |
| Change application assignments | okta.apps.manage |
| Read administrator roles and assignments | okta.roles.read |
| Change administrator role assignments | okta.roles.manage |
| Clear user sessions | okta.sessions.manage |
| Reset factors | okta.factors.manage |
| Refresh authorization | offline_access |
See Okta's OAuth 2.0 guide for app setup and grant configuration.
Each manage scope includes the corresponding read access. If you need both sync and writes for a resource, its manage scope is sufficient; use the narrower read scope for sync-only access.
Private Key Auth
Create an API Services integration (service app), register its public key, and retain its client ID and matching PKCS#8 private key. Grant the Okta API scopes the connector needs and assign an administrator role that restricts the service app to the required resources. The connector uses RS256 private-key JWT authentication as documented in Implement OAuth for an Okta service app.
Connect Okta in Owlie
| Field | Required | Format and example |
|---|---|---|
| Okta Domain | Yes | Hostname only, such as acme.okta.com; omit scheme, port and path. Owlie trims whitespace and lowercases the hostname. |
| API Token | For API Token auth | Secret SSWS token. |
| Client ID | For either OAuth option | OAuth app client ID. |
| Scopes | No | Select Okta management scopes; defaults depend on auth option. |
| Private Key | For Private Key Auth | Secret PKCS#8 PEM key matching the public key registered with Okta. |
| Key ID | No | kid of the registered public key. |
The connection check requests one user from the configured Okta domain. It does not establish that every enabled feature's scopes or administrator permissions are available.
Entities
| Entity | In Okta | Identifier | Key attributes | Sync | Create | Update | Delete | Grants (as target) |
|---|---|---|---|---|---|---|---|---|
| User | Okta user account | id | Login, email, first and last name, status | Yes | Yes | Yes | Yes | No |
| Group | Okta group | id | Name, description, type | Yes | No | No | No | member_of |
| Application | Okta application integration | id | Name, label, sign-on mode, status | Yes | No | No | No | assigned_application, group_assigned_application |
| Role | Standard Okta administrator role | id | Role type, label | Yes | No | No | No | assigned_role, group_assigned_role |
People lifecycle
User sync turns each Okta user's status into their employment status, which places them in People lifecycle:
| Okta user status | Employment status | Lifecycle state |
|---|---|---|
Active, Password expired, Password reset (RECOVERY), Locked out | Active | Active |
Staged, Pending user action (PROVISIONED, not yet activated) | Pre-hire | Pre-hire |
| Suspended | Suspended | Suspended |
Deactivated (DEPROVISIONED) | Terminated | Terminated |
| Any other status | Not set | Unknown, until you map it |
A user whose password expired or is being reset, or who is locked out, is still employed, so they stay Active. A deactivated user becomes Terminated, and the built-in Terminated access deny removes their access. Okta sends no hire, start or end date, so Okta alone never shows someone as Leaving before they go, and the date a user was created in Okta isn't used as a hire date. You can change or remove this mapping on the Okta sync's Mappings tab. If an HR system also sends employment status, choose which one wins with the employment status source priority. Without one, the most recently synced source wins.
Grant kinds
| Kind | Native relationship | Principal → target | Add/remove | Qualifiers | Membership |
|---|---|---|---|---|---|
member_of | Group membership | User → group | Yes | None | No |
assigned_application | User application assignment | User → application | Yes | None | No |
group_assigned_application | Group application assignment | Group → application | Yes | None | No |
assigned_role | User administrator-role assignment | User → role | Yes | None | No |
group_assigned_role | Group administrator-role assignment | Group → role | Yes | None | No |
Role writes support SUPER_ADMIN, ORG_ADMIN, READ_ONLY_ADMIN, MOBILE_ADMIN, API_ACCESS_MANAGEMENT_ADMIN and REPORT_ADMIN. Okta also allows resource targets for APP_ADMIN, USER_ADMIN, HELP_DESK_ADMIN and GROUP_MEMBERSHIP_ADMIN; Owlie doesn't write any assignments of those role types because the connector can't distinguish a targeted assignment from an organization-wide one in its Grant model. Role observations identify the role type and don't prove organization-wide privilege. See Okta's standard role reference. Custom roles and resource sets aren't included. Group membership changes apply only to Okta-managed groups. Owlie syncs a user's group links, but doesn't use those links to expand the applications or administrator roles assigned to the group onto each user.
Custom operations
Owlie also exposes these provider-specific operations: activate, reactivate, or deactivate a user; unlock a user; reset their factors; expire their password; clear their sessions; assign or revoke an application for a group; and assign or revoke a standard role for a group. The role-type refusal above applies to managed Grant writes; the preserved group-role custom operations accept an explicit Okta role type. assign-application-to-group accepts optional priority and profile values. expire-password can return a temporary password; clear-user-sessions can optionally revoke OAuth tokens.
Provisioning behaviour and limits
Provisioning creates an active Okta user with first and last name from the identity, uses the identity email as the user's email, generates the login from it (the identity email first, then a numbered variant such as jsmith2@example.com when another user holds it), and generates a password. Revoke removes managed Grants and deletes the user. Disable suspends a user; enable unsuspends them.
Revoke deletes the Okta user. Review lifecycle mappings and managed Grants before enabling automated revocation.
A password change sets the user's new password when the resource is linked to the person's password or lets people set it themselves. It needs the okta.users.manage scope (for OAuth) and an administrator role allowed to set that user's password, such as Super Administrator, Organization Administrator, or a Group Administrator for the user's groups. Okta can refuse a password that breaks the org's password policy, or a change the connection may not make; Owlie shows a fixed reason for each and never Okta's text. A user whose password another system owns (a federated, Active Directory or LDAP-sourced user) reads as the service rejecting the password. Owlie hasn't confirmed Okta's answers against a live org, so try a password change on a test user first.
Managed application Grants do not carry app-specific credentials or profile fields: user assignments use the USER scope, and group assignments send an empty profile. Use the assign-application-to-group custom operation when you need to provide a group assignment priority or profile. Owlie does not sync custom roles or resource sets, and managed role Grants have no scope qualifier.
Okta rate limits vary by organization, API endpoint and credential. Owlie marks provider responses it recognizes as rate limits as retryable quota errors. See Okta's rate limit guidance for your org's quotas and monitoring.
Troubleshooting
- Connection succeeds but an operation is forbidden: add the specific OAuth scope required by that operation and ensure the authorizing administrator or service-app admin role has the needed privilege. Reauthorize after changing OAuth grants.
- A private-key connection cannot obtain a token: confirm the private key is PKCS#8 PEM and matches the public key registered on the service app; check the configured client ID and optional key ID.
Changelog
Okta is at connector version 1. Owlie displays each connector's changelog with the connector in the integration catalog.