Skip to the content

Provision and remove people with SCIM

Let Okta or Entra ID create the people Central Lite knows, give them console roles from their groups, and end their access when they leave.

Built, not yet claimed preview: this guide describes a package that has not passed its release gate.

Know what SCIM creates in Central Lite, make a token, connect Okta or Entra ID, map their groups to console roles, offboard someone and watch their gateway key stop working, decide what to do with a held wave of removals, and rotate the token. At the end your identity provider decides who Central Lite knows.

1. Know what SCIM creates

Your identity provider's provisioning client calls Central Lite at https://central.example:8443/scim/v2; Central Lite never calls it. Each user it sends becomes a person (a human principal) in the identity registry that every enrolled machine receives, with the user's identity at your provider, so gateway keys and costs are attributed to them. A user in a group you map to a console role also becomes a console admin, without a passkey, linked to their SSO identity when single sign-on is configured. Opt-in, a user can also be bound to a login name on every machine.

Central Lite keeps only userName, the display name, externalId, active, group memberships and the login attribute you name. Everything else in the request, emails, phone numbers and addresses among it, is dropped as the request is read and never reaches the database.

The provider must reach Central Lite's URL from its cloud. Entra ID can instead relay through its provisioning agent, outbound from your network (Entra ID P1); Okta's on-premises agent is supported only where Okta or a partner set it up. Central Lite's port answers SCIM over HTTP/2 and HTTP/1.1, so a provisioning client that speaks only HTTP/1.1 connects too.

See also

Give every agent an owner and an identity

Register each person and agent in Central Lite's identity registry, issue and revoke gateway keys, and see which identity every task belongs to.

2. Make a token for your provider

garm-central scim token create makes a bearer token for one source, named for your provider, and prints it once with the base URL to give the provider. Central Lite keeps only its SHA-256. A token reads and writes only its own source's users and groups. In the console, Settings → SCIM does the same: name the source, choose “Create a token with a passkey”, and copy the token while it is shown (“Copy this token now: it will not be shown again”).

Entra ID can authenticate without a long-lived token, by workload identity federation: Entra signs a short token that Central Lite checks against your tenant, the provisioning identity's object id and the audience you set with garm-central scim wif set, and answers with an access token that lasts an hour. Neither provider presents a client certificate, so there is no mutual TLS.

garm-central scim token create --name okta
garm-central scim token list
garm-central scim wif set --tenant <tenant id> --object-id <provisioning identity object id> --audience <audience>

3. Connect Okta or Entra ID

Okta: in the app integration you made for single sign-on, turn on SCIM provisioning. Give the SCIM connector base URL, userName as the unique identifier for users, and the token as an HTTP header (Bearer) authentication, then test the connection. Under To App, turn on creating users, updating their attributes and deactivating them. In the app's attribute mappings, map externalId from the expression user.getInternalProperty("id"): Okta then sends the same user id its ID tokens carry, which is how Central Lite matches a provisioned person to their sign-in. Assign the app to people or groups, and push the groups that carry roles.

Entra ID: in the enterprise application, set Provisioning to Automatic, with the base URL as the Tenant URL and the token as the Secret Token, then Test Connection. In the user attribute mappings, map objectId to externalId instead of the default: Central Lite matches it to the oid in Entra's ID tokens, since Entra's sub differs per application. Provision only assigned users and groups. Try one person first with Provision on demand, which runs at once; the regular cycle runs about every 40 minutes. Provisioning groups needs Entra ID P1, and a job that mostly fails is put in quarantine by Entra.

Each token may make 600 requests at once and 6,000 a minute; past that the provider is answered 429 and retries. For a large first sync, raise both with --scim-burst and --scim-per-minute on garm-central serve, and lower them again afterwards.

garm-central scim show shows the settings and the group mappings, garm-central identity show the people provisioned, and Settings → SCIM each source's active and total users, groups and last request.

garm-central serve --listen 0.0.0.0:8443 --scim-burst 2000 --scim-per-minute 20000
garm-central scim show
garm-central identity show

