# Microsoft Entra ID

> Learn how to set up SCIM provisioning with Microsoft Entra ID (formerly Azure Active Directory) for your Sketch Workspace.

**URL:** https://www.sketch.com/docs/getting-started/single-sign-on/scim-provisioning/microsoft-entra/ | **Last updated:** 2026-02-26

---
This guide shows you how to set up SCIM provisioning with [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) for your Sketch Workspace. If you get stuck during setup, [contact us](/support/contact/?topic=enterprise&subject=other&summary=I%20need%20help%20setting%20up%20SSO%20or%20SCIM.%0A%0A---%0A%0AAdd%20any%20other%20details%20below%3A%0A) and we’ll help you out.

> **Note:** **[Start here if you already use Entra ID for SSO](#existing-entra-id-sso-configuration).**
You’ll need to delete the Gallery app and create a custom app before continuing.

## 1. Create a custom application

1. Navigate to **Enterprise apps** > **All applications**, then click **New application**.
1. Select **Create your own application**.
1. Name your application and keep the preselected option *Integrate any other application you don’t find in the gallery (Non-gallery)*.

![An image showing how to create a custom application in Microsoft Entra ID](https://cdn.sketch.com/docs/sso/1-entra-create-custom-app.png)

### Configure SSO

1. Set up SAML by adding the Entity ID, ACS, and sign-on URLs.
1. Update the SSO attributes and claims in Entra ID. You’ll need to change the default values for the SSO attributes and claims.

   Manually review and create new claim mappings for a successful sign-in. Incorrect mappings are a common cause of sign-in issues.

   - **Email:** Map the email claim to `userPrincipalName`.
   - **Given Name (First Name):** Map to `user.givenname`.
   - **Surname:** Map to `user.surname`.

1. Save your changes to the attribute mappings.

### Upload the metadata to Sketch

1. Download the **Federation Metadata XML** file from Entra ID.
1. Sign in to Sketch as an admin.
1. Navigate to **Settings** > **[Single Sign-on](/workspace/settings/sso)**.
1. Open the **Configure Sketch** tab, then drag and drop the XML file.

> **Note:** For more details on configuring SSO, see our [Entra ID SSO documentation](/docs/getting-started/single-sign-on/setting-up-saml-sso/setup-identity-provider/azure-active-directory/).

## 2. SCIM provisioning setup

### Enable provisioning in Entra ID and Sketch

In your custom Entra ID application, go to **Provisioning** and enable SCIM. In the **Admin credentials** section, enter the following:

- **Authentication method:** `Bearer authentication`
- **Tenant URL:** SCIM endpoint URL from Sketch
- **Secret token:** SCIM token from Sketch

To get these values from Sketch:

1. Sign in to your Sketch Workspace as an admin.
2. Go to **Settings** > **[Single sign-on](/workspace/settings/sso)**.
3. Scroll to the bottom of the page and click **Enable SCIM**.
4. Copy the **SCIM endpoint URL** (Tenant URL) and **SCIM token** (Secret token).
5. Paste these values into the provisioning settings in Entra ID.

![An image showing the provisioning credentials section in Microsoft Entra ID](https://cdn.sketch.com/docs/sso/2-entra-new-provisioning-config.png)

### Test the connection

After pasting the Tenant URL and token, click **Test connection** to check everything is set up correctly.

### Configure app roles

Before SCIM can provision roles correctly, you’ll need to configure them in the application manifest.

1. In Entra ID, go to **App registrations**.
1. Select your custom app.
1. Configure the application roles (App Roles).

Create two new roles: **Editor** and **Viewer**. Make sure the **value** field is in lowercase (`editor` and `viewer`) to avoid capitalisation issues in provisioning.

![An image showing how to configure app roles in Microsoft Entra ID](https://cdn.sketch.com/docs/sso/4-entra-configure-app-roles.png)

### Disable group provisioning

Sketch doesn’t support creating groups through the API — only users. To handle this, Entra ID uses *group expansion*: it reads the members of a group and provisions those users individually, instead of trying to create a group in Sketch.

![An image showing how to disable group provisioning in Microsoft Entra ID](https://cdn.sketch.com/docs/sso/5-entra-disable-group-provisioning.png)

### Adjust SCIM attribute mappings

For provisioning to work correctly, you’ll need to update the default SCIM attribute mappings in Entra ID.

1. Go to **Provisioning** → **Edit attribute mappings** for your custom application.
2. Update `emails[type eq "work"].value` by changing the source attribute to `userPrincipalName`.

![An image showing the SCIM attribute mappings in Microsoft Entra ID](https://cdn.sketch.com/docs/sso/6-adjust-default-email-mapping.png)

### Create an access level attribute

1. Go to **Enterprise apps** and select your custom app.
2. Click **Provisioning**.
3. Click **Provisioning** again to open the provisioning settings.
4. Expand the **Mappings** section and select **Provision Microsoft Entra ID Users**.
5. Scroll to the bottom and click **Show advanced options**, then select **Edit attribute list for customappsso**.
6. Scroll to the bottom of the attribute list and add a new attribute with the following value:

   ```
   urn:ietf:params:scim:schemas:extension:sketch:1.0:User:accessLevel
   ```

7. Keep **String** selected and check the **Required** checkbox.

![An image showing how to create the access level attribute in Microsoft Entra ID](https://cdn.sketch.com/docs/sso/8-create-access-level-attribute.png)

### Create a mapping for the access level attribute

Map the Entra ID app role (**editor** or **viewer**) to the Sketch access level using an advanced mapping.

1. Go to **Enterprise apps** and select your custom app.
2. Click **Provisioning**.
3. Click **Provisioning** again, then expand the **Mappings** section.
4. Select **Provision Microsoft Entra ID Users**.
5. Scroll to the bottom and click **Add new mapping**.

   Use the following settings:

   - **Mapping type:** Expression
   - **Expression:**
   ```
   IIF(SingleAppRoleAssignment([appRoleAssignments])="", "viewer", ToLower(SingleAppRoleAssignment([appRoleAssignments]), ))
   ```
   - **Target attribute:** Select the access level attribute you created in the previous section.

6. Click **OK** to save.

![An image showing how to create the access level mapping in Microsoft Entra ID](https://cdn.sketch.com/docs/sso/10-entra-access-level-mapping.png)

## 3. Assign groups or users

### Create the groups

You’ll need two security groups — one for Editors and one for Viewers. You can create new groups or reuse existing ones.

1. In Entra ID, click **Groups** in the sidebar.
2. For each group, set the following:
   - **Group type:** Security
   - **Group name:** Use a clear, descriptive name, such as `sketch-users-editor` and `sketch-users-viewer`.
   - **Membership type:** Choose what fits your setup:
     - *Assigned* — assign users manually
     - *Dynamic user* — define a rule to match users
     - *Dynamic device* — define a rule to match devices
3. If you’re using assigned membership, add users to the group.

![An image showing how to create security groups in Microsoft Entra ID](https://cdn.sketch.com/docs/sso/11-entra-create-groups.png)

### Assign the groups to the custom app

This is where group membership is mapped to Sketch access levels.

1. Go to **Enterprise apps** and select your custom SCIM/SSO app.
2. Select **Users and groups** in the sidebar.
3. Click **Add user/group**.
4. Select a group and assign a role. Do this one group at a time:
   - Assign the Viewers group to the **Viewer** role.
   - Assign the Editors group to the **Editor** role.

Double-check the mappings before saving.

![An image showing how to assign groups to the custom app in Microsoft Entra ID](https://cdn.sketch.com/docs/sso/12-entra-assign-groups.png)

## 4. Testing and confirmation

Run a **Provision on demand** test for an assigned user.

**Note:** You can’t run a provision-on-demand test for a group. Entra ID will prompt you to select up to five users from the assigned groups instead. The outcome should be the same: the user is added to your Workspace with the correct role.

Once the test succeeds, turn on provisioning for the custom app. From now on, any changes you make to users or groups in Entra ID will sync automatically to your Sketch Workspace.

## Considerations

- If you reach your Editor seat limit, provisioning will appear as successful in Entra ID, but we’ll add them as Viewers to avoid unwanted extra charges.
- If you disable a user in Entra ID, they’ll be deleted from the Workspace. Any documents in their **My Drafts** folder will move to a restricted folder that Workspace Admins can access.

## Existing Entra ID SSO configuration

If you already have SSO configured with Entra ID, you’ll need to delete the Gallery app and create a new custom app to enable SCIM. The Gallery app doesn’t support SCIM provisioning.

Deleting the Gallery app won’t affect existing users or their documents. You don’t need to make any changes in your Sketch Workspace — Entra ID handles everything.

### Delete the Gallery app

> **Note:** Ask users to sign out of their accounts and quit the Mac app before you delete the app that handles user sign-in.

1. Sign in to your Entra ID account.
1. Go to **Enterprise apps** and select **Sketch** from the app list.
1. Open **Properties**, then select **Delete**.

![An image showing how to delete the Sketch gallery app in Microsoft Entra ID](https://cdn.sketch.com/docs/sso/0-entra-delete-gallery-app.png)

> **Note:** Once you’ve deleted the Gallery app, [go back to step 1](#1-create-a-custom-application) to create the custom app and set up SCIM.