Available for: Enterprise plan

Set up by: Company-level admin

Deprovisioning and Provisioning using SCIM protocol

System for Cross-domain Identity Management, also known as SCIM, provides automated provisioning and user management for MURAL Enterprise accounts. SCIM will help your team create matching user accounts in all systems that your team needs access to. By adding SCIM to MURAL, we hope to streamline your workflows and help your team grow in MURAL.

⚠SAML based SSO must be properly set up and be functional in your Enterprise account before you start configuring automated provisioning. See the guide to configuring SAML SSO.

Supported Features

Detailed MURAL SCIM schema can be found here

MURAL supports the following provisioning features:

1. GET /Users

  • Get an overview of the members with a MURAL license

2. GET /Users/{id}

  • Check the attributes of a member

3. POST /Users

  • Create a new MURAL account

4. PATCH /Users/{id}

  • Update an existing members’s resource and overwrite values for specific attributes

5. PUT /Users/{id}

  • Update an existing member's resource, overwriting all values for a member

Supported Attributes

In MURAL, each user has their own attributes linked to their MURAL account. Attributes are profile information that a user would typically set in the Profile Details page of their MURAL account. These attributes include the user’s first name, last name and email.

MURAL profile field

SCIM attribute

email

email

name

givenName

surname

familyName

email

userName

/

userType

locked

active

avatar

profileUrl

username

id

Planned Features

The following features are not supported but are planned to be added in the nearest future:

  • Integrations to IdP connectors Okta and AzureAD

  • Linking IdP groups to mural workspaces and moving members between workspaces.

Configuring SCIM API

Here's how to set up SCIM provisioning using the API.

MURAL's SCIM implementation targets the SCIM 2.0 protocol reference.

SCIM API endpoints

The base URL for all calls to MURAL is: https://app.mural.co/api/v0/scim/Users

All SCIM methods are branches of this base URL.

Enable SCIM API endpoints

[ i ] You must be a MURAL company administrator and have SSO enabled to complete the following procedure.

By default, SCIM API endpoints are not enabled. To enable SCIM API endpoints, please contact your MURAL Enterprise Transformation Manager (ETM).

You can verify that SCIM API endpoints are active for your account by stepping through the Generate SCIM API keys process, below.

Generate SCIM API keys

Once SCIM endpoints are enabled, your company administrator can create SCIM API keys. API keys are custom-generated keys that perform Machine to Machine Authentication (M2M) and allow your application to securely talk to our endpoints. You also need an API key when testing an endpoint from our API Reference UI.

Your Company Administrator creates API keys on your Company Dashboard. Each API key has a scope that defines which endpoints that key works with.

To create a SCIM API key, follow these steps:

  1. Log into MURAL as a company administrator.

  2. Click your user profile, then click Company Dashboard.

3. On the left, click API Keys.

4. Click the Create API key button. A list of API scopes is displayed.

5. Select SCIM, then click Create API key. If there is no SCIM option, SCIM API endpoints are not enabled on your account. See Enable SCIM API endpoints.

6. Click Copy key, then click Done.

7. Store the API key in a safe location. To keep your API keys secure, the only time you can see or copy a key is when you’re creating it.

Current limitations

There are a few limitations to the SCIM API implementation, described below.

1. Members can be deactivated (suspended), but not permanently deleted from MURAL.

  • Suspending is done with the PATCH endpoint. DELETE is currently not supported.

  • When a member is suspended, they cannot sign in and will be immediately logged out of open sessions, but their data remains on MURAL as an inactive member. When a suspended member is reactivated (unsuspended) through the SCIM API, the member can access all their previous content in the event that their content has not been transferred to another member before suspension.

  • For more information on suspending and unsuspending MURAL members, see this article.

2. If any profile fields in a custom profile are invalid, all of the fields will be ignored. Carefully review custom profile information before creating new users.

3. Only MURAL members can be provisioned via SCIM, not guests. See Types of Users in MURAL.

4. The last admin in a workspace cannot be suspended through the SCIM API. This action generates a 409 error (conflict).

5. The SCIM API uses rate limiting to prevent server overload. If your app sends more than 25 requests per second, you will receive a 429 error.

