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.

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 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. Push Group timeout. "Failed on 06-14-2021 12:16:29PM UTC: Unable to update Group Push mapping target App group <Group Name>: Error while creating user group <Group Name>: Read timed out".
   

   
   This timeout error may appear when attempting to push a group with a large number of members. At this point, you need to check whether Okta's SCIM request timed out before or after the target Miro team was created in Miro. 

   If the target group was not created in Miro, then you need to manually create a team with the same name as your security group and then you can push the group again:
   
   

   
   If the Miro team with the same name is already created in Miro, you need to link it with the group in Okta. To do this you can try the following steps:
   - Unlink pushed group (check Leave the group in target app in modal window):
   
   
   
   
   - Click Refresh App Groups button to let Okta pull the list of groups in Miro:
   
   
   
   - Click Push Groups button and select Find Groups by name option.
   - Find the group you are trying to push by typing its name in the search box and select it from the dropdown. Okta should display it with the Link Group disabled option like so:
   
   
   
   - Click Save. Okta will try to sync target group using PATCH /Groups SCIM requests.