> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/identity-provider/okta.md). # Okta Okta is a leading identity and access management (IAM) platform that provides single sign-on, multi-factor authentication, and user lifecycle management. Connecting Okta to Harmony enables automated application discovery, intelligent license optimization, and seamless user provisioning workflows. *** ### What the Okta Integration Enables | Capability | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Application Discovery | Automatically discover all applications managed through Okta, including SaaS and cloud-based tools assigned via SSO - even without MDM enrollment | | License Optimization | Track application usage and identify unused licenses for cost savings | | User Provisioning | Automate user onboarding and offboarding across all connected applications, including assigning and revoking Okta application access via workflows | | Access Management | Centralize access requests and approvals with intelligent policy enforcement | | Automation Workflows | Build custom workflows using the Okta API for identity and access management | | Employee Directory Sync | Sync rich employee profile data - including manager, department, location, and employment type - directly from Okta into your Harmony employee directory | | Login Event Tracking | Capture and view normalized Okta login and authentication events within Harmony's event log and reports | | User Status Lookup | Retrieve the live lock and account status of any user directly through your connected Okta instance | Anything defined in the [Okta API](https://developer.okta.com/docs/reference/) can be accessed through Harmony workflows. *** ### Prerequisites Before connecting Okta to Harmony, ensure you have: 1. **Okta Administrator access** to your Okta organization 2. **A Harmony account** with admin privileges 3. **Your Okta domain** (e.g., `company.okta.com` or `company.oktapreview.com`) {% hint style="info" %} You need Super Admin or Org Admin privileges in Okta to create API tokens and OAuth applications. {% endhint %} *** ### Step 1: Add the Harmony Integration 1. **Navigate to Okta App Catalog** 1. Sign in to your Okta Admin Console 2. Navigate to **Applications → Browse App Catalog** 3. Search for **Harmony (API)** in the catalog 4. Click **Add Integration** 5. Follow the on-screen prompts to complete the integration setup Harmony is a verified application in the [Okta Integration Network (OIN)](https://www.okta.com/integrations/) marketplace, so no custom app configuration is required. The integration uses OAuth-based authentication with a managed token refresh flow, keeping your connection secure and uninterrupted. Okta domain validation is enforced during setup to help catch configuration errors early. ![Okta Admin Console - Add Harmony Integration](/files/p9B1kK4rzACqBPczkZNK) *** ### Step 2: Harmony Configuration 1. **Navigate to Integrations** 1. Log into your Harmony dashboard 2. Navigate to **Settings → Integrations** 3. Find **Okta** under **Identity & Access Management** ![Harmony Dashboard - Connect Okta Integration](/files/PazxA5cBifyFuTKTsiN4) 2. **Enter Configuration** Fill in the following fields: | Field | Description | Example | | ----------------- | ----------------------------------------------------------------------------------- | ------------------------------- | | **Instance name** | A descriptive name for this Okta instance | `Company Okta` | | **Client ID** | The Client ID from the Okta OIN app integration | `0oa1a2b3c4d5e6f7g8h9` | | **Client secret** | The Client Secret from the Okta OIN app integration | `AbCdEfGhIjKlMnOpQrStUvWxYz...` | | **Okta domain** | Your Okta organization domain (e.g., or company.okta.eu) | `https://company.okta.com` | Once all fields are filled in, click **Connect** to complete the integration setup. ![Harmony - Okta Configuration Fields](/files/o5tbQ8n5Frvq4YjiWZ8D)

You can find the Client ID and Client Secret in the Okta Admin Console after adding the Harmony integration from the App Catalog.

