Setting up automated provisioning with Azure AD

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

⚠️ The guide provides steps to configure provisioning for Miro Enterprise accounts. For available functionality, rules that Miro SCIM follows and possible issues and how to resolve them 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. 

Your security groups and Miro teams must already be created and named the same way. 

Setting up Provisioning

Once the application is created during SSO configuration, you will see its settings:

1. Choose the Provisioning item on the left panel and then change Provisioning Mode from Manual to Automatic:
2. Provide Admin Credentials:
   a) Use https://miro.com/api/v1/scim/ as Tenant URL
   b) Provide the Secret Token. You can obtain it from the SSO section of your Miro settings like so:
   
   c) Click Test Connection button right below the Secret Key edit box.
   If the connection passes the test, you will get the following notification:
   If there is no confirmation, double-check the Tenant URL 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:
   

Mappings

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

Users

1. Choose the Provisioning tab on the left side, then click Synchronize Azure Active Directory Users to Miro:
   
   
2. Default mappings are expected to be enough. However, double-check that synchronization is enabled for users and all required methods (Create, Update, Delete) are ON:
   

Please note that Miro will recognize Azure users by their UPNs. 

Note that to be able to map a new attribute you should enable this option by accessing Azure with the following URL:

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

For further information about adding new attributes please visit Microsoft documentation here and here. 

Groups

1. Choose the Provisioning tab on the left, then click Synchronize Azure Active Directory Groups to Miro.
2. Default mappings are expected to be enough. Check that synchronization is enabled for groups and uncheck Create and Delete methods - note that Miro SCIM API does not support creating and deleting teams.
   ⚠️ We strongly recommend unchecking the methods to prevent unplanned changes when we start supporting the methods. 
   
3. Click Save.

User and Group Assignments

Miro SCIM Provisioning can help you to provision and de-provision users to your Enterprise account, as well as to automatically distribute them across teams. Users or Groups from Azure Active Directory should be assigned to Miro SCIM Provisioner application to be automatically managed in Miro. To assign users and groups to the application, follow the steps below.

We recommend provision users through assigning groups. In that case, when user is removed from all assigned groups in Azure AD, the same user will be removed from all teams in Miro (note that they will still stay a member of the Enterprise account). To deactivate a user in your Enterprise account, deactivate them in Azure AD, which will send a corresponding request to Miro. To delete a user from Miro, use the Active Users page in Miro.

1. Choose Provisioning tab on the left. In the Settings section make sure the scope is set to the one you expect to be synced with Miro. Please choose "Sync only assigned users and groups".
2. Choose User and groups tabs on the left panel, then click Add user:
   
3. On the Add assignment screen, choose Users and groups tab, then select users and groups from the list. NOTE: Miro SCIM API does not create new teams in Miro. Please see the SCIM features list here. 
4. Click Select, then Assign buttons.
5. Assigned users and groups will appear in the list.

Enabling and disabling provisioning

When the initial set up is complete, switch Provisioning Status toggle to enable the provisioning.

1. Choose Provisioning tab on the left.
2. Click On option on the Provisioning Status toggle.
   
   
3. Hit Save. This will start the initial provisioning that might take some time. Go back in about 20 minutes and check the bottom of the page for the status.

Whenever needed, choose the Off option to disable the provisioning. Note that Azure updates the data intermittently so if you need an urgent update, Stop the provisioning and then Start again. Resync will be immediate and will also carry with it the updates. 

Decoupling Groups and Teams

To enable SCIM and sync your groups to your Miro teams they must be named the same way because Miro performs the sync based off the name value. However, if you need to have them named differently you can change the names of either of them after the sync is performed. Please see the example below. 

The planned result: in Azure there is a Group named sfo_hq_eng_support while in Miro there is a Team named Engineering Support and the sync is performed between the two.

Run the curl command to list all Security Groups:

curl \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SCIM_API_TOKEN" \
-X GET https://miro.com/api/v1/scim/Groups

Sample response:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "3074457345618261605",
      "displayName": "YourMiroTeamName",
      "members": [],
      "meta": {
        "resourceType": "Group",
        "location": "https://miro.com/api/v1/scim/Groups/3074457345618261605"
      }
    }
  ]
}

At this moment in Miro there exist the Miro team called Engineering Support and the Miro Security group Engineering Support (with id 3074457345618261605). They are mapped 1:1.

The goal now is to modify the name of the Security Group Engineering Support to sfo_hq_eng_support while keeping the Team name unchanged. To achieve that run the curl command:

curl \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SCIM_API_TOKEN" \
-X PATCH https://miro.com/api/v1/scim/Groups/3074457345618261605 \
-d '{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Replace",
      "path": "displayName",
      "value": "YourSecurityGroupName"
    }
  ]
}'

This change will be immediately displayed on the Miro Company teams page.

Azure performs the background scheduled synchronization every 40 minutes. With the next sync Azure will see the sfo_hq_eng_support Security Group in Miro and will automatically link it with the respective Group in Azure.

At this point you have connected your Security Group to one of your Miro teams and have them named differently.