Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

SCIM provisioning — frequently asked questions

Companion to Setting up SCIM provisioning with Microsoft Entra ID, SCIM authentication and the supported API surface.

These are the behaviours that surprise people. Most of them are working as intended.

Our SAML claims stopped taking effect

Expected — and it is the biggest single change to how your directory reaches Refapp.

Once SCIM configuration is on for your company, Refapp stops reading most of the SAML claim set. User creation, the email address, roles, cost centre, phone number and subaccount membership all come from SCIM instead, and SAML is left doing one job: authenticating the sign-in. The full list is under And what SCIM takes over in the setup guide.

Nothing warns you, because from Entra's side nothing is broken: the claims still arrive, and Refapp ignores them.

The two that bite:

  • Nobody is created at first sign-in, whatever Disable user auto-provisioning for SSO is set to. Someone who has not been provisioned is told that auto-provisioning is disabled and to contact their administrator — but inviting them in Refapp is not the fix. Assign them to the application in Entra.
  • Subaccounts mapped from the SAML groups claim stop updating. Membership now follows the groups SCIM provisions, so either turn group provisioning on — see groups and subaccounts — or manage subaccounts in Refapp from here on.

Roles are the reassuring one: they still come from the same app role assignments, carried by SCIM's roles attribute instead of by the role claim.

I cleared a phone number in Entra, but it is still set in Refapp

This is expected, and it is an Entra behaviour rather than a Refapp one.

Entra never sends an empty attribute. When you clear a value in the directory, Entra does not send "this is now empty" — it simply stops including the attribute. Refapp sees a request that says nothing about the field and leaves it alone.

The practical consequence: once an attribute has been provisioned, it can be replaced but not blanked from the directory. This most often bites phone numbers and cost centres.

To clear one, change it in Refapp directly, or set it to a placeholder value in Entra.

Microsoft documents this as a known issue: Null attribute can't be provisioned.

Does GET /Users return only the users SCIM created?

No — it returns every active user in your company, however they were created: by SCIM, by an earlier SAML sign-in, by an ATS integration, or by hand in Refapp.

This is worth stating because some other providers work the other way, returning only what their own connector created. If you have used one of those, do not assume the same restriction here.

Two details follow from it:

  • Deleted users are not returned. Suspended users are, with active: false.
  • When Entra runs its first cycle it will find, and take ownership of, users that already existed in Refapp. That is usually what you want — it links rather than duplicates — but it does mean the first cycle can change more than you expect. Run Provision on demand for one user before starting a full sync.

A user with no email address is skipped in the results. If you ever notice totalResults being larger than the number of users actually returned, that is why.

Refapp shows a different email address than my directory does

If your company is set up for plus-addressing, Refapp stores addresses with a label in them:

in your directory     anna.svensson@example.com in Refapp             anna.svensson+acme@example.com

This is deliberate and provisioning is working correctly. Email addresses are unique across all of Refapp, and the label is what lets the same person hold an account in more than one Refapp company — a consultant working for two clients, say, or your own staff who also appear in a partner's account. Mail still reaches them: everything after the + is ignored on delivery.

You control this yourself, under Company settings → Security. Two settings work together:

  • Plus addressing fallback — the label itself. Set it to acme and the label becomes +acme. Leave it empty and none of this applies.
  • Apply plus addressing fallback to all users — how the label is used.

With the label set but that switch off, provisioning stores the plain address you send, and the label is only used as a fallback: if the address is already taken Refapp labels it rather than failing the write, and a lookup that misses on the plain address is retried against the labelled one.

With the switch on, every account created for the company gets the label, collision or not — so the address in Refapp never matches the directory exactly.

You do not need to change anything in Entra, and you should not try to send the labelled address yourself. Keep mapping your ordinary mail attribute. Matching, updates and deprovisioning all continue to work, because Refapp falls back to the labelled address whenever the plain one finds nothing.

One consequence if you ever read the API directly: a user lookup answers userName with the address you filtered on, while emails carries the address actually stored. Those two disagreeing is the plus-address label, and it is deliberate — see the API surface.

How do I change someone's email address?

Change it in the directory and let it flow through the emails mapping.

userName looks like the field to change, but it is declared read-only and is ignored on writes — Refapp takes the address from emails and derives userName from it. So a change that only moves userName will appear to do nothing.

