Butterfly Security/

SSO & SCIM Configuration Guide

Install the Butterfly Security app from the Okta Integration Network and configure Single Sign-On and SCIM 2.0 provisioning for your team.

SSO (OIDC)SCIM 2.0EntitlementsUniversal LogoutAll Plans

Overview

The Butterfly Security app is available in the Okta Integration Network (OIN) and provides both Single Sign-On (OIDC) and SCIM 2.0 provisioning in a single integration. Once installed, your team members can sign in to Butterfly Security through Okta — no separate passwords needed — and user accounts are automatically created, updated, and deactivated as your Okta directory changes.

SSO and SCIM are included on all plans. This integration has its own Client ID and Client Secret, separate from the API Service Integration used for backup and recovery. The SSO/SCIM app handles authentication and provisioning, while the API Service Integration handles backup API access.

What You Get

Single Sign-On (OIDC)

Team members sign in through Okta using their existing credentials. No separate Butterfly Security password required.

Automated Provisioning (SCIM)

Create, update, and deactivate users automatically in Butterfly Security when your Okta directory changes.

Role-Based Entitlements

Five built-in roles exposed as SCIM entitlements. Assign roles via the SCIM roles attribute for automated access control.

Universal Logout (CAEP)

Back-channel logout support ensures sessions are revoked immediately when an admin removes access in Okta.

Prerequisites

Okta Requirements

  • Okta Super Administrator or Application Administrator role
  • Permissions to install OIN integrations

Butterfly Security Requirements

  • An active Butterfly Security account (any plan)
  • Team Super Admin role (required to configure SSO/SCIM)

Part 1: Install the Butterfly Security App

OIN
1

Add Butterfly Security from the OIN

  1. Sign in to your Okta Admin Console.
  2. Navigate to Applications → Applications.
  3. Click Browse App Catalog.
  4. Search for Butterfly Security.
  5. Click Add Integration.
  6. On the General Settings page, review the defaults and click Done.
2

Copy the Client ID and Client Secret

  1. Open the Butterfly Security app and go to the Sign On tab.
  2. Under Sign on methods, you will see OpenID Connect.
  3. Copy the following values:
    Client ID: 0oa...
    Client Secret: Click the copy icon to reveal

Separate from API credentials: This SSO/SCIM integration uses its own Client ID and Client Secret, different from the API Service Integration. You will find these values in the Okta Admin Console under the SSO/SCIM app's Sign On tab.

Part 2: Configure Single Sign-On

OIDC
1

Configure SSO in Butterfly Security

  1. Sign in to Butterfly Security at butterflysecurity.org.
  2. Navigate to Dashboard → Settings → SSO & SCIM.
  3. Enter the Issuer URL for your Okta authorization server:
    Issuer URL: https://your-org.okta.com

    Find this under Security → API → Authorization Servers in the Okta Admin Console.

  4. Enter the Client ID and Client Secret from Part 1.
  5. In the Email Domains field, enter the email domain(s) for your organization:
    Email Domains: yourcompany.com, subsidiary.com

    Comma-separated. Users with these email domains will be automatically redirected to SSO at login.

  6. Click Enable SSO.
2

Test SSO Login

  1. Open an incognito/private browser window.
  2. Go to butterflysecurity.org/login.
  3. Enter an email address with one of your configured domains.
  4. You should be redirected to your Okta sign-in page.
  5. Sign in with your Okta credentials.
  6. You should land on the Butterfly Security dashboard.

First-time users: Users who sign in via SSO for the first time are automatically added to your team with the read_only role. You can change their role in team settings or automate it with SCIM entitlements.

Supported SSO Features

SP-initiated SSO — Users can start the sign-in flow from the Butterfly Security login page
IdP-initiated SSO — Users can launch Butterfly Security from the Okta dashboard
Just-in-Time (JIT) provisioning — User accounts are automatically created on first SSO login
Universal Logout (CAEP) — Back-channel logout revokes sessions when access is removed in Okta

SP-Initiated SSO

SP-initiated SSO allows users to start the sign-in flow from the Butterfly Security login page rather than from Okta.

  1. Navigate to butterflysecurity.org/login.
  2. Enter your email address (e.g., user@yourcompany.com).
  3. Butterfly Security detects that your email domain is configured for SSO and redirects you to your Okta sign-in page.
  4. Authenticate with your Okta credentials (password, MFA, etc.).
  5. After successful authentication, you are redirected back to the Butterfly Security dashboard.

How domain detection works: When SSO is configured, the admin specifies one or more email domains (e.g., yourcompany.com). Any user who enters an email with a matching domain at the Butterfly login page is automatically redirected to the configured Okta authorization server for authentication.

Supported SCIM Features

Create Users — Provision new users in Butterfly when assigned in Okta
Update User Attributes — Sync profile changes from Okta to Butterfly
Deactivate Users — Deactivate users in Butterfly when unassigned in Okta

Not supported: Import New Users, Import Profile Updates, Group Push, and Sync Password are not supported. Butterfly Security is not a profile source — user profiles are always sourced from Okta and pushed to Butterfly. Role assignment is handled via SCIM entitlements (the roles attribute) rather than group push.

Part 3: Configure SCIM Provisioning

SCIM 2.0
1

Generate a SCIM Bearer Token

