User lifecycle management with SCIM

Any organization that grants access to its services and that uses permissions to control how users engage must manage users and their access. This lifecycle starts when a company onboards its users and continues until they leave the company. Managing users and their access involves various systems and can become challenging.

The increasing use of APIs for nearly every system has enabled organizations to automate the provisioning and management of users, often using the System for Cross-domain Identity Management (SCIM) as a standard. SCIM provides API methods and JSON objects that define users and groups, so identity providers and integration tools can manage users across systems.

This article looks into the Miro SCIM API, its capabilities, and some standard processes to consider when implementing automatic provisioning and management of users in Miro.

Miro SCIM API overview

The Miro SCIM API enables organizations to manage user access automatically. It uses an identity provider, and it includes an interface for other identity providers that support the SCIM protocol. The documentation already features several walkthroughs for configuring an Okta or Azure Active Directory (AD) instance. An Okta or AD instance enables the automatic provisioning of users, and it controls access for teams aligned with the two identity providers.

Additionally, you can call the SCIM API independently for greater control and customization. Independently calling the SCIM API allows middleware to create, update, and delete users or update group membership.

User lifecycle management with the Miro SCIM API

Understanding the information a company uses for onboarding and as users transition into new roles enables you to use your systems and data efficiently. Let's explore some common scenarios organizations encounter when implementing automated user management. We can then understand how the Miro SCIM API can assist with automating the user journey.

Suppose an organization has connected a single sign-on (SSO) capability for Miro logins, but uses an integration platform to perform the SCIM actions. This example demonstrates how to use the API in standard processes, such as onboarding new users, setting permissions, configuring and using groups, handling user role changes, and offboarding users.

New user onboarding

When discussing automated user management, one of the first topics tends to be creating new users in an application. Here, the ideal user experience is one in which account creation provides immediate access to all necessary resources.

For this example organization, when a company adds a new user to the miroUsers group, the integration layer first calls the SCIM Users API to look up the user, using filters to ensure that the user doesn’t already exist in the system. For a user with the email [email protected], the lookup would look like this:

https://miro.com/api/v1/scim/Users?attributes=name,userName&filter=(userName eq "[email protected]")

If the user doesn’t exist, the integration layer calls the create method with the user’s details. This method only requires the username (the Miro email address), a family name, and a given name.
However, you can also include other information, such as department, employee number, or cost center. You can also save the user ID with a property in your user directory to ensure that you have correctly linked the users.

Group modification and creation

The ability to modify team members is another of the Group API’s core features that allow users to access work related to their role. Miro links teams with an underlying security group represented in the SCIM API through the Groups endpoint.

Notably, the Group API doesn’t allow the creation of groups. It only permits retrieving and updating them, because Miro uses two objects linked together: a team for details displayed within the user interface and a group for the security controls accessed through the SCIM API. Consequently, you must use the SCIM API to create groups.

After creating groups, you can use the SCIM API to synchronize them between the two systems, employing a similar process for creating users. You can first look up the group ID using the Groups API and a relevant filter:

https://miro.com/api/v1/scim/Groups?attributes=id&filter=(displayName eq "Engineering Group")

You can then use that ID to update the group’s members by calling the update method with a JSON payload containing the user IDs saved in the previous step. Using the ID enables you to maintain that user in the group automatically.

Additionally, this method helps change the security group’s name in Miro to something other than the team’s name. For example, the security group can use a naming standard, such as g_app_proeng_all.
The update endpoint enables you to change the group’s name to match the security group’s name, while retaining the readability of the team’s name in the user interface.

User data update

As users and their roles change within an organization. You must also make changes to applications and access. Using identifiers to link users and groups to Miro allows you to support many changes to users as their roles change.

Consider Alex Smith, who has just started. When you add Alex to the organization, you create his role and assign it to the Engineering Group by updating the team.
After a few months, Alex joins the IT Administration team as a Miro administrator. You can flag Alex’s account as a Miro administrator in your identity store, and add him to the security groupg_app_itadmin_all, which you have linked to your Miro IT Administration team.

Using the API, you would then:

Add the ORGANIZATION_INTERNAL_ADMIN option to the role attribute using the Users API.
Remove Alex from the g_app_proeng_all group using the Groups API.
Add Alex to the g_app_itadmin_all group using the Groups API.

Chaining these APIs together through these processes enables you to manage virtually every update.

User offboarding and deletion

Finally, when a user leaves your organization or no longer requires Miro, you must clean up their accounts. Of course, you can use the Delete User API to delete the account.
However, in cases where the user no longer requires Miro, or if policies require that user accounts remain, you can also set the user’s status to inactive using the Update user API.

Conclusion

The Miro SCIM API provides all the necessary components for managing your organization’s users through the entire lifecycle. Using existing user information and security groups or roles can make Miro's user and group management almost entirely automated.
Additionally, keeping security groups and Miro teams separate allows you to maintain user-friendly team names within Miro, while ensuring groups use a consistent naming scheme.

To see the full benefits of Miro for collaboration and diagramming, visit Miro and get started for free.