Setting up automated provisioning with Entra ID

This guide walks you through configuring automated user and user group provisioning between Entra ID 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 Entra ID SSO for instructions.
• Review Important to know and Rules under which Miro operates in the SCIM overview to avoid connection errors during sync.

Configuration

Connect Entra ID to Miro's SCIM API so it can authenticate its provisioning requests. Once the application is created during SSO configuration, you'll see its settings:

Miro application settings

1. Choose Provisioning in the left panel, then change Provisioning Mode from Manual to Automatic.
2. Provide your admin credentials:
   • Use https://miro.com/api/v1/scim/ as the Tenant URL.
   • Enter the Secret Token, available in the SSO section of your Miro settings.
   • Click Test Connection, below the Secret Key field. If the connection succeeds, you'll see this notification:
     
     Successful connection test notification
     If you don't see the confirmation, check that the Tenant URL isn't blocked by firewalls or other traffic interceptors on your network, and confirm the API Token is correct.
3. Save the configuration:
   
   Saving the configuration

Map attributes

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

Users

1. Choose the Provisioning tab, then click Synchronize Entra Active Directory Users to Miro:
   
   Enabling synchronization
2. The default mappings should be enough for most cases. Confirm that synchronization is enabled for users and that all required methods (Create, Update, Delete) are on:
   
   Attribute mapping

Miro recognizes Entra users only by their UPNs for the SP-initiated flow.

To add a supported attribute, click Show advanced options, then select Edit attribute list for Miro:

Advanced options

Enter the attribute name you want to map and save it. See our SCIM documentation for the full list of supported attributes.

Miro user attributes

Choose Add New Mapping and select the new attribute you just added:

To map a new attribute, first enable this option by accessing Entra with the following URL:

https://portal.azure.com/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true

For more information on adding new attributes, see Microsoft's documentation on customizing application attributes and creating an extension attribute.

⚠️ The ProfilePicture attribute isn't supported by Entra. You can request this feature on User Voice to help prioritize its development.

Groups

1. Choose the Provisioning tab, then click Synchronize Entra Active Directory Groups to Miro.
2. Confirm that synchronization is enabled for groups, then choose whether to enable Create and Delete:
   
3. Click Save.

⚠️ Miro's SCIM API now supports creating and deleting user groups. If you enable Create, Entra automatically creates the corresponding Miro user group the first time you assign a matching group to the app, so you don't need to pre-create user groups in Miro. If you enable Delete, removing a group's assignment in Entra deletes the corresponding Miro user group, so enable it only if that's the behavior you want. If you'd rather manage user group creation and deletion manually, leave both unchecked.

Assign users and groups

Miro SCIM provisioning lets you provision and deprovision users in your Enterprise subscription, and automatically distribute them across user groups.

Users or groups from Entra Active Directory must be assigned to the Miro SCIM Provisioner application to be automatically managed in Miro. To assign users and groups to the application, follow these steps:

1. Choose the Provisioning tab. In the Settings section, confirm the scope is set to match what you expect to sync with Miro. Choose Sync only assigned users and groups.
2. Choose the Users and groups tab, then click Add user:
   
   User and groups tab
3. On the Add assignment screen, choose the Users and groups tab, then select users and groups from the list. If you haven't enabled Create for group sync, make sure a matching Miro user group already exists before assigning it here.
4. Click Select, then Assign.
5. Assigned users and groups appear in the list.

✏️ Removing a group's assignment in Entra ID doesn't remove its users from the synced user group in Miro, and doesn't deactivate them. To fully deprovision a user, remove them from all Entra ID groups connected to Miro.

Downgrading a user

To downgrade a user, follow these steps:

1. In Entra ID:
   1. Remove the user from the group where the Full app role is assigned.
   2. Confirm the user is a member of another group where the User role is assigned.
2. In Miro, update their license to Free Restricted.

⚠️ If you remove a user from all Entra ID groups assigned to the Miro application, Miro deactivates them and they lose access to the application. If a downgraded user needs to keep accessing Miro with a Free Restricted license, make sure they remain a member of an Entra ID group where the User role is assigned.

✏️ Downgrading a user from a Full to a Free Restricted license via SCIM provisioning isn't supported yet.

Enabling and disabling provisioning

Once initial setup is complete, enable provisioning:

1. Choose the Provisioning tab.
2. Set the Provisioning Status toggle to On:
   
   Provisioning status
3. Click Save. This starts the initial provisioning, which can take some time. Check back in about 20 minutes and look at the bottom of the page for the status.

To disable provisioning, set the toggle to Off. Entra updates data intermittently, so if you need an urgent update, stop provisioning and then start it again. The resync is immediate and includes any pending updates.

Troubleshooting

Issues with changing user emails

If you updated a user's email but don't see the change on the Miro end, confirm which attribute was updated. This issue usually comes up when using emails[type eq "work"].

emails[type eq "work"] is a default attribute in Entra, and Miro does support it, but only as a read-only field that's dynamically generated from userName. When reading users, Miro returns:

Because emails[type eq "work"] is read-only on Miro's end, Miro ignores any attempts to modify it. In Miro, a user's email is their primary ID, the identifier used to recognize them, so Miro doesn't support additional emails. The SCIM structure requires an email array, so Miro supports its existence, just not as an editable field.

To modify a user's email, send the update to userName, not emails[type eq "work"]:

Failed to update user error

Entra logs show a Failed status with:

Status Reason: "Failed to update user: Attribute emails does not have a multi-valued or complex value"
Error Code: SystemForCrossDomainIdentityManagementServiceIncompatible