Before enabling provisioning in Okta, you need to generate a bearer token in Butterfly Security.

  1. In Butterfly Security, navigate to Dashboard → Settings → SSO & SCIM.
  2. Scroll to the SCIM 2.0 Provisioning section.
  3. Click Generate SCIM Token.
  4. Copy the raw token immediately. It is only displayed once and cannot be retrieved later. When pasting into Okta, enter the raw token only — Okta automatically prepends the "Bearer" prefix to the authorization header.
    Token format: bfs_scim_xxxxxxxxxxxxxxxxxxxxxxxx

Important: The SCIM bearer token is shown only once. If you lose it, you must click Rotate Token to generate a new one, then update the token in Okta.

2

Enable Provisioning in Okta

  1. In the Okta Admin Console, open the Butterfly Security app.
  2. Go to the Provisioning tab.
  3. Click Configure API Integration.
  4. Check Enable API Integration.
  5. In the API Token field, paste the token you generated in Step 1.
  6. Click Test API Credentials to verify connectivity.
  7. Click Save.
3

Enable Provisioning Features

  1. On the Provisioning tab, click To App in the left sidebar.
  2. Click Edit.
  3. Enable the following supported operations:
    Create Users — New Okta users assigned to the app are provisioned in Butterfly
    Update User Attributes — Profile changes in Okta sync to Butterfly
    Deactivate Users — Removing app assignment deactivates the user in Butterfly

    Not supported: Import New Users and Import Profile Updates are not supported. Butterfly Security does not act as a profile source — user profiles are always sourced from Okta and pushed to Butterfly, not the other way around.

  4. Click Save.
4

Assign Users

  1. Go to the Assignments tab in the Butterfly Security app in Okta.
  2. Click Assign → Assign to People or Assign to Groups.
  3. Select the users or groups you want to provision in Butterfly Security.
  4. Click Save and Go Back and then Done.

userName format: Butterfly Security requires the userName attribute to be a valid email address (e.g., user@example.com). Ensure that Okta's userName value for the app matches the user's primary email address.

Role Permissions Matrix

Each role controls what a team member can do in the Butterfly Security dashboard. Roles are assigned via SCIM entitlements, entitlement governance, or manually in team settings.

Permission
Super Admin
Admin
Backup Op
Auditor
Read Only
Team
Manage team settings
Manage billing
Configure SSO/SCIM
View team members
Connections
Create & manage connections
Test connections
View connections
Backups
Run backups
View backup list
View backup contents
Download backups
Delete backups
Restore
Restore from backup
Compliance
View compliance reports
Export reports
Settings
Edit backup schedules
Manage integrations (Git, Terraform)
super_admin

Full access including team management, billing, and SSO/SCIM configuration.

admin

Manage connections, run backups, restore, and view compliance reports.

backup_operator

Run backups, test connections, edit schedules, and view reports.

auditor

Read-only access to backups, compliance, and reports. Cannot modify.

read_only

View connections and backup list only. Cannot view backup contents.

SCIM Attribute Mapping

The following attributes are mapped from Okta to Butterfly Security user profiles.

SCIM Attribute
Butterfly Field
Required
Notes
userName
Email address
Yes
Must be a valid email address (e.g., user@example.com). Used as the unique login identifier. Okta's userName value must match the user's primary email.
name.givenName
First name
No
Maps to the user's first name in their Butterfly Security profile.
name.familyName
Last name
No
Maps to the user's last name in their Butterfly Security profile.

Custom role assignment: To assign roles during provisioning, use the Butterfly extension schema in your SCIM payloads:

"urn:ietf:params:scim:schemas:extension:butterfly:2.0:User": {
"butterflyRole": "admin"
}

Troubleshooting

SSO redirect fails or returns an error

  • •Verify the Issuer URL is correct and points to a valid OIDC authorization server (e.g., https://your-org.okta.com).
  • •Confirm the Client ID and Client Secret match the values from the Sign On tab in Okta.
  • •Ensure the email domain(s) configured in Butterfly match the user's email address domain.
  • •Check that the user is assigned to the Butterfly Security app in Okta (Assignments tab).

SCIM provisioning fails or users are not created

  • •Verify the SCIM Bearer Token has not been revoked. Click Rotate Token if needed.
  • •Confirm the SCIM Base URL is exactly: https://butterflysecurity.org/api/scim/v2
  • •Check that the Authentication Mode in Okta is set to HTTP Header (not Basic Auth).
  • •Use the Okta provisioning logs (Provisioning tab → View Logs) to see detailed error messages.

Users are provisioned but assigned the wrong role

  • •Verify the SCIM roles attribute is set correctly. The value must be one of: super_admin, admin, backup_operator, auditor, read_only.
  • •Newly provisioned users default to read_only if no role is specified in the SCIM payload.
  • •Check the user's profile in Butterfly Security Settings → Team Members to verify the assigned role.

Back-channel logout is not revoking sessions

  • •Verify the Logout section on the Sign On tab shows 'Okta system or admin initiates logout'.
  • •The Back-channel Logout URI should be: https://butterflysecurity.org/api/logout/global
  • •Check that the logout token issuer matches the SSO Issuer URL configured in Butterfly.

Support

If you experience issues configuring SSO or SCIM provisioning, contact our support team.

Email: support@butterflysecurity.org

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

Contact SupportAPI Service Integration GuideFull Documentation