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 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

Go to Settings > Sign-in & access.

In the SCIM provisioning section, select Create token.

Enter a Name, such as "Entra", and select Create token.

In Copy your SCIM token, select Copy.

You won't see this token again, so paste it somewhere safe or keep this window open.

Select Done.

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.

In the Microsoft Entra admin center, go to Entra ID > Enterprise apps.

Select New application, then Create your own application.

Name it "HelpDocs".

Choose Integrate any other application you don't find in the gallery (Non-gallery).

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

In your application, open Provisioning.

Select New configuration. If you see Provisioning Mode instead, set it to Automatic.

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.

Select Test Connection. Entra should report that it connected.

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.

Under Mappings, open Provision Microsoft Entra ID Users.

Edit the mapping for the target attribute userName.

Set the source attribute to mail.

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 and OpenID Connect 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

Under Settings, set Scope to Sync only assigned users and groups.

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.

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

Back in Provisioning, set Provisioning Status to On.

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.

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.

Step 9: Check it worked

In HelpDocs, go to Settings > People. People Entra manages have a Managed badge.

In Settings > Sign-in & access, Last sync shows when Entra last used the token.

Your Audit log shows each change as SCIM: Entra, or whatever you named the token.

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.