Skip to main content
/

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.

Install from the Okta Integration Network
SSO (OIDC)SCIM 2.0EntitlementsUniversal Logout (Partial)All Plans

Overview

The Butterfly Securityapp 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 available on the Business plan. 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 (Partial)

Back-channel logout revokes refresh tokens immediately when an admin removes access in Okta. Existing access tokens expire within 1 hour (3600s default lifetime).

Prerequisites

Okta Requirements

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

Butterfly Security Requirements

  • An active Butterfly Security Business account
  • 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 (Partial) — Back-channel logout revokes refresh tokens immediately; access tokens expire within 1 hour

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.

Universal Logout (Back-Channel)

Butterfly Security supports partialUniversal Logout via OpenID Connect Back-Channel Logout. When an Okta admin terminates a user’s access, Okta POSTs a signed logout token to our endpoint and we immediately invalidate the user’s refresh tokens. Any issued access token remains valid until it expires.

Our Back-Channel Logout URI

https://butterflysecurity.org/api/logout/global

This is the endpoint Okta calls on admin-initiated session termination, password reset, or risk detection. It validates the JWT logout token against the configured SSO issuer, resolves the user by OIDC subject or email, and calls a global sign-out on the user’s session.

Logout behavior (partial support)

  • Refresh tokens revoked immediatelyon receipt of a valid logout token — the user cannot extend their session.
  • Access token lifetime: 3600 seconds (1 hour)— in-flight access tokens remain valid until they reach TTL, at which point refresh is blocked and the session fully ends.
  • Worst-case re-access window: ≤ 1 hour from the moment Okta calls the endpoint, after which the user is fully signed out across every device and session.

Enabling Universal Logout on your Okta tenant

  1. In Okta, follow the official enablement guide: Configure Universal Logout for an app
  2. On the Butterfly Security app’s Sign On tab, ensure the Logoutsection reads “Okta system or admin initiates logout.”
  3. Set the Back-Channel Logout URI to https://butterflysecurity.org/api/logout/global
  4. Confirm the SSO Issuer URLconfigured in Butterfly Security’s team settings matches the issuer Okta signs its logout tokens with — token signature verification fails silently otherwise.
  5. Test by signing a user into Butterfly, then revoking their Okta session via “Clear user sessions” in the admin console. Refresh tokens are killed on the POST; access token TTL drains the remainder.

Why partial and not full: Butterfly Security uses short-lived JWT access tokens (Supabase Auth). JWTs are stateless by design, so an access token issued 30 seconds before the revocation call remains valid until its 1-hour TTL. Revoking refresh tokens immediately is the canonical pattern for short-TTL OIDC architectures and matches the Back-Channel Logout 1.0 spec’s guidance for stateless-session relying parties.

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 Updatesare 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.

Using Okta Identity Governance Entitlement Management? Entitlement Management must be enabled on your Okta tenant before you can use it to assign Butterfly Security roles to users. Follow the official Okta enablement guide: Enable Entitlement Management. Once enabled, map Butterfly Security roles (see the matrix above) to entitlements in your governance catalog and assign them through access requests, access certifications, or automated provisioning policies.

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.

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