Skip to main content

How to Configure User Provisioning with Microsoft Entra (SCIM 2.0)

Note: SCIM user provisioning is available on the Pro and Organization plans.

Microsoft Entra can automatically create, update, and deactivate Bonusly users so your Bonusly user list always matches your IdP. This article walks through the full setup against Bonusly's SCIM 2.0 endpoint.

In this article:

  • Before you start

  • Step 1: Get the SCIM endpoint and token from Bonusly

  • Step 2: Create a custom enterprise app in Microsoft Entra

  • Step 3: Configure provisioning credentials and test the connection

  • Step 4: Disable group provisioning

  • Step 5: Register Bonusly's custom attributes in Entra

  • Step 6: Map Entra source attributes to Bonusly

  • Step 7: Assign users and turn provisioning on

  • Attribute reference

  • FAQ

Before you start

⚠️ Do NOT use the "Bonusly" gallery app from Microsoft's app catalog.

The Bonusly enterprise app published in Entra's gallery is preconfigured for an older integration shape and does not work with our SCIM 2.0 endpoint. If you start there, you'll get cryptic schema errors at attribute-mapping save time and the connection test will fail.

Always create a fresh non-gallery custom application following Step 2 below. If you've already added the gallery Bonusly app for SAML SSO, that's fine leave it for SSO and create a separate non-gallery app for SCIM provisioning.

You'll need:

  • A Bonusly company admin account.

  • A Microsoft Entra account with Application Administrator or Global Administrator role on the tenant where the integration will live.

  • 30–45 minutes for the full setup including Entra's initial sync cycle.

Step 1: Get the SCIM endpoint and token from Bonusly

  1. Log into Bonusly as a company admin.

  2. Navigate to Admin Settings → Integrations → SCIM. You'll see the SCIM Integration page:

  3. Under "About SCIM", copy the Microsoft Entra (SCIM 2.0) endpoint URL — it should be https://bonus.ly/api/scim20. (Use this exact URL; do not use the SCIM 1.1 URL for Entra.)

  4. Under "SCIM tokens", click Add SCIM token.

  5. Give the token a descriptive name (e.g., Microsoft Entra production) and click Create.

  6. Copy the token value immediately — Bonusly only shows it once. If you lose it, you'll have to revoke and re-create. Paste it somewhere temporary (a password manager, a secure note) for the next step.

Security note: SCIM tokens can only read and write users. They cannot access bonuses, rewards, awards, or any other Bonusly surface. Even so, treat the token like any other credential — store it in your IdP only, never commit it to source control or share it over insecure channels.

Step 2: Create a custom enterprise app in Microsoft Entra

  1. Sign in to the Entra admin center as a tenant admin.

  2. Left nav → Identity → Applications → Enterprise applications.

  3. Click + New application.

  4. Click + Create your own application (the button near the top of the page).

  5. Enter a Name for the app (e.g., Bonusly SCIM) and choose the third radio option: "Integrate any other application you don't find in the gallery (Non-gallery)".

    • This is the critical step. Do not search the gallery for "Bonusly" — that app uses a different integration and won't work for SCIM 2.0.

  6. Click Create and wait for the success toast.

  7. Click into the new app once it appears.