Be aware that userName is also the value Entra matches on, so after an address change Entra needs the new address in both places to keep finding the user. See userName must be the email address.

A user lost a role I had given them in Refapp

Roles are owned entirely by the directory. Every sync sends the complete set, and Refapp replaces what it has rather than merging.

That is deliberate: if roles merged, a role you removed in Entra would survive in Refapp forever, which is exactly the wrong behaviour for a permission. But it does mean a role granted by hand in Refapp will be removed on the next cycle if the directory does not also grant it.

Grant roles by assigning app roles in Entra, not in Refapp.

Related: a role name Entra sends that Refapp does not recognise is discarded without an error, so a typo in an app role name looks exactly like the role not being assigned. The recognised names are listed in the setup guide.

A newly created user is in no subaccount

If you are watching a cycle as it runs, this is normal and resolves itself within the same cycle.

Entra provisions users first and group membership second, a few seconds apart. In that gap a correctly created user genuinely belongs to nothing. Refapp does not derive subaccounts at user-creation time; they arrive with the group operations that follow.

If it persists past a full cycle — and you are actually provisioning groups; if you are not, this is simply how it works — it is one of two things:

  1. The Entra group names do not match the SSO group names configured on your Refapp subaccounts — see groups and subaccounts. Matching is on the group's display name, and it ignores case but nothing else.
  2. The groups are outside the provisioning scope, so no group operation ever mentions the user — see step 9.

The SAML groups claim is not involved either way — see And what SCIM takes over in the setup guide.

I renamed a group in Entra and nothing happened in Refapp

Renaming a group updates the name Refapp has stored, but it does not re-evaluate the people already in it. Existing members keep the subaccount access they had until their membership next changes.

To make a rename take effect:

  1. Update the SSO group name on the Refapp subaccount to match the new name.
  2. Force a re-evaluation of the members — run Provision on demand for them, or remove and re-add them to the group.

Provisioning failed with "Refusing to deprovision more than N users within 24 hours"

That is Refapp's mass-deprovisioning guard, and it is doing its job.

Refapp refuses to deprovision more than the greater of 10 users, or 25% of your users, in any rolling 24 hours, and answers 503 with a Retry-After. Entra will retry.

Refapp support is alerted automatically the first time it trips, so you do not need to report it. Then:

  • If the deprovisioning was a mistake — usually a group assignment edited by accident — fix the assignment. The guard has already prevented most of the damage.
  • If it was intended (a real bulk offboarding, or a migration), contact support and we will raise your limit. Otherwise it clears on its own as the 24-hour window rolls forward.

This is separate from Entra's own Prevent accidental deletion setting, and the two use deliberately different numbers so they cannot both fail for the same reason. Keep both on.

Can I remove a user and add them back later?

No. Removing a user from the application's assignments deletes them in Refapp, and that is permanent. Re-assigning the same person later creates a brand-new Refapp user with none of their previous history.

If someone is leaving temporarily — a leave of absence, a contractor between engagements, an offboarding that might be reversed — disable their account in Entra instead of unassigning them. That sends active: false, which suspends the Refapp user reversibly. Re-enabling the account restores everything exactly as it was.

The rule of thumb: disable for anything that might be undone, unassign only when you are certain.

Does every user have to be in a group?

No — and you do not have to provision groups at all.

Group provisioning is entirely optional. If you do not use subaccounts, or you would rather manage subaccount membership in Refapp, provision Users only and leave Groups switched off. Nothing else changes: users are still created, updated, suspended and deprovisioned exactly the same way.

If you do provision groups, a user who belongs to none is still fine. They are provisioned normally and simply have no subaccount access from the directory. You do not need a catch-all group. Some other providers require every user to be in at least one group; Refapp does not.

Why does every authentication error say the same thing?

Because the endpoint deliberately does not reveal which part was wrong. A bad token, a revoked token, a token for a different company, a company id that does not exist, and a company without SCIM enabled all return an identical 401.

If it told you apart, anyone could use it to discover which Refapp companies exist and which are half-configured.

There is a checklist for working through the causes in troubleshooting a 401.

Why is sortBy ignored instead of rejected?

Sorting is not supported, and Refapp advertises that in ServiceProviderConfig. Requests that ask for a sort return unsorted results with a 200 rather than an error.

This is the one unsupported feature that fails quietly rather than loudly — unsupported filters, by contrast, return an explicit 400. Do not rely on result ordering.