6. Filter and sort options for GET endpoints are not currently available. However, you can filter by email address in the GET endpoint to find a member's mural ID, which can then be used with other endpoints.

7. User roles are not available through the SCIM API. For example, if a user has a role of “Admin,” attempting to pass this attribute to MURAL does not enable an Admin account for the user.

Testing environment

Before implementing SCIM in your account, it is highly recommended you test your implementation in a sandbox environment. The SCIM test environment can be accessed using this URL: https://scim.mural.engineering/.

What is included in the test environment?

The test environment is a copy of the production environment but company settings and SSO configurations have not been copied over. Customers will have access to their company with default company settings. Companies’ metadata (e.g. users, workspace, rooms, murals) are NOT copied over. MURAL does not create fake/test users or workspaces on behalf of customers. The customer will be able update their test environment and use the SCIM user endpoints to create test accounts.

Who can access the SCIM API endpoints in the test environment?

Company admins will be able to access the API keys page in their company dashboard in the test environment. More information about accessing the test environment can be found in our dev portal.

Frequently asked questions

What are the benefits of SCIM?

  • SCIM streamlines processes and solves identity maintenance and security challenges - like manual onboarding and offboarding

  • SCIM provisioning is particularly important for growing organizations - especially when considering scalability.

What is the difference between Just in Time provisioning and SCIM provisioning?

  • In the past, MURAL only supported SAML Just in Time provisioning. In this configuration, user accounts are created the first time they successfully log in to MURAL via SAML assertions that pass the attributes required for account creation.

  • SCIM, on the other hand, does not use SAML. Admins can create, update and deactivate accounts from a central place using an API call. For example, if an enterprise uses SCIM and one of their employees quit, an admin can deprovision them in their IdP, and that change will propagate to SCIM-enabled web applications and automatically delete the accounts there, too. JIT provisioning does not provide these capabilities.

  • Both JIT and SCIM can be implemented through a web application single sign-on (SSO) solution, though.

What is the difference between SCIM and SSO?

  • :SSO is a way to authenticate and SCIM is a way to provision.

  • SAML SSO: allow users to use a single sign-on (SSO) identity provider service to log in to MURAL, as opposed to using the default email + password.

    • Requirements: Plus or Enterprise plan

  • SCIM provisioning, allows organizations to use their identity provider service to automate how their users are added to and updated in MURAL

    • Requirements: Enterprise plan

Does SCIM support guest and visitor provisioning?

  • SCIM only supports the provisioning, updating and deactivation of members (not visitors or guests).

Can customers turn off JIT provisioning once they enable SCIM?

  • Yes, customers can turn off JIT provisioning once SCIM is enabled. By default JIT will be turned on. Changing this can be done by request to your MURAL account or support team.

How does SCIM affect collaboration?

  • Collaboration is affected in the event that JIT provisioning is turned off once SCIM is enabled. In that case, members that are trying to access MURAL that have not been provisioned through SCIM will be denied access.

  • We are not stopping users from inviting non-provisioned SCIM users in the product.

Will users provisioned through SCIM receive an email from MURAL?

  • No, when a member has their account created by an admin they will not receive an email.

What does deactivating a user mean and how is it different from deleting a user?

  • Users cannot be permanently deleted from MURAL, they can only be deactivated. If a user is deactivated they will no longer be able to sign in. The session is revoked almost immediately as part of the suspension process. If the user is logged in MURAL at the moment of the suspend, the next action (e.g. click) that they try will kick the user out redirecting to the login page.

  • If a deactivated user tries to access MURAL they will see an error page.

  • The deactivated user's data will remain available for other collaborators. The deactivated user will show up as grayed out with the status ‘Inactive member’ in MURAL.

  • When reactivating a removed user via SCIM, the user will automatically regain access to the same content they had previously in the event the content wasn’t moved over through transfer of ownership.

Do customers need SSO enabled to use SCIM?

  • No, but since this could bring implementation issues on we highly recommend SSO to be set up before a customer implements SCIM.

Do you have thoughts about SCIM? Let us know! You can contact our Support team in the MURAL chat box, or via email at support@mural.co.

Did this answer your question?