Step 3: Configure provisioning credentials and test the connection

  1. From the enterprise app's left nav, click Provisioning.

  2. Click Get started (or Provisioning under "Manage" if you've already opened this page once).

  3. Change Provisioning Mode from Manual to Automatic. The "Admin Credentials" section appears.

  4. Fill in:

Field

Value

Tenant URL

https://bonus.ly/api/scim20

Secret Token

The SCIM token you copied from Bonusly in Step 1

5. Click Test Connection.

You should get a green checkmark and the message "The supplied credentials are authorized to enable provisioning." If you get an error, see the FAQ below.

6. Click Save at the top. You must save before configuring mappings — Entra will discard any unsaved mapping changes when you change credentials.

Step 4: Disable group provisioning

Bonusly's SCIM API is users-only. The default Entra setup includes a "Provision Microsoft Entra ID Groups" mapping that will fail against Bonusly. Disable it before continuing.

  1. From the Provisioning page, click Mappings.

  2. Click Provision Microsoft Entra ID Groups.

  3. Set Enabled to No.

  4. Click Save at the top.

  5. Go back to Mappings.

You should now see only Provision Microsoft Entra ID Users as enabled.

Step 5: Register Bonusly's custom attributes in Entra

Entra auto-discovers Bonusly's standard SCIM attributes from our /Schemas endpoint, but it does not auto-add our extension attributes to the mapping dropdown. You have to register them manually before they're available as mapping targets.

  1. Click Provision Microsoft Entra ID Users to open the user-mapping page.

  2. Scroll to the bottom and check Show advanced options.

  3. Click Edit attribute list for customappsso. The attribute list editor opens.

  4. Add a row for each of the eight attributes below. Click Add New Mapping at the bottom of the existing list to insert each row.

    Seven String-typed attributes:

    For each, paste the full URN-prefixed name exactly as shown (case-sensitive, no leading whitespace), set Type = String, leave Multi-valued and Required unchecked, and leave the "Referenced object attribute" column empty.

    • urn:ietf:params:scim:schemas:extension:bonusly:2.0:User:employeeNumber

    • urn:ietf:params:scim:schemas:extension:bonusly:2.0:User:costCenter

    • urn:ietf:params:scim:schemas:extension:bonusly:2.0:User:businessUnit

    • urn:ietf:params:scim:schemas:extension:bonusly:2.0:User:department

    • urn:ietf:params:scim:schemas:extension:bonusly:2.0:User:location

    • urn:ietf:params:scim:schemas:extension:bonusly:2.0:User:hiredOn

    • urn:ietf:params:scim:schemas:extension:bonusly:2.0:User:userMode

    One Reference-typed attribute (manager):

    • Name: urn:ietf:params:scim:schemas:extension:bonusly:2.0:User:managerEmail

    • Type: Reference

    • Multi-valued: unchecked

    • Referenced object attribute: select urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:emails[type eq "work"].value from the dropdown (this is Entra's internal selector for "the manager's work email")

  5. Click Save at the bottom of the attribute list editor. The page refreshes; your new attributes are now selectable as Target Object targets in the mapping table.

    When you're done, your attribute list should look like this (note managerEmail is type Reference; everything else is String):

Common pitfall — case-sensitive names. Bonusly's SCIM schema declares these attributes in camelCase (managerEmail, employeeNumber, businessUnit, etc.). If you type manager_email or employee_number, Bonusly silently drops the value because the attribute name doesn't match the schema. Copy directly from the list above to avoid typos.

Step 6: Map Entra source attributes to Bonusly

Now connect each Bonusly target attribute to a source attribute in Entra. The mapping table below covers everything Bonusly supports. You can map all of them, some of them, or just a few — Bonusly only updates fields you map and leaves the rest untouched.

In the Attribute Mapping page:

  1. Confirm Target Object Actions: ✅ Create, ✅ Update, ✅ Delete are all checked.

  2. Delete any default mapping that targets an attribute Bonusly doesn't honor:

    • Anything ending in phoneNumbers[...].value

    • Anything ending in addresses[...].streetAddress, .locality, .region, .postalCode, or .formatted (Bonusly only honors country)

    • Anything targeting urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:* (Bonusly does not use the enterprise URN — re-route those source attributes to the Bonusly URN equivalents below)

  3. Add or verify each mapping using the table in the Attribute reference section below.

  4. Click Save at the top of the Attribute Mapping page.

When complete, your Attribute Mapping page should look like this:

Step 7: Assign users and turn provisioning on

  1. From the enterprise app's left nav → Users and groups.

  2. Click + Add user/group and assign the users you want Bonusly to provision. (We recommend starting with a small test group of 2–3 users before assigning your whole organization.)

  3. Go back to Provisioning → set Provisioning Status to On → click Save.

Entra runs the initial sync within ~40 minutes. To force it sooner, click Provision on demand, search for a specific user, and click Provision.

Verify the provision worked

In Bonusly, head to Admin → Manage users. Your newly provisioned users should be present and active. Click into a user to check that all the attributes you mapped came through correctly.

About managers

Microsoft Entra populates manager links only after both the employee and their manager have been provisioned. If you provision Alice before Bob (her manager), Alice's managerEmail will be empty on the first sync. After the next sync cycle — or after a manual "Provision on demand" for Alice — her manager will resolve correctly.

If a manager hasn't been provisioned yet, Bonusly stashes the manager email and resolves it later when the manager finally provisions. No manual intervention needed.

Attribute reference

Bonusly supports every attribute below for both initial create and ongoing update. Source attribute values are based on a typical Entra setup; substitute whatever attribute holds the equivalent value in your tenant.

Core attributes (auto-discovered, in the standard dropdown)

Entra source

Bonusly target

Notes

userPrincipalName

userName

Primary identifier. Must be unique within your company.

Switch([IsSoftDeleted], , "False", "True", "True", "False")

active

Default Entra expression. Bonusly accepts the string "True"/"False" values Entra sends.

objectId

externalId

Entra's stable user ID. Used for manager resolution and re-matching across renames.

givenName

name.givenName

First name.

surname

name.familyName

Last name.

IIF(IsPresent([mail]), [mail], [userPrincipalName])

emails[type eq "work"].value

Must match userName.

country (or usageLocation)

addresses[type eq "work"].country

Bonusly normalizes to ISO-2 ("United States" → US).

jobTitle

title

Stored as a Bonusly custom property (job_title).

employeeType

userType

Stored as a Bonusly custom property (employment_type).

preferredLanguage

locale

Region is stripped (en-US → en). Only languages Bonusly supports are honored.

Bonusly extension attributes (custom, registered in Step 5)

All target paths are prefixed with urn:ietf:params:scim:schemas:extension:bonusly:2.0:User:. The table below abbreviates that prefix as …: for readability.

Entra source

Bonusly target

Stored as

Notes

employeeId

…:employeeNumber

custom_properties["employee_number"]

(your cost center attribute)

…:costCenter

User#cost_center (top-level field)

Top-level Bonusly column, not a custom property.

companyName

…:businessUnit

custom_properties["business_unit"]

Most tenants map companyName here. Customize if your tenant uses a different attribute.

department

…:department

custom_properties["department"]

manager (Reference, with referenced attribute = work email — see Step 5)

…:managerEmail

Resolved to manager_id via the company's user list

Bonusly resolves by externalId → email → internal ID. Unresolvable values are stashed for later resolution.

city

…:location

custom_properties["location"]

employeeHireDate

…:hiredOn

User#hired_on (Date column)

Bonusly accepts both YYYY-MM-DD and YYYY-MM-DDTHH:MM:SSZ.

(your birth-date attribute)

…:dateOfBirth

User#date_of_birth (with year stripped for privacy)

Write-only — Bonusly never returns this on reads to avoid leaking the artificial year back to Entra.

(custom — see below)

…:userMode

User#user_mode

Values: normal (default), receiver, ghost. Most tenants don't map this.

A few attributes Bonusly does not honor

If you see these in Entra's default mapping, delete them — Bonusly silently ignores any value sent for these and they just clutter your mapping table:

  • phoneNumbers[...].value and any sub-attribute

  • addresses[...] sub-attributes other than country

  • roles[...] (Bonusly handles roles via its own admin settings, not SCIM)

  • Anything under urn:ietf:params:scim:schemas:extension:enterprise:2.0:User: — Bonusly does not use the SCIM Enterprise extension. Re-route those source attributes to the Bonusly URN equivalents above.

FAQ

Why can't I use the Bonusly app from Entra's gallery?

The gallery Bonusly app is configured for a legacy integration. Bonusly's SCIM 2.0 endpoint requires a non-gallery custom application setup so you can point Entra at the right URL and configure the Bonusly extension URN. If you've added the gallery app for SAML SSO, leave it — it works fine for SSO. Just create a separate non-gallery app for SCIM provisioning.

Can I use SCIM 2.0 with Okta or OneLogin instead?

The /api/scim20 endpoint speaks standard SCIM 2.0 and works with any compliant IdP, including modern Okta SCIM connectors. If your IdP still uses SCIM 1.1 (older Okta connector, OneLogin SCIM 1.1, JumpCloud), use Bonusly's SCIM 1.1 endpoint instead — see the Bonusly SCIM Integration page for both URLs. The two endpoints can be used by different IdPs at the same time without conflict.

Why is managerEmail set up as a Reference type instead of String?

Entra's manager source attribute is a Reference to another user (not a plain string). Type the Bonusly target as Reference and choose the manager's work email as the "Referenced object attribute" — Entra dereferences the link and sends a plain email string to Bonusly, which then resolves it to the corresponding Bonusly user. You don't have to manually keep a separate mapping of [manager].mail.

Why did my Bonusly URN attributes not appear in the dropdown after I registered them?

Hard-refresh the Entra portal tab. Entra caches schema metadata aggressively and sometimes needs a reload before newly-added attributes show up. Also double-check there's no leading whitespace in the attribute Name field (Entra treats " urn:..." and "urn:..." as different attributes and silently drops the one with leading whitespace from the dropdown).

What happens when I unassign a user in Entra?

Bonusly deactivates the user (soft delete). The user record is preserved — their bonus history, balance, and rewards stay intact for audit and possible rehire. To restore later, re-assign them in Entra or set active: true via a PATCH operation; Bonusly will reactivate the existing record.

Will Bonusly send a welcome email to provisioned users?

By default, yes — new SCIM-provisioned users receive Bonusly's standard welcome email at the email address Entra provides. If your company has the Send welcome emails setting turned off in Bonusly's company settings, no welcome email is sent. Users who are reactivated (rather than newly created) do not get another welcome email either way.

Can I provision groups or roles?

No. Bonusly's SCIM API is users-only. Disable group provisioning (Step 4) so Entra doesn't try.

How do I rotate the SCIM token?

In Bonusly: Admin Settings → Integrations → SCIM → find the existing token → click into it → revoke. Then create a new token, copy the value, and paste it into Entra's Secret Token field on the Provisioning page. Click Test Connection to verify, then Save. There's no downtime — Entra picks up the new token on its next sync cycle.

Questions? Send us a note at [email protected]; we'd be happy to help!

Was this article helpful? Let us know by rating it below with an emoji and sharing your feedback!

Related Articles
Integrating with OneLogin
How to Configure SAML SSO and User Provisioning with Okta
Did this answer your question?