--- title: "Set up SCIM with Microsoft Entra ID" description: "Connect Microsoft Entra ID to HelpDocs with SCIM so Entra provisions members and groups. Covers the enterprise app, userName mapping, scope, and troubleshooting." url: "https://support.helpdocs.io/article/1rlz3n199u-set-up-scim-with-microsoft-entra-id" category: "SCIM" updated_at: "2026-11-12T16:15:12Z" --- # Set up SCIM with Microsoft Entra ID Connect Microsoft Entra ID to HelpDocs so Entra adds, updates, and removes your HelpDocs members and groups. See [Provision users with SCIM](/article/mboz67jrh5-provision-users-with-scim) first. ### Before you start - SCIM provisioning is switched on for your HelpDocs account. If you can't see the **SCIM provisioning** section in **Settings > Sign-in & access**, get in touch with us in-app. - You can edit settings in HelpDocs. - You can create and configure enterprise applications in Entra. Once you create a SCIM token, SSO and Slack sign-in stop creating new members. Have Entra ready to provision people before you create the token. ### Step 1: Create a SCIM token in HelpDocs 1 Go to **Settings > Sign-in & access**. 2 In the **SCIM provisioning** section, select **Create token**. 3 Enter a **Name**, such as "Entra", and select **Create token**. 4 In **Copy your SCIM token**, select **Copy**. You won't see this token again, so paste it somewhere safe or keep this window open. 5 Select **Done**. 6 Copy the **SCIM base URL** with its **Copy** button. It's `https://api.helpdocs.io/scim/v2`. ### Step 2: Create an enterprise application If you already have a HelpDocs enterprise application for SSO, you can use it and skip to step 3. 1 In the Microsoft Entra admin center, go to **Entra ID > Enterprise apps**. 2 Select **New application**, then **Create your own application**. 3 Name it "HelpDocs". 4 Choose **Integrate any other application you don't find in the gallery (Non-gallery)**. 5 Select **Create**. Microsoft renames these menus from time to time. Look for the option to create your own, non-gallery application. ### Step 3: Connect Entra to HelpDocs 1 In your application, open **Provisioning**. 2 Select **New configuration**. If you see **Provisioning Mode** instead, set it to **Automatic**. 3 Fill in these fields, which can appear under **Admin Credentials**: - **Tenant URL**: your **SCIM base URL** from HelpDocs. - **Secret Token**: the SCIM token you copied. 4 Select **Test Connection**. Entra should report that it connected. 5 Select **Create**, or **Save** if you're editing an existing configuration. ### Step 4: Map userName to email HelpDocs uses `userName` as the person's email address. Entra maps it to `userPrincipalName` by default. Change it to `mail`, unless every user principal name in your tenant is also the person's email address. 1 Under **Mappings**, open **Provision Microsoft Entra ID Users**. 2 Edit the mapping for the target attribute `userName`. 3 Set the source attribute to `mail`. 4 Save. HelpDocs reads these attributes and ignores the rest: - `userName` (the email address) - `active` - `displayName` - `name.givenName` and `name.familyName` - `externalId` You can leave Entra's other default mappings in place. HelpDocs always uses `userName` as the email address, so the `emails` mapping makes no difference. Users with no `mail` value can't be provisioned, because HelpDocs needs an email address. Entra reports them as failed in its provisioning logs. For groups, keep **Provision Microsoft Entra ID Groups** turned on. HelpDocs reads `displayName`, `members`, and `externalId`. ### Step 5: Check your SSO sends the same email If people sign in to HelpDocs through Entra, their sign-in must send the same email address as `userName`. HelpDocs refuses anyone whose sign-in email doesn't match a member. It also matches existing members by email, so a different address makes Entra add them again as a second member. Our [SAML](/article/i8fpdjc43n-setting-up-saml-single-sign-on) and [OpenID Connect](/article/h961z8xb7r-using-open-id-connect-for-single-sign-on) guides already ask for the email address, so if you followed them you're set. To check: - **SAML:** in your application's **Single sign-on > Attributes & Claims**, **Unique User Identifier (Name ID)** should be `user.mail`. Entra's default is `user.userprincipalname`. - **OpenID Connect:** the ID token needs an `email` claim. If it's missing, add it in **App registrations > Token configuration > Add optional claim**, for the **ID** token. If your SAML Name ID is still `user.userprincipalname` and people already sign in with it, your members were added under that address. Don't switch to `mail` for them, or Entra adds them again under the new address, using extra seats. Leave `userName` on `userPrincipalName` instead, or get in touch with us in-app first. ### Step 6: Choose who's provisioned 1 Under **Settings**, set **Scope** to **Sync only assigned users and groups**. 2 Open **Users and groups** for the application and assign the people and groups who should be HelpDocs members. People who are already HelpDocs members are matched by email. Try one person first with **Provision on demand**, if your tenant has it. An existing member should get a **Managed** badge, not show up twice. If your articles already use a HelpDocs group for permissions and you want an Entra group to take it over, link them **before** you assign the group. Use **Link a group** under **Link existing groups** in the **SCIM provisioning** section. When Entra first sends the group, HelpDocs renames your group to Entra's name and replaces its members with Entra's list, so people added by hand are removed. See [Link existing groups](/article/q4jncgqsm0-give-scim-groups-a-role#link-existing-groups). Assigning groups to an application needs a Microsoft Entra ID plan that supports it. Check your plan if you can only assign users. ### Step 7: Start provisioning 1 Back in **Provisioning**, set **Provisioning Status** to **On**. 2 Save. Entra runs a first sync, then syncs again on its own schedule. A large first sync can take a while. HelpDocs accepts up to 600 requests a minute for your account, and Entra slows down and retries when it hits that. When Entra deactivates or unassigns someone, HelpDocs deactivates them and remembers their role and groups. See [What happens when someone is deactivated](/article/mboz67jrh5-provision-users-with-scim#what-happens-when-someone-is-deactivated). ### Step 8: Pick roles for your groups Groups Entra pushes show in **Settings > Sign-in & access** under **Group roles**. Pick a role for each one. See [Give SCIM groups a role](/article/q4jncgqsm0-give-scim-groups-a-role). ### Step 9: Check it worked 1 In HelpDocs, go to **Settings > People**. People Entra manages have a **Managed** badge. 2 In **Settings > Sign-in & access**, **Last sync** shows when Entra last used the token. 3 Your Audit log shows each change as **SCIM: Entra**, or whatever you named the token. 4 In Entra, check the provisioning logs for any failed users. ### Troubleshooting Test Connection fails with 401 The token is wrong, rotated, or revoked. Create a new one and paste it into **Secret Token**. 403 "SCIM is not enabled for this account." SCIM provisioning isn't switched on for your account. Get in touch with us in-app to have it switched on. A user fails with "invalidValue" Their `userName` isn't an email address. Check the `userName` mapping in step 4. Someone shows up twice in HelpDocs Entra sent a different address from the one their existing member uses. See step 5. A provisioned member can't sign in with SSO Their sign-in sends a different email address from `userName`. See step 5. 403 about the user limit Your HelpDocs account is full. Remove a member or upgrade. Entra retries on its next sync. HelpDocs says "Managed by your identity provider" The member or group is managed by Entra. Make the change in Entra. A rename doesn't come through Either the person also belongs to HelpDocs accounts outside your organization, or SCIM didn't create their HelpDocs login. In both cases, SCIM can't change their email.