Auto-Provisioning User Records via Active Directory Integration

Integrating Active Directory to your Butterfly cloud will allow you to auto-provision user records. The auto-provisioning will occur at the point of login for each user. The user will be assigned a Butterfly Access role and organization access based on assignment rules created in Butterfly. 

Prerequisites

The auto-provisioning feature works off of Butterfly’s existing Single Sign On (SSO) integration capabilities. 

• If you have not configured SSO yet, please follow the steps in the Single Sign On (SSO) support article, then return to this article to complete the Active Directory setup. 

• If you have already set up SSO, you’ll need to add a claim rule for “Group ID” to your SSO configuration. If you store the information needed to populate DICOM Field Mapping and Interface Codes in your Active Directory system, you can also create claim rules for these details. For more information on creating claim rules, please visit the guide below that best matches your Active Directory setup:
  • ADFS v 3.0 on Windows 2012
  • ADFS 4.0 Windows 2016+
  • Azure ADFS

Setting up Auto-Provisioning  

The steps that must be completed to enable auto-provisioning are listed below. Not all steps will occur within Butterfly and therefore may not be detailed in this article. Please ensure all steps are completed before toggling auto-provisioning on to ensure users do not experience issues at log in. 

1. Complete SSO Configuration. 
2. Create User Groups in Active Directory and add users to those groups.
3. Build Assignment Rules.
   • Don’t forget to include an assignment rule and AD group for Enterprise Admins. Once auto-provisioning is turned on, all SSO users must have an AD group and corresponding assignment rules to login. 
4. Toggle Active Directory on in Butterfly. 

Building Assignment Rules

Assignment rules are the mechanism that will determine which access role and organization assignment(s) a user will receive at login. Each Assignment Rule can only be mapped to one Group ID. 

To build an assignment rule:

1. Log into your Butterfly cloud.
2. Click your avatar in the upper right corner and select “Enterprise Settings” from the drop down.
3. Navigate to the “SSO & User Sync” submenu.
4. Click the “Auto Provisioning” tab.
5. Click “Add New Rule” on the Assignment Rules table.
   • Note: you do not need to toggle on Auto Provisioning to create Assignment Rules and should not turn the feature on until you have completed all configuration steps
6. Name your Assignment Rule. 
7. Enter the Group Name and Group ID for the Active Directory Group that this assignment rule will be mapped to in the designated fields.
8. Select the Butterfly Access Role and Butterfly Organization(s) members of this Active Directory Group will be assigned upon login.
9. Click Add Rule to save. 
10. Click “Add New Rule” to create another assignment rule. If you need to edit a rule you’ve already created, click “Edit” next to that rule on the Assignment Rules table. 

Once all Assignment Rules have been created and all users have been added to the appropriate groups in Active Directory, you can toggle the auto-provisioning feature on from the Auto Provisioning tab. 

As users log in to Butterfly, they will be provisioned the appropriate roles and organization access. Their user records will then show up on the Enterprise Users table. 

Updating User Access

Once Auto Provisioning is on, user records created via SSO cannot be manually updated. The Assignment Rule/Active Directory Group pairing will be the source of truth for role and organization access assignment. To change a user’s access, they should be moved to a user group with the desired access or you can update the Assignment Rule mapped to that user group to change assignment for the entire user group. 

User records created with the Butterfly log in method can still be manually updated and created once auto-provisioning is enabled.

Deactivating User Records

Deactivating a user in Butterfly will not update the user record in your Active Directory system and vice versa. Disabling the user in either system will prevent the user from logging in. However, we recommend you  remove the user from their Butterfly User Group in Active Directory and deactivate the user in Butterfly to keep both systems in sync.  

To disable a user in Butterfly: 

1. Access the Enterprise User’s submenu within Enterprise Settings
2. Locate the user(s) you’d like to deactivate and check the box next to the user’s email address. 
3. Click “Bulk actions”
4. Select Deactivate Users from the drop down menu. This will move the user to the “Inactivate Users” tab. 

If you need to reactivate a user, you can access their user record from the “Inactive Users” tab. Check the box next to their email address and use the “Bulk actions” button to reactivate the user. 

Recommendations and FYIs

• If your organization utilizes the DICOM Field Mapping and/or Interface Code fields on a user record, we strongly recommend storing this information in your Active Directory system and using auto-provisioning to populate the information on the user’s record. If you choose to not do this, you’ll have to manually update the user record with this information after each user logs in. 

• Once auto-provisioning is enabled, you will not be able to manually create SSO users in Butterfly via single user creation or bulk upload. All SSO user creation must happen via auto-provisioning.