Butterfly SSO Setup Guide (SAML 2.0)

This guide walks you through connecting your Identity Provider (Okta, Azure AD, PingFederate, Workday, etc.) to Butterfly for single sign-on.

Part 1: Configure Your Identity Provider (Your Environment)

1. Create a SAML integration for Butterfly in your IdP's third-party SSO setup for external applications.
2. Enter Butterfly's Sign on URL into your IdP: https://<subdomain>.butterfly.ai/saml/callback?provider=<provider-name>
   • Replace <subdomain> with your chosen Butterfly.ai subdomain (If your account has not been created yet, please refer to the Account Setup guide
   • Pick a <provider-name>, if you have multiple SSO providers, make sure this is a unique value
3. Enter SP Entity ID / Audience URL: https://butterfly.ai/saml/metadata
4. Set the NameID format to Email Address, mapped to each user's primary work email — this is how Butterfly matches the login to an existing account.
5. Generate your IdP's SAML metadata. You'll need the following for Butterfly:
   • IdP SSO URL
   • SP Entity ID (your IdP's entity ID/issuer for this integration)
   • Public X.509 signing certificate
6. Confirm assertions (and optionally the full authentication response) are signed with this certificate before exporting.

Part 2: Configure Butterfly (Authentication Page)

Using the values gathered in Part 1, fill in the following:

1. SAML Provider Identifier
A short internal name for this connection (letters, digits, underscore, and dash only — e.g. okta-sso).

2. SAML SSO URL
Enter https://<subdomain>.butterfly.ai/saml/callback?provider=<provider-name>
Replace the <> values with the information from part 1

3. SP Entity ID (currently labeled "Identity Provider Issuer" in the UI)
Enter this value here: https://butterfly.ai/saml/metadata

4. Public Certificate
Paste the full X.509 certificate from your IdP, including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

Then choose your signing options:

• Assertions are signed using this certificate — recommended, checked by default.
• Authentication Response is signed using this certificate — enable if your security policy requires signing the full response, not just the assertion.
• Allow non-password authentication methods (PIN, Face ID, etc.) — optional, enable if your IdP supports it and you want to allow it.
• Force re-authentication — enable if you want users to always re-enter IdP credentials when logging into Butterfly, even with an active IdP session.

5. Login User Interface

• Set the custom text for your SSO login button (defaults to "SSO Login").
• Optionally check Disable Password Login to enforce SSO-only access. Recommend leaving unchecked until testing is complete.

6. User Resolution

• By default, Butterfly matches users by email address. Leave as-is unless you have a specific reason to use custom logic.
• If your IdP email doesn't reliably match Butterfly usernames (aliases, domain differences, etc.), use Add Custom User Resolution Rule to define matching logic instead.

Part 3: Test Before Enforcing

1. Test with one or two pilot users first — do not check Disable Password Login yet.
2. Confirm login succeeds through the SSO button and (if supported) directly from your IdP's app launcher.
3. Verify the user lands in Butterfly correctly matched to their existing account.
4. Once confirmed, optionally enable Disable Password Login to require SSO for all users.

Troubleshooting

• Login fails immediately — double check the SP Entity ID and SAML SSO URL are pasted exactly, with no extra whitespace.
• Certificate errors — confirm the full certificate block was pasted, including header/footer lines.
• User not found — check that the NameID email in your IdP matches the user's email in Butterfly, or set up a custom user resolution rule.