Contents

SCIM provisioning Enterprise

Your identity provider tells the team server when a person joins, changes or leaves. When IT disables or removes someone in Okta or Microsoft Entra ID, every gitta token of that person stops working at once, and their browser sessions end.

What happens

In the identity provider	On the team server
IT assigns a person to the gitta app	The server stores the person. They sign in with `gitta login` as usual.
IT changes the name or email	The server stores the change.
IT disables the person, or removes them from the app	All tokens with their email stop working on the next call. Their team view sessions end. The server issues them no new token and refuses their sign in.
IT deletes the person	The same as disabling. The server also forgets the person.
IT enables the person again	They can sign in again with `gitta login`. Their old tokens stay invalid.

The server matches tokens to people by email address. It uses the SCIM userName when it is an email address, and every address in emails. Admin tokens are never affected.

Turn it on

Make a long random token and give it to the team server as GITTA_SCIM_TOKEN, or in a file with --scim-token-file. It must be at least 32 characters. The server then answers at /scim/v2.

Terminal

$ openssl rand -hex 32 > scim-token
$ GITTA_SCIM_TOKEN=$(cat scim-token) gitta server
gitta server: SCIM provisioning on at /scim/v2

Use the same value on every team server. With two or more servers, also set GITTA_SCIM_PEERS on each server to the addresses of the other servers, separated by commas. The identity provider talks to one server, and that server copies each change to the others in the background. It tries again for about an hour when one is down.

Terminal

GITTA_SCIM_TOKEN=…
GITTA_SCIM_PEERS=https://gitta-2.example.com

Okta

In the Okta admin console, open your gitta app (the one you use for sign in), or add a SCIM 2.0 app with bearer token authentication.
On the Provisioning tab, set the SCIM connector base URL to https://gitta-1.example.com/scim/v2 and the unique identifier field to userName.
Choose HTTP Header authentication and paste the SCIM token.
Turn on Push New Users, Push Profile Updates and Push User Deactivation.
Assign people or groups to the app.

Okta looks people up with filter=userName eq "…" and disables them with PATCH or with PUT and "active": false. The server accepts both.

Microsoft Entra ID

In Entra, open Enterprise applications, then your gitta app, then Provisioning. Set the mode to Automatic.
Set the Tenant URL to https://gitta-1.example.com/scim/v2 and the Secret Token to the SCIM token. Select Test Connection.
Under Mappings, keep the user mapping. Turn off the group mapping, because gitta has no roles to give groups.
Assign users or groups to the app and start provisioning. Members of an assigned group are provisioned as people.

Entra disables a person with a PATCH such as {"op":"Replace","path":"active","value":"False"}, and removes them with DELETE. It also sends filtered paths such as emails[type eq "work"].value. The server accepts all of these.

Check it

Terminal

$ curl -s -H "Authorization: Bearer $(cat scim-token)" \
    "https://gitta-1.example.com/scim/v2/Users?filter=userName%20eq%20%[email protected]%22"
{"schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],"totalResults":1,…}

When a person loses access, the server log says so:

Terminal

gitta server: SCIM: access ended for [email protected]

Endpoints

Path	Methods
`/scim/v2/Users`	GET with `filter` on `userName`, `externalId`, `id` or `emails.value`, and `startIndex` and `count`. POST.
`/scim/v2/Users/{id}`	GET, PUT, PATCH, DELETE
`/scim/v2/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas`	GET

The server keeps the people in scim-users.json and the disabled addresses in deprovisioned.json, both in its data folder. For tokens and sign in, see Tokens and sign-in.