#### Connecting Multiple Okta Instances You can connect more than one Okta instance to Harmony. This is useful for enterprises that manage separate Okta environments across business units, regions, or subsidiaries. Each Okta instance is tracked independently, so employee data and application records are correctly attributed to the right integration. To add an additional instance, repeat Steps 1 and 2 using a unique **Instance name** for each connection. *** ### What Harmony Syncs from Okta Once connected, Harmony automatically syncs the following data: #### Applications * Application names and descriptions, displayed using the human-readable label configured in Okta (e.g., "Testim.io" rather than `honeybook_testimio_1`) * Application status (active/inactive) * User assignments and access policies * Application logos and metadata * Last used dates and usage statistics * Applications are automatically checked against the Harmony application catalog and grouped under a recognized catalog entry or a new application group - kept up to date as catalog matches change over time #### Users * User profiles (name, email, phone) * User status (active, suspended, deprovisioned) * Group memberships * Application assignments * Authentication factors (MFA status) * **Manager name** - who each employee reports to * **Department** - the team or business unit the employee belongs to * **Location** - the employee's assigned office or region, resolved to full country names * **Employment type** - full-time, contractor, or other classification * **User type** - the Okta user type associated with the account {% hint style="info" %} If you also use an HR system such as HiBob alongside Okta, HR system data takes precedence, ensuring your authoritative people data always wins. {% endhint %} #### Groups * Group names and descriptions * Group members * Application assignments per group * Group rules and policies #### Login Events Harmony ingests webhook events directly from Okta and transforms them into a normalized format enriched with employee and application context. These events are available in Harmony's event log and reports, and can be used in downstream workflows. Event data is correctly attributed to the right employee even when Okta's internal user and app-user identifiers differ. Application instances that no longer exist are gracefully filtered out, and transient errors automatically retry to ensure no events are silently dropped. *** ### User Status Lookups You can retrieve the live lock and account status of any user directly through your connected Okta instance. Harmony maps all 8 Okta account statuses to a consistent, normalized format, so your support agents always have an accurate, up-to-date picture of a user's standing without leaving Harmony. Supported status values include: * Active * Locked out * Suspended * Password expired * Deprovisioned * Provisioned * Staged * Recovery {% hint style="info" %} User status lookups are faster than ever - Harmony now consolidates credential fetching into a single call, reducing latency and placing less load on the system. {% endhint %} *** ### Assign and Revoke Application Access via Workflows You can assign users to Okta applications and revoke their access directly through Harmony's automated workflows. This brings Okta application lifecycle management into the same access provisioning and deprovisioning flows you already use for other integrations. * **Assign access**: Workflows can automatically assign a user to an Okta application as part of an access provisioning step. * **Revoke access**: Workflows can remove a user's application assignment when access is deprovisioned. * **Automatic sync**: After access changes are made, Harmony syncs the updated state to keep your records accurate. *** ### Okta Verify in Workflows #### Automatic OTP Fallback You can configure Okta Verify workflows to automatically fall back to OTP (one-time passcode) verification if an Okta push notification fails to be delivered. Instead of a workflow failing outright when a push verify attempt is unsuccessful, Harmony seamlessly switches to OTP verification to keep the process moving. * **Automatic OTP fallback**: When an Okta push verify attempt fails, the workflow automatically retries using OTP verification. * **Configurable fallback behaviour**: You can choose to disable the OTP fallback if you prefer push-only verification. #### Multi-Device Push Support Okta Verify push notifications work reliably across multiple devices, including environments where users have more than one device enrolled in Okta. * **Multi-device push support**: Push challenges are sent correctly when a user has multiple devices enrolled. * **Smarter retry logic**: Push requests handle OAuth propagation delays more gracefully, with improved retry behaviour to reduce failures caused by timing issues. *** ### Sync Reliability Under API Rate Limits Harmony proactively monitors Okta API rate limit consumption and backs off before hitting Okta's limits, rather than reacting only after errors occur. The number of concurrent Okta API requests made during data collection has also been reduced, spreading the load more evenly across time. This results in more consistent, uninterrupted syncing of your Okta users, groups, and applications - even in environments where other integrations share your Okta API quota. *** ### Troubleshooting
Connection fails with "Invalid API token" **Possible causes:** * The API token was entered incorrectly * The API token has expired or been revoked **Solutions:** 1. Verify you copied the entire API token without extra spaces 2. Generate a new API token in Okta and update Harmony
Application discovery is incomplete **Possible causes:** * Some applications are not assigned to any users * Applications are managed by a different IDP **Solutions:** 1. Verify applications have at least one user assigned in Okta 2. Check that you're using the correct Okta domain
*** Need help? Contact [**support@harmony.io**](mailto:support@harmony.io) for assistance with your Okta integration. *** ### Data & Privacy
Key privacy principles For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy). * Okta credentials are encrypted at rest and in transit * Only necessary scopes are requested for integration functionality * User data is processed solely for identity and access management purposes * Integration can be revoked at any time from Okta or Harmony settings
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.harmony.io/integrations/identity-provider/okta.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.