SCIM Provisioning¶
What is SCIM?¶
SCIM lets your Identity Provider create, update and deactivate Report URI accounts on its own, and keep your teams in step with its groups. Assign someone the Report URI application in your IdP and their account appears here; unassign them and it is deactivated within seconds.
It removes the two failure modes of doing this by hand: people arriving with no account and waiting on an admin, and people leaving with an account nobody remembers to remove.
We implement SCIM 2.0 (RFC 7643 and RFC 7644), which works with Okta, Microsoft Entra ID, and anything else that speaks the standard.
SCIM needs SSO
SCIM provisions accounts that authenticate through your IdP, so it is configured on the same page as SSO and requires the same plan. Set up Single Sign-On first — in particular, your claimed domains must be verified before provisioning will work.
Before you start¶
You will need:
- SSO configured, with at least one verified claimed domain.
- An IdP administrator who can enable provisioning on your Report URI application.
Step 1 — Generate a SCIM token¶
On the Setup SSO page, find SCIM provisioning and click Generate SCIM token.
The token is shown once. We store only a hash of it, so it cannot be displayed again — copy it somewhere safe before you leave the page. If you lose it, rotate it and update your IdP with the new value.
Step 2 — Point your IdP at the SCIM endpoint¶
Give your IdP administrator these values:
| Value | What it is |
|---|---|
| SCIM base URL | https://scim.report-uri.com/v2 |
| Authentication | HTTP header authentication, or OAuth bearer token, using the token from step 1 |
| Unique identifier field for users | userName |
The unique identifier is the field your IdP matches on to decide whether someone already exists here, and it must be userName. That is the email address, and it is the only user attribute we treat as unique — anything else produces a query we reject, so every provisioning decision fails. If your IdP does not ask for this, it already uses userName, which is the default the standard defines.
Most IdPs will test the connection at this point by reading our ServiceProviderConfig. A successful test means the token and URL are right.
Okta
These three values are on Provisioning → Integration → Edit. Choose HTTP Header as the authentication mode and paste the token as the bearer value. Enable Push New Users, Push Profile Updates and Push Groups, then use Test Connector Configuration before saving.
Step 3 — Assign people and groups¶
Once the connection is live, assignments in your IdP flow through:
- Assigning a user creates their Report URI account.
- Unassigning a user, or deactivating them in your IdP, deactivates their account here.
- Pushing a group creates a Report URI team of the same name, with its members.
- Changing group membership adds and removes people from that team.
New accounts arrive with no password. Their access is through SSO, as it should be for an IdP-managed identity.
What each operation does¶
| Your IdP does | We do |
|---|---|
| Create user | Create the account, bound to your organisation |
| Deactivate user, or unassign | Revoke every live session immediately and refuse further logins |
| Reactivate user | Restore the ability to log in |
| Delete user | Deactivate, as above — the account is not erased |
| Create group | Create a team owned by your account |
| Update group membership | Add or remove team members |
| Delete group | Delete the team |
Things worth knowing¶
Deactivation is immediate. When your IdP deactivates someone, every session they have open is destroyed at that moment, not when it would have expired. There is no window in which a deprovisioned person keeps working in a tab they already had open.
Deleting a user does not erase them. An IdP deleting a user is telling us that person no longer has access, and that is exactly what we do. Their report history, team memberships and billing relationship stay intact, so reprovisioning the same person restores their access. If you genuinely want the account erased, delete it from Account → Settings.
Deleting a group does delete the team, along with the team's report data. The accounts that were in it are unaffected.
Existing accounts are adopted, not duplicated. If someone signed up directly before you connected your IdP, provisioning them links that existing account to your organisation rather than creating a second one — as long as their address is on one of your verified claimed domains.
You can only provision your own domains. Every address you provision must be on a verified claimed domain. This is what stops an account being created here for an address your organisation does not control.
Email addresses cannot be changed through SCIM. The address identifies the account across our whole system. If someone's address changes, deprovision the old one and provision the new one.
The team owner is not a group member. Your own account owns the teams SCIM creates and is not listed in their members, so your IdP cannot remove you from your own team.
Group names are not deduplicated. Two IdP groups pushed with the same name give you two teams with the same name.
Attributes we support¶
| Attribute | Notes |
|---|---|
userName |
The email address. Required, and immutable. |
active |
false deprovisions, true restores. |
externalId |
Your IdP's own id for the user. Optional but recommended — it is what reconciliation matches on. |
displayName (groups) |
The team name. |
members (groups) |
Team membership. |
We do not store a personal name, so name.givenName and name.familyName are not offered for mapping. Filtering is supported on userName and externalId for users, and displayName for groups, using the eq operator — which is what an IdP uses to reconcile.
Rotating or removing the token¶
Rotate issues a new token and stops the old one working immediately. Provisioning will fail until you update your IdP with the new value.
Delete stops provisioning entirely. Existing accounts and teams are untouched; your IdP simply loses the ability to change them.
Both actions are recorded in your audit trail, along with every account SCIM provisions, links or deactivates.
Troubleshooting¶
Every request returns 401. The token is wrong, has been rotated, or the plan on the account no longer includes SSO. Generate a fresh token and check the plan.
Creating a user returns 400. The address is almost certainly not on a verified claimed domain. Check the domain is listed and verified on the SSO setup page.
Creating a user returns 409. That address already exists and is already bound to an organisation. If they signed up directly, they can be adopted only while unbound — an account already linked to another organisation cannot be moved.
A group sync fails on one member. We refuse a member we cannot resolve, rather than skipping it, so that your IdP is never told a change succeeded when it did not. The usual cause is a group containing someone who has not been assigned the application, so no account exists for them yet.
If something else is wrong, email support@report-uri.com.