SCIM provisioning

Overview

SCIM lets your identity provider — Okta, Microsoft Entra ID, OneLogin, JumpCloud or any other that speaks SCIM 2.0 — tell Gitmoap who works at your organisation and which groups they are in, the moment it changes. You give the provider a token; from then on it creates people, puts them in groups and, when someone leaves, de-provisions them. De-provisioning takes their access to your organisation away within the same request, rather than at their next sign-in or whenever somebody remembers.

It builds on single sign-on. People still sign in through your provider; SCIM decides what is waiting for them when they do, and what is gone when they should no longer have it.

Quick start

Before you start

How it works

A pushed person is expected, not a member. Most people arrive before they have ever signed in, so Gitmoap records them and invites them with your connection's default access level — or, if you already invited that email yourself, keeps your invite and the level it names. At their first sign-in the invite is taken up and they join every group your provider put them in. A push either records the person and their invite together or does neither, so a refused push leaves nothing behind for your provider's retry to trip over. Someone who already has a Gitmoap account with that email is matched to it straight away: their places on your provider's groups take effect as soon as the groups are pushed, and the invite is taken up at their next sign-in.

A pushed group is a team. Each group becomes a team whose roster your provider keeps; its name, from 1 to 100 characters, is the group's display name. You give the team access exactly as you would any other team, and everyone your provider puts in the group has it. Nobody can add or remove people on such a team by hand, or link it to a group in the sign-in instead — change the group in your provider.

De-provisioning is immediate and stays inside your organisation. When your provider deactivates or deletes someone, in one step Gitmoap removes all of their grants in your organisation — including access you gave them by hand — takes them off every one of your teams, revokes their personal access tokens that are limited to your groups and repositories, and cancels any invite still waiting for them. If they sign in again, they join nothing — even the first time they sign in through your provider with an account they already had. Their account, their access to other organisations, and everything they wrote — commits, merge requests, comments — are untouched. An approval they gave stops counting at once, because approvals are counted when a merge is checked, not when they were given.

Your provider's word on groups survives a deactivation. Gitmoap remembers which groups a de-provisioned person was in. If your provider reactivates them, they get the default access level on the organisation back and their places on your provider's groups return with it. Access they held anywhere else in the organisation does not come back on its own.

The last owner cannot be de-provisioned. Your organisation always keeps at least one person who is an Owner of it directly, with no end date. A deactivation that would remove the last of them is refused with the protocol's mutability error, and the request changes nothing — not their access, and not any other attribute it carried. Make someone else an Owner first.

SCIM replaces sign-in group sync. While your organisation has a live SCIM token, teams linked to an identity-provider group are not updated at sign-in — SCIM is the one source of truth for rosters, and two sources would undo each other. Nothing confirms the places on those teams any more, so they lapse at the end of the connection's sync period. Push those groups over SCIM instead, or revoke the last token to go back to sign-in sync.

Every change is recorded. Each SCIM request that changes something lands in your organisation's audit log, with your provider's token named as the actor; a de-provisioning, and the deletion of a pushed group, also record every grant they removed, with the role it carried. A request refused because its token is wrong is recorded without naming any token. Creating or deleting a pushed group, and the grants a deleted group took with it, are announced to webhooks subscribed to access, like any team's.

How to

Mint a token for your identity provider

Name it after the provider it is for. The response carries secret — the whole bearer token, gsc_… — once; nothing can show it again.

See your organisation's tokens

Every token, newest first, with when it was last used. Revoked tokens stay on the list, marked with when they were revoked, so the record of who could provision is complete.

Rotate a token

Two tokens can be live at once, so a rotation has no gap: mint a new one, put it in your provider, confirm your provider's next push succeeds, then revoke the old one.

Point your identity provider at Gitmoap

Your provider does the calling; you configure it once.

Your provider can read what Gitmoap supports from ServiceProviderConfig, ResourceTypes and Schemas under the same address. Filtering supports userName eq for people and displayName eq for groups — the lookups every provider makes before it creates something.

Remove somebody's access

Unassign them from the app in your provider, or deactivate them there. Your provider sends the deactivation, and their access to your organisation is gone when it returns. To give it back, reassign them.

Reference

Limits

Two live SCIM tokens per organisation, on every plan — enough to rotate without a gap. Minting a third is refused with 429 TOO_MANY_REQUESTS; revoke the old one first. An organisation that provisions from more than one identity provider can ask for a higher limit, up to five.

People your provider pushes count toward your organisation's member limit, and groups count toward its team limit. See teams and billing and plans for the numbers on each plan. Creating a person or a group past its limit is refused with 429, and your provider retries it once you have made room.

A group's people count toward the people-per-team limit, and a full team takes nobody new without refusing the push. Gitmoap still records that your provider put the person in the group, and gives them their place at their next sign-in if the team has room by then.

A PATCH carries at most 100 operations, and a page of results at most 100 resources. Every provider pages and batches below both.

Requests to the SCIM address are rate-limited per address, with a limit of their own, so a sync never counts against the limit every other client shares. A first full sync of a large directory sends thousands of requests in a few minutes and can still reach it. A request over it is refused with 429 and no SCIM error body; identity providers back off and retry on their own.

Troubleshooting

Examples

What your provider sends to create a person

What de-provisioning looks like on the wire

Find the tokens nobody has used in a month

FAQ

Related