Skip to main content
Run this runbook before enabling SCIM for a customer-facing pilot, before flipping GENESIS_SCIM_REQUIRE_PROVISIONED_USERS=true, and any time you materially change the IdP-side SCIM configuration.

​
Preflight

Confirm each of the following before running validation:
  • The Genesis deployment has a stable HTTPS hostname and persistent configuration values.
  • Authentication is configured and a test user can sign in through the customer IdP before SCIM-only admission is enforced.
  • The SCIM admin endpoints are reachable as a Genesis admin:
    • GET /api/config/scim/config
    • POST /api/config/scim/tokens/rotate
    • PUT /api/config/scim/group-role-mapping
  • A dedicated SCIM bearer token has been generated for the tenant and stored in the IdP’s secret field.
  • The group-to-role mapping has been configured before enabling group push from the IdP.
  • GENESIS_SCIM_REQUIRE_PROVISIONED_USERS is set to false for now.
For deployment-specific environment variables, see SCIM Inbound Provisioning.

​
Validation steps

Run these in order against a single pilot user. Reset state between iterations if needed.
1

Provision a pilot user

Have the IdP provision one user. Or push directly:
2

Verify the user exists

The response must contain exactly one resource with active: true and the expected externalId.
3

Push a mapped group with the user as a member

From the IdP (or directly), push one group present in the Genesis group-to-role mapping with the pilot user as a member. Confirm a 200 / 201 SCIM response.
4

Verify the role assignment

Have the pilot user sign in. Then call:
Confirm the role corresponding to the pushed group is present.
5

Remove the user from the group

From the IdP, remove the user from the group. Confirm only that role is revoked in Genesis. The user remains active.
6

Deactivate the pilot user

From the IdP, deactivate the user (or PATCH active=false). Confirm:
  • GET /scim/v2/Users/<id> returns active: false.
  • The user can no longer sign in once SCIM-only admission is enabled.
7

Verify audit rows

Confirm each operation above wrote a row to SCIM_AUDIT_LOG. See the audit query examples.
8

Confirm no unrelated changes

Inspect a non-SCIM admin user. Their roles, login state, and metadata should be unchanged.

​
Conformance harness

Genesis ships a repeatable conformance harness, scripts/validate_scim_conformance.py, that exercises the live SCIM endpoint. The script is included in the Genesis source distribution; if you do not have it locally, request it from your Genesis contact. Run it from a machine that can reach the Genesis host before customer pilot traffic begins, and again whenever you change SCIM-related configuration.
Set GENESIS_SCIM_TOKEN in the environment before running the command. Pass --token only for tightly controlled automation where shell history and process listings are not retained. For self-signed certificate troubleshooting in non-production environments, add --insecure. Do not use --insecure against production hosts. The harness checks include:
  • Invalid bearer token is rejected with a SCIM-shaped error.
  • ServiceProviderConfig, ResourceTypes, and Schemas are reachable.
  • PATCH support is advertised; ETag is correctly not advertised.
  • User and Group resources can be created, fetched, listed, filtered, PATCH-updated, replaced, and soft-deactivated.
  • Group membership PATCH add and remove operations are reflected in Genesis role assignments.
  • Group delete removes role membership without deactivating users.
The harness writes a JSON report listing every check and its status. Retain the latest report alongside your release evidence.

​
Rollback

If a rollout needs to be reversed:
1

Cut off the IdP

Disable the IdP SCIM app or revoke the Genesis SCIM token with POST /api/config/scim/tokens/revoke.
2

Reopen sign-in if it was restricted

Set GENESIS_SCIM_REQUIRE_PROVISIONED_USERS=false so non-SCIM users can still sign in.
3

Restore the previous mapping

PUT the previous group_role_mapping payload through PUT /api/config/scim/group-role-mapping.
4

Reconcile roles

Re-run the last known-good IdP group snapshot, or push the mapped groups from the IdP again, to bring Genesis role state back in line.
5

Roll back the deployment if needed

If the regression is suspected to be in Genesis itself, roll the deployment back to the previous container image and restart the application. Helm-based deployments can use helm rollback.

​
Pilot-to-production checklist

Before announcing SCIM as generally available for the deployment:
  • All validation steps pass for the pilot user.
  • The conformance harness report is green and retained.
  • Monitoring signals and alerts are wired up and acknowledged by an on-call owner.
  • The security review has been completed for the deployment.
  • A separate SCIM bearer token exists per integration and the rotation procedure is documented for the customer.
  • For multi-replica deployments, strict global SCIM rate limiting is enforced at ingress / WAF / API gateway / a shared limiter.
  • A rollback path is documented and rehearsed.

​
Accepted limitations for this release

  • Genesis does not advertise ETag support; optimistic concurrency is not required for a pilot unless the target IdP requires it.
  • SCIM Bulk operations are not supported.
  • Custom SCIM schema extensions beyond the SCIM Enterprise User extension fields documented in the API Reference are not supported.
  • The in-process per-token rate limiter is suitable for single-pod deployments; for multi-replica deployments, enforce strict global limits at ingress / WAF / API gateway / a shared limiter.