Setting up automated provisioning with OKTA

This guide walks you through configuring automated user and user group provisioning between Okta and your Miro Enterprise account using SCIM.

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

⚠️ This guide covers configuration steps only. For supported functionality, sync rules, and troubleshooting, see the SCIM overview. For the SCIM API reference, see the developer documentation.

Note: SCIM Groups configured through this integration sync directly to Miro user groups, not teams. See New synchronization model for details.

If your organization uses the Flexible Licensing Program, see our detailed provisioning guide for that setup instead.

Prerequisites

Before you configure automated provisioning, complete the following:

• Set up and confirm that SAML-based SSO is working in your Miro Enterprise plan. See Configure Okta SSO for instructions.
• Generate an API token. The SCIM API requires one for every request. Enable SCIM in Enterprise Integrations > SSO > SCIM settings to generate a token.
• Review Important to know and Rules under which Miro operates in the SCIM overview to avoid connection errors during sync.

Configuration

Connect Okta to Miro's SCIM API so Okta can authenticate its provisioning requests.

1. On the application settings page, switch to the Provisioning tab, then click Configure API Integration:
   
   Provisioning tab in the preconfigured Miro app
2. Select the Enable API Integration checkbox, then enter the Base URL (https://miro.com/api/v1/scim/) and your unique API Token (available in the Security section of Miro settings), then click Test API Credentials.
   If the connection succeeds, you'll see the notification "Miro was verified successfully":
   
   Provisioning tab, Integration section
   If you don't see the confirmation, check that Base URL https://miro.com/api/v1/scim/ isn't blocked by firewalls or other traffic interceptors on your network, and confirm the API Token is correct.
3. Save the configuration.

Map user attributes

Miro's SCIM API uses a subset of the metadata Okta attaches to users and groups. This section covers the required mappings between the Miro SCIM API and Okta attributes.

1. On the application settings page, switch to the Provisioning > To App tab. Click Edit, then select the checkboxes next to Create Users, Update User Attributes, and Deactivate Users:
   
   To App tab in the preconfigured Miro app
2. Scroll down and confirm that Username is set to Configured in Sign On Settings:
   
   Attribute mappings tab in the preconfigured Miro app
3. To add a supported attribute, click Go to Profile Editor, then select Add Attribute:
   
   The list of active attributes in the Profile editor
   

See our SCIM documentation for the full list of supported attributes.

Assign users and sync groups

Miro SCIM provisioning lets you provision users to your Miro Enterprise plan, automatically distribute them across user groups, and deactivate them when needed.

⚠️ Groups from Okta must be assigned to the Miro application, even if their users are already assigned individually, and then added to the app's Push Groups. Both steps below are required.

Step 1: Assign groups

Use the Assignments tab to assign groups to the Miro application. Assigned users can authenticate via Miro SSO at this point, but aren't placed into any Miro user groups yet.

Step 2: Configure Push Groups

Configure Push Groups to sync your Okta groups to your Miro user groups.

1. Choose the Push Groups tab on the application settings page, then click Refresh App Groups:
   
   Push groups in the preconfigured Miro app
   This lets Okta discover the user groups in your Miro subscription so it can sync to them. Downloading the list may take a few minutes, depending on how many user groups you have.
2. Click Push Groups > Find groups by name:
   
   Setting up pushed groups
   Type an Okta group name into the search box and choose it from the autosuggest list. Okta shows the group that matches the corresponding Miro user group, based on the list you downloaded in the previous step:
   
   Linking Okta groups and Miro user groups
   If no matching Miro user group exists, select Create Group. Okta creates the Miro user group for you, so you don't need to pre-create user groups in Miro.
3. If some users were already added to your Miro Enterprise plan directly instead of through Okta, go to the Import tab and click Import now. This imports your existing Miro users into Okta, where you can choose how to process them:
   
   This ensures there are no mismatched users between the two systems, which could otherwise prevent someone from logging in after you enable SSO.
4. Save your changes. You'll see the list of groups now pushed to Miro, along with their sync status, which should show as Active (in green). All users in the chosen groups are placed in the corresponding Miro user group and kept in sync going forward.

Board and Space access isn't automatic through user group membership. Share the relevant boards and Spaces with the user group, or its individual members, separately to grant access.

Troubleshooting

1. Users are not pushed to Miro.
   Check that the pushed group in Okta is properly assigned to the app. Okta's Active status for the Push Group sync can sometimes be inaccurate. To resolve sync errors, de-assign the group, remove it from Push Groups, then reassign the group and add it back to Push Groups. Recreating the sync connection can resolve the issue even if nothing else changed.
2. Users are not being deleted.
   The SCIM processes don't include user deletion. To remove a user's access, deactivate them in Okta, or de-assign them from the application on the Okta side. Either action sends a request to Miro that sets the user to Deactivated status. To delete a user entirely, see our guide on how to delete a user.
3. User data are not being updated.
   The Username attribute should NOT be updated from Application > Assignments:
   
   Update the Username attribute, along with other attributes, from the Edit option in the user profile:
   
4. Users do not get provisioned due to "Conflict. Errors reported by remote server: DomainAddress is not whitelisted".
   
   Make sure the user's domain address is allowed under your Sharing policy.
5. After using the Push Now option, some users were unexpectedly removed from a user group.
   With this option, Okta initiates a PATCH request to replace all members of the user group, meaning it syncs the list of users in Miro to the user list in Okta. If a timeout occurs before the process completes, Miro is left only with the users available until the timeout happened, and the remaining users are removed from the user group. Removing a user from a user group only affects that user group's membership: it doesn't remove the user from any team or from the organization, and it doesn't transfer board or project ownership, so this operation doesn't reassign content. If you notice missing members after a Push Now operation, retry the sync to apply the full user list.
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.
   This number doesn't include Deactivated users or Non-Team users. Results may also differ if Okta includes recent changes since the last import (for example, a "1 user removed" change, as shown below). Run the Import command at least twice to get an accurate count.
   
7. My users are not updated with some data.
   Check that all configured attributes, especially custom ones like ProfilePicture or UserType, are present and filled in on the User profile page:
   

8. The changes are not sent to Miro due to Link / 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 linking existing groups or pushing a new group with a large number of members.

   If you were pushing a new group, check whether Okta's SCIM request timed out before or after the target group was created in Miro. If the target group wasn't created in Miro, retry the "Push Group" operation:
   

   If you were linking existing groups, or the target group was created in Miro after the initial push operation, restore the link between the groups in Okta and Miro:

   1. Unlink the pushed group (check Leave the group in target app in the modal window):
      
      
   2. Click Refresh App Groups to let Okta pull the list of groups in Miro:
      
   3. Click Push Groups, then select Find Groups by name.
   4. Find the group you're trying to push by typing its name in the search box and selecting it from the dropdown. Okta displays it with the Link Group option disabled, like this:
      
   5. Click Save. Okta syncs the target group using PATCH /Groups SCIM requests.
   6. If not all the members from the Okta group were assigned to the corresponding user group in Miro, check the "Directory → Tasks" tab in Okta and retry the failed operations: