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. 
• 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. If you're seeing that the 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. 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. Please note that Username attribute should NOT be updated from Application > Assignments:
4. Username attribute should be updated from Edit option in the user profile:
5. Users do not get provisioned due to an allowlist error
   
   Please make sure that the user's domain address is added to your allowlist in the Security settings.