Butterfly Security for Okta

Okta Integration Network (OIN) integration providing Single Sign-On via OIDC, SCIM 2.0 provisioning for lifecycle management (LCM), and automated backup, disaster recovery, and compliance monitoring for your Okta organization.

SSO (OIDC)SCIM 2.0 (LCM)EntitlementsUniversal LogoutBackup & RestoreCompliance Monitoring

Overview

The Butterfly Security Okta Integration Network (OIN) integration provides Single Sign-On (SSO) via OIDC, SCIM 2.0 provisioning for lifecycle management (LCM), and automated backup, disaster recovery, and compliance monitoring for your Okta organization. Once installed, your team can sign in to Butterfly Security through Okta, and user accounts are automatically created, updated, and deactivated as your Okta directory changes.

Butterfly Security connects to your Okta org via OAuth 2.0 and gives administrators the ability to perform scheduled or on-demand backups of their identity configuration — users, groups, applications, policies, authorization servers, and 30+ additional resource types. In the event of accidental misconfiguration, unauthorized changes, or a disaster recovery scenario, administrators can restore any supported resource to a previous known-good state directly from the Butterfly Security dashboard.

Supported Features

Automated Backup

Schedule hourly, daily, or weekly backups of your entire Okta configuration. Supports 30+ resource types across users, groups, apps, policies, and more.

Disaster Recovery

Restore users, groups, applications, policies, and other supported resources to a previous known-good state. Dry-run preview mode lets administrators review exactly what will change before committing.

Compliance Monitoring

Continuous compliance checks against SOC 2, NIST 800-53, HIPAA, PCI DSS, ISO 27001, and CIS Controls frameworks.

Change Detection

Diff any two backup snapshots to see exactly what changed in your Okta configuration over time.

Prerequisites

Okta Requirements

Okta Super Administrator or Organization Administrator role
Permissions to manage API Service Integrations (Applications → API Service Integrations)
API Access Management enabled in your Okta org

Butterfly Security Requirements

An active Butterfly Security account
Team admin or super admin role

Configuration Steps

Install the Butterfly Security Integration in Okta

Sign in to your Okta Admin Console.
Navigate to Applications → API Service Integrations.
Click Discover new integrations and search for Butterfly Security.
Click Add integration and accept the requested OAuth scopes.
Copy and securely store the following values:
Okta Domain: your-org.okta.com
Client ID: 0oa...
Client Secret: Generated by Okta

Connect Your Okta Org in Butterfly Security

Sign in to Butterfly Security at butterflysecurity.org.
Navigate to Dashboard → Connections → New Connection.
Select Okta as the provider.
Enter the Okta Domain, Client ID, and Client Secret from Step 1.
Click Test Connection to verify connectivity.
Save the connection.

Run Your First Backup

From the Dashboard, select your Okta connection.
Click Run Backup Now to start an on-demand backup.
The backup will snapshot all resources your granted scopes allow access to.
Optionally, configure a backup schedule (hourly, daily, or weekly) under connection settings.

Enterprise SSO & SCIM Provisioning

Available on Business plans: configure OIDC Single Sign-On so your team can sign in through Okta, and enable SCIM 2.0 automated user provisioning to manage team members and role assignments directly from your Okta admin console.

SSO & SCIM Setup Guide →

OAuth Scope Reference

The following table details each OAuth scope requested by Butterfly Security, what it is used for, and whether it supports backup operations, restore operations, or both. For the complete list of available scopes, see Okta’s official OAuth 2.0 API reference.

Core Identity

Scope

Purpose

Resources

okta.users.manage

Read user profiles, status, and metadata for backup. Create, update, activate, deactivate, and delete users during restore.

Users, User Profiles, User Types

okta.groups.manage

Read groups, memberships, and rules for backup. Create, update groups and manage memberships during restore.

Groups, Group Rules, Group Memberships

Applications

Scope

Purpose

Resources

okta.apps.manage

Read application configurations and assignments for backup. Create and configure applications and restore assignments during restore.

Applications, App User Assignments, App Group Assignments

Policies

Scope

Purpose

Resources

okta.policies.manage

Read sign-on, password, MFA, and access policies for backup. Create, update, and activate policies during restore.

Policies, Policy Rules

Authorization

Scope

Purpose

Resources

okta.authorizationServers.manage

Read and restore custom authorization servers, claims, scopes, and access policies.

Authorization Servers, Claims, Scopes, Access Policies

okta.idps.manage

Read and restore external identity provider configurations and routing rules.

Identity Providers, IdP Routing Rules

okta.roles.manage

Read and restore custom admin role definitions and resource sets.

Custom Roles, Resource Sets

Hooks & Integrations

Scope

Purpose

Resources

okta.eventHooks.manage

Read and restore outbound event hook configurations.

Event Hooks

okta.inlineHooks.manage

Read and restore inline hook configurations.

Inline Hooks

Infrastructure

Scope

Purpose

Resources

okta.domains.manage

Read and restore custom domain configurations.

Custom Domains

Schemas & Mappings

Scope

Purpose

Resources

okta.profileMappings.manage

Read and restore attribute mappings between profiles.

Profile Mappings

okta.linkedObjects.manage

Read and restore linked object definitions (e.g., manager relationships).

Linked Objects

Security & MFA

Scope

Purpose

Resources

okta.factors.manage

Read and restore MFA factor configurations and enrollments.

MFA Factors

Audit & Monitoring

Scope

Purpose

Resources

okta.logs.read

Read system log events for compliance reporting and change detection. This is the only read-only scope — there is no okta.logs.manage.

System Log Events

Scope Summary

Total OAuth scopes

13 manage + 1 read-only

Resource categories

Identity, apps, policies, auth, hooks, and more

30+

Resource types backed up

Users, groups, apps, policies, servers, hooks, domains…

Why does Butterfly Security request manage scopes?

Okta .manage scopes include full read access, so a single scope per resource category covers both backup (read) and restore (write) operations. This is why we request .manage rather than separate .read + .manage pairs. The only exception is okta.logs.read, which has no corresponding manage scope.

During backup, Butterfly Security only performs read operations — no data is modified. Write capabilities are only used during explicit administrator-initiated restore operations, which always require manual confirmation and support a dry-run preview mode that shows exactly what will change before any modifications are applied.

Butterfly Security does not access or manage Okta administrator accounts, does not modify configurations outside of restore operations, and does not perform actions beyond identity configuration backup and recovery.

Troubleshooting

Connection test fails

•Verify the Okta Domain, Client ID, and Client Secret match the values from the API Service Integration in Okta.
•Confirm the integration is active in your Okta Admin Console under Applications → API Service Integrations.
•Ensure your Okta org has API Access Management enabled.

Backup returns partial or empty results

•Check that the required OAuth scopes are granted for the resource types you want to back up.
•Verify the Okta admin role assigned to the integration has read permissions for the target resources.
•Review the backup logs in the Butterfly Security dashboard for specific error messages.

Restore operation fails

•Ensure the corresponding .manage scopes are granted for the resource type you are restoring.
•Run a dry-run restore first to identify potential conflicts.
•Check for resource dependencies (e.g., groups must exist before group assignments can be restored).

Support

If you experience issues configuring or using the integration, contact our support team.

Email: support@butterflysecurity.org

Available Monday–Friday, 9am–6pm ET. Response within 1 business day.

Contact Support SSO & SCIM Setup Guide Full Documentation