We're here to help.

Setup and Configuration Guide for ADFS Windows 2016+


  • Contact Butterfly Support to set up your custom logon sub-domain.

    • Example:  https://myhospital.butterflynetwork.com

  • Provide your preferred email address to Butterfly Support to grant you access as an Enterprise Administrator. Only an Enterprise Admin account can access the security configuration settings within Butterfly Cloud.



  1. Log into Butterfly Cloud with your Enterprise Admin account.

    1. Your login page will be at your Butterfly Network Enterprise URL.

  2. Click your user initials in the top right of the window and select Enterprise Settings.

  3. SSO is the first tab, which allows you to configure the Single Sign-On integration with your corporate Identity Provider (IdP) solution.

    1. Examples include: Okta, Imprivata, Microsoft ADFS

  4. It is recommended to keep both Allowed Login Types enabled during the transition period to SSO authentication.

    1. Once you have successfully validated the SSO integration you may disable the ability for users to login with Butterfly Credentials.

  5. Service Provider Details - this information is static for your instance of Butterfly Enterprise. Please enter the provided information when configuring Butterfly Network as an SSO-enabled application in the configuration screen(s) of your Identity Provider’s (IdP) software.


Adding a Relying Party Trust

At this point you should be ready to set up the ADFS connection with your Butterfly Enterprise Cloud. The connection between ADFS and Butterfly is defined using a Relying Party Trust (RPT).

Select the Relying Party Trusts folder from AD FS Management, and click Add Relying Party Trust... from the Actions sidebar. This starts the configuration wizard for a new trust.

  1. Leave Claims aware selected and click Start.

  2. In the Select Data Source screen, select the last option, Enter Data About the Party Manually.

  3. On the next screen, enter a Display name that you'll recognize in the future, and any notes you want to make.

  4. On the next screen, click Next. No encryption certificate is required.

  5. On the next screen, check the box labeled Enable Support for the SAML 2.0 WebSSO protocol. The service URL will be https://sso.butterflynetinc.com/saml2/idpresponse. Note that there's no trailing slash at the end of the URL.

  6. On the next screen, add a Relying party trust identifier of urn:amazon:cognito:sp:us-east-1_DPQCgPjWG

  7. You can configure any access policy you like, we will revisit this later when configuring logout.

  8. Review your configuration, then click Next.

  9. On the final screen use the Close button to exit and open the Claim Rules editor.


Creating Claim Rules

Once the relying party trust has been created, you can create the claim rules and update the RPT with minor changes that aren't set by the wizard. By default the claim rule editor opens once you created the trust.

  1. To create a new rule, click on Add Rule. Create a Send LDAP Attributes as Claims rule.

  2. On the next screen, using Active Directory as your attribute store, do the following:

    1. From the LDAP Attribute column, select E-Mail Addresses.

    2. From the Outgoing Claim Type, select E-Mail Address.

    3. Create a second claim. From the  LDAP Attribute column, select E-Mail Addresses.

    4. In the Outgoing Claim Type, type DomainUser.Email.

    5. Click on Finish to save the new rule.

  3. Create another new rule by clicking Add Rule, this time selecting Transform an Incoming Claim as the template.

  4. On the next screen:

    1. Select E-mail Address as the Incoming Claim Type.

    2. For Outgoing Claim Type, select Name ID.

    3. For Outgoing Name ID Format, select Email.Leave the rule to the default of Pass through all claim values.

    4. Finally, click Finish to create the claim rule, and then Apply to finish creating rules. Click OK to exit the rule wizard.


Configure Logout

  1. To ensure that sessions are removed from both Butterfly and the IdP when a user logs out of Butterfly we will enforce that users provide credentials each time they log in. In the Access Control Policy that you configured in Adding a Relying Party Trust, verify that Require users to provide credentials each time at sign-in is checked.

  2. Butterfly sends signed logout requests, so we will configure a certificate to verify those requests. In the Properties menu for the Relying Party Trust select the Signature tab.

    1. Click Add..

    2. Select the provided Butterfly verification certificate from the filesystem. You may have to change the file type selection dropdown to include All files (.) - the certificate is in PEM format.

    3. Click Apply.

    4. Click OK.

  3. Finally we will configure the logout endpoint to which Butterfly will send logout requests.

    1. In the Endpoints tab, click on Add SAML... to add a new endpoint.

    2. For the Endpoint type, select SAML Logout.

    3. For the Binding, choose POST.

  4. For the Trusted URL, enter:  https://sso.butterflynetinc.com/saml2/logout


Testing Log In


Testing in a Web Browser

  1. Go to your Butterfly Network subdomain address. E.g. https://myhospital.butterflynetwork.com

  2. Select the Login with Company Name Option (Blue Button).

  3. Ensure that you are taken to your corporate IdP login page.

  4. Login with your corporate credentials - you should be automatically taken to Butterfly Cloud upon successful login.

  5. Logout from Butterfly Cloud - you should be taken back to the Butterfly Cloud login page.


Testing in the Mobile App

  1. Open the Butterfly iQ App on your mobile device.

  2. At the login screen - tap the Enterprise User? Log in here option.

  3. On the following screen enter your Butterfly Network subdomain. (e.g. myhospital.butterflynetwork.com).

  4. Select the Login with Company Name Option (Blue Button). Note: If you have enabled MDM Shared Device Rapid Log In this step will be skipped.

  5. Ensure that you are taken to your corporate IdP (mobile) login page.

  6. Login with your corporate credentials - you should be automatically taken to the Butterfly iQ App upon successful login.

  7. Logout from Butterfly iQ App - you should be taken back to the corporate Butterfly iQ App login page.

Was this article helpful?
2 out of 4 found this helpful
Thank you for your feedback

We’re sorry this didn’t answer your question. We’re here to help. Contact us