Setting up Automated Provisioning with OKTA

Available for: Enterprise plan
Set up by: Company-level admin

⚠️ The guide provides steps to configure provisioning for Miro Enterprise accounts. For available functionality and rules that Miro SCIM follows please first see here.

Miro's Developer documentation for SCIM can be found here.

In this article: 

Prerequisites

The Miro SCIM API is used by SSO partners to help provision, manage users and teams (groups). SAML based SSO must be properly set up and be functional in your Miro Enterprise account before you start configuring automated provisioning. The instructions on how to set up SSO can be found here. 

When calling the SCIM API, you will need to provide an API Token. Enable the SCIM option in your Security > SSO settings to see the token.

Miro connects your teams and groups by name. This means that the Miro teams that you wish to sync to your Okta groups must first be created in your Miro account and named exactly the same way. Only then you can enable SCIM group updates. 

Configuration

1. On the application settings page, switch to the Provisioning tab. Then click Configure API Integration:
   
   Provisioning tab in the preconfigured Miro app
   
   
2. Set Enable API Integration checkbox and provide Base URL (https://miro.com/api/v1/scim/) and your unique API Token (available in the Security section of your account) in the respective fields. After that click to Test API Credentials.
   If the connection passes the test, you will get the notification saying "Miro was verified successfully": 
   
   Integration tab
   
   If there is no confirmation, double-check the Base URL https://miro.com/api/v1/scim/ and make sure that it is not blocked by firewalls and any other traffic interceptors inside your network, as well as make sure the API Token is correct.
3. Save the configuration.

To App Mappings

Miro SCIM API makes use of a part of metadata OKTA attaches to users and groups. This section explains the required mappings between Miro SCIM API and OKTA attributes.

1. On the application settings page switch to Provisioning > To App tab. Click Edit and enable checkboxes next to Create Users, Update User Attributes and Deactivate Users sections.
   
   Mappings tab in the preconfigured Miro app
   
   

Check that the Username is set to Configured in Sign On Settings: 

Assignments and Push Groups

Miro SCIM provisioning can help you provision to your Miro Enterprise account, as well as automatically distribute them across teams, and deactivate them if need be. 

Groups from OKTA must be assigned to the Miro application (even if the group contains the users that were already assigned as Users directly) and also to be added to Push Groups of the app. 

1) Use Assignments tab to assign groups to the Miro application. All assigned users will be able to authenticate via Miro SSO at this point but will not be placed into any Miro teams. 

2) After that, configure Push Groups to sync your Okta groups to your Miro teams. 

• Choose Push Groups tab on the application settings page, then click Refresh App Groups:
  
  Provisioning tab in the preconfigured Miro app 
  
  This will allow Okta to learn which teams exist in your Miro account to be able to sync to them afterward. It may take a few minutes to download the list of teams depending on their number.
• Click Push Groups > Find groups by name:Setting up pushed groups 
  
  Type-in an OKTA group name in a quick search box and choose it from the auto-suggest list. OKTA will show you the group that has a match to the respective Miro team (according to the previously downloaded list). Linking OKTA groups and Miro teams
  
  If OKTA shows you the option to manually link the group, make sure the Miro team with the name of the group exists on the Miro side. It's best to click Refresh Apps groups again so the system syncs the entities and then retry searching by the group's name. 
• If you have some users already added to your Miro Enterprise account directly instead of being provisioned from Okta, go to the Import tab and click to Import now:
  This will import the information about your existing Miro users to Okta. From there you can choose how to process the imported users:
  
  As a result you will ensure that there are no users mismatched between the systems and thus unable to log in after you enable SSO.
• Save changes and that will be all! You will be shown the list of the groups that are now Pushed to Miro and the status of the synchronization which should be Active (in green). At this point, all the users of the chosen groups will be placed in the respective Miro team and will get access to the boards shared with the team. They will then be continuously updated.

Possible Issues and How to Resolve them

1. Users are not pushed to Miro.
   Please check that the pushed group in Okta is properly assigned to the app. Note that Okta's Active status of the Push Group sync may sometimes be faulty. To solve sync errors try to de-assign the group, remove it from Push Groups, and then recreate the sync connection by assigning the group anew and then adding it to Push Groups again. Even if the setup you have did not change, the process of re-creating the synchronization connection may be required to solve the issues.
2. Users are not being deleted.
   Note that the SCIM processes do not include user deletion. To take away a user's access, deactivate them in OKTA, or de-assign a user from the application on Okta side, which will send a corresponding request to Miro and will set the user to the Deactivated status. To delete a user from Miro, use the Active Users page in Miro.
3. User data are not being updated.
   Please note that the Username attribute should NOT be updated from Application > Assignments:
   Username attribute (as well as other attributes) should be updated from Edit option in the user profile:
   
4. Users do not get provisioned due to "Conflict. Errors reported by remote server: DomainAddress is not whitelisted".
   
   Please make sure that the user's domain address is allowed according to your Sharing policy. 
5. After using the Push Now option some of our boards and projects got reassigned to the Team admins. 
   With this option, Okta initiates a PATCH request to replace all members of your subscription (meaning syncing the list of users in Miro to the user list in Okta). If a timeout occurs until the process is completed Miro is left only with the users available until the timeout happened. Since on Miro end that results in removing the users from your teams, the boards and projects they previously owned are reassigned to respective Team admins.
6. The number of Scanned users provided by the Import Now option does not match the number of users I have in my Miro subscription. 
   Please note that this number does not include Deactivated users and Non-Team users. We also noticed that the results may differ if Okta included some fresh changes that occurred since the last Import (for example, like "1 user removed" change shown on the screenshot below). To get the actual number try running the Import command at least 2 times. 
   
   

7. My users are not updated with some data.
   Please check that all the attributes that you configured, especially if they are custom, like ProfilePicture or UserType are present and filled in on the User profile page: