This document provides a clear, simplified explanation of the Okta restore functionality, its user interface options, and critical object-level caveats.
Core Restore Configuration Options
When performing a data restore, you are presented with three primary configuration toggles and dropdown options:
Restore Relationships
Enabled: Restores all associated relationships of the selected record.
Disabled: Restores the record as a standalone entity without restoring its relationships.
Restore Permanently Deleted Items Only
Use this option during bulk restore operations when you want to recover deleted records exclusively without modifying or altering existing records.
On-Conflict Resolution Strategies
A Conflict occurs when you attempt to restore a record that already exists within the target Okta portal. You can handle conflicts using one of three behaviors:
Option | Behavior | Example / Exception |
Skip | Skips the parent record entirely during the restore process. | All child records are still restored, except for policy rules. |
Overwrite | Replaces the existing data in the Okta portal entirely with the backup payload. | If a user's first name is "Johny" in Okta but "John" in the backup, the system overwrites it back to "John". |
Merge | Compares backup data with live Okta data, merging new field additions and data changes. | If a live schema has 12 fields but the backup only contains 10, a standard overwrite might fail. Merge pulls the 2 new fields from the live environment, combines them with the 10 backup fields, and executes the restore. |
Note: If the exact same field contains different data in both the backup payload and the live Okta system, the Merge operation prioritizes the live data and replaces the backup data with the live values.
General Restore Execution Logic
To accurately identify whether a record is missing (deleted) or present during execution, the system employs a two-tiered lookup strategy:
Primary Lookup: The system attempts to locate the record using its unique system ID.
Fallback Lookup: If the ID search fails, it searches using a unique identifier attribute specific to that object type (e.g., username for Users, name for Groups).
Note: This deterministic fallback behavior applies to both same-org and cross-org restore operations.
Okta- Imposed Limitations
Okta has certain product limitations, which are stated below:
Users
Deleted User Types: For same-org restores, if a custom user type was deleted, the system restores the user to the default user type.
Mandatory Schema Requirements: If the target user schema includes a mandatory property that is missing from the backup payload, the restore operation will fail.
Status Changes During Updates: When updating existing users via a restore, status changes are generally ignored.
Exception: Users in a Deprovisioned state cannot have properties updated directly. To bypass this, the system temporarily shifts the user to a Suspended state, updates the properties, and saves the record.
User Creation Status Lifecycle: Newly created users will inherit statuses based on their backup state:
Backup Status | Restored Status in Okta |
Staged | Staged |
Active | Pending User Action |
Suspended | Suspended |
De-provisioned | Suspended |
Cross-Domain Restores: All users can be restored across domains and will automatically be assigned the default user type of the target domain.
Cross-Org: Not restorable, because the corresponding relationship records do not exist in the target organization.
Groups & Group Schemas
App Groups: Groups imported from external third-party systems cannot be restored because Okta does not permit manual updates to these entities.
Group Schema Deletions: If a group schema attribute is deleted and you attempt to restore it immediately, the operation will fail. You must wait 10 to 15 minutes before attempting the restore.
Group Rules: Restored group rules always preserve and inherit the exact status documented in the backup file.
Applications
Admin Role Assignments: If an application has Okta admin roles explicitly assigned to it, it cannot be updated during a restore operation.
Deleted Applications: Standard deleted applications can be fully restored.
Real-World SaaS Applications: Deleted real-world provisioning applications (such as Jira or Salesforce) cannot be re-created from scratch via restore, though their configurations can be updated if they already exist.
Authentication Secrets: Client secrets and authentication certificates cannot be backed up or restored because Okta’s APIs do not expose sensitive credential details.
Tenant Settings
Conflict Options: Only Skip and Overwrite strategies are supported; the Merge strategy is unavailable for Tenant Settings.
Unsupported Components: Certain configurations, such as Captcha Settings, are fundamentally non-restorable.
Event Hooks & Inline Hooks
Authentication Headers: Hooks containing authentication header data in the backup cannot be restored, as Okta requires a fresh client secret alongside the header. If no header data exists in the backup, the restore will succeed. This limitation applies to cross-org operations as well.
Status Preservation: Restored hooks automatically adopt the status present within the backup file.
Authorization Servers
Cryptographic Keys: Authorization server signing keys are not backed up.
Status Preservation: Restored authorization servers inherit the status from the backup file.
Policy Rules Exception: Restoring an Authorization Server restores its top-level policies, but does not restore the underlying individual rules belonging to those policies. To successfully recover rules, you must restore the Authorization Server Policy separately.
Identity Providers (IdPs) & Authenticators
Status Preservation: Both Identity Providers and Authenticators inherit their status directly from the backup dataset.
Note: Both components are subject to minor known API errors during execution depending on target org configurations.
Network Zones
Status Preservation: Restored Network Zones always inherit the status documented in the backup.
Policies
Cross-Tenant Blockers: Global Session Policies, Password Policies, and MFA Policies cannot be restored to a cross-tenant target environment.
Default Policies: Individual rules belonging to default out-of-the-box Okta policies cannot be restored.