4. Map groups to console roles

garm-central scim groups lists the groups each source sent, with Central Lite's id and the group's externalId. garm-central scim map gives a group's members a console role at a scope (the whole org unless you name one). Name the group by its externalId where the provider sends one (Entra ID does), or by Central Lite's id (Okta's group push sends none), never by display name. Membership changes apply as they arrive.

A member without an admin gets one, without a passkey, named from the local part of their userName, and an admin_added alert is raised. Until they add a passkey their console session is read-only. Central Lite needs a first admin of its own, made at setup, before it adds any: until then the member is refused with a scim_admin_refused alert. Mapping roles, the login attribute and workload identity federation are set on the host only; the console shows them.

garm-central scim login-from userName-local binds each user to the login name before the @ in their userName, on every machine, as the provider next sends them; a value that is no login name, or one someone else holds, binds nothing and is alerted.

garm-central scim groups
garm-central scim map --group <group id> --role security

See also

Give people the right access in the console

Give each Central Lite admin one of six roles, for the whole org or a host group, and know who may request a kill order and who holds each approver key.

5. Offboard someone and watch their key stop working

Deactivate the person at your provider, or unassign them from the app. The provider sends active: false, and in that one change Central Lite suspends their principal, ends their console sessions, stops counting any approver key they hold, and publishes a new identity registry at once. Each machine erases the gateway keys AgentGarm issued to that person on its next delivery, and its proxy refuses the key within a minute after that, with 403 and “AgentGarm: this gateway key is revoked or no longer usable”. A key issued elsewhere keeps working at its issuer: end it there.

Reactivating the person restores them. Entra ID deletes a user 30 days after removal, which retires their principal and removes their admin for good; a person hired again later becomes a new principal. Okta never deletes, so an Okta person stays suspended until you retire their principal with garm-central identity principal state.

To watch it, run agentgarm identity on their machine before and after: the key is gone. On the Central Lite host, garm-central identity show lists the principal as suspended, and garm-central approver holders shows any approver key they held as suspended.

agentgarm identity
garm-central identity show
garm-central approver holders
garm-central identity principal state <principal id> retired

See also

Give Claude Code a per-developer gateway key

Give each developer their own gateway key from Central Lite and let Claude Code fetch it through apiKeyHelper; a claude.ai login is never routed.

6. Decide what to do with a held wave

A mistake at the provider can unassign everyone at once. Within any hour, once one source has suspended or deleted more than 5 people and more than 10% of its users, Central Lite holds the next ones: the first ones apply, the provider is answered as if all were done, and a High alert (scim_wave_held) asks an owner to decide. The held people stay active at Central Lite meanwhile. A single offboarding is never held.

garm-central scim holds lists each hold's source, when it was raised and who is held. garm-central scim hold resolve with --apply makes every held change and publishes the registry once; with --discard it drops them, and those people stay active: then fix the assignment at the provider. In the console, Settings → SCIM lists Held waves with “Apply with a passkey” and “Discard with a passkey”.

garm-central scim holds
garm-central scim hold resolve --id <hold id> --apply
The console's SCIM settings: the endpoint, the sources with a held wave of removals to apply or discard, and the bearer tokens

7. Rotate the token

Create a second token with the same source name, give it to the provider, check its last use in garm-central scim token list, then revoke the first by its id. A revoked token is refused at once, with 401: if your provider reports 401, its token was revoked or mistyped, so give it a current one. Settings → SCIM lists the bearer tokens with their creation and last use, and revokes one with a passkey.

While Central Lite is restoring from a backup, every SCIM write is answered 503 with a wait of five minutes, so the provider retries rather than giving up.

garm-central scim token create --name okta
garm-central scim token list
garm-central scim token revoke --id <old token id>

See also

Back up and restore Central Lite

Write Central Lite's encrypted backups by hand and on a schedule, and restore one so that no enrolled node refuses what Central Lite signs next.