SCIM

SCIM (protocolsoup-scim)

Image: ghcr.io/parlesec/protocolsoup-scim

When To Use

Use SCIM service for identity provisioning testing with SCIM-compatible IdPs, including user/group lifecycle operations, bulk provisioning, and filter queries.

Runtime Contract

Property	Value
Port	8080
Health	GET /health
SCIM base path	/scim/v2
Storage	SQLite (seeded with demo data on init)

SCIM Endpoints

• GET /scim/v2/ServiceProviderConfig
• GET /scim/v2/ResourceTypes, GET /scim/v2/ResourceTypes/{id}
• GET /scim/v2/Schemas, GET /scim/v2/Schemas/{id}
• GET|POST /scim/v2/Users, GET|PUT|PATCH|DELETE /scim/v2/Users/{id}
• GET|POST /scim/v2/Groups, GET|PUT|PATCH|DELETE /scim/v2/Groups/{id}
• POST /scim/v2/Bulk
• POST /scim/v2/.search
• POST /scim/client/provision — create a single user on an external SCIM service
• POST /scim/client/sync — reconcile local users to an external SCIM service

Outbound Reconciliation

POST /scim/client/provision and POST /scim/client/sync both send real outbound SCIM requests to the exact base URL supplied in targetUrl. Server-managed attributes (id, meta, groups, password) are stripped before a resource is forwarded; the source id is preserved as externalId for correlation.

sync additionally retrieves ServiceProviderConfig, then creates users without a stored target mapping and replaces previously mapped users with PUT. Source-to-target IDs and the last fully successful sync time are stored in the SCIM SQLite database.

curl -X POST http://localhost:8080/scim/client/sync \
  -H "Authorization: Bearer $SCIM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetUrl":"https://app.example.com/scim/v2","authToken":"target-service-token"}'

A fully successful sync run returns 200; a run with per-user failures returns 207 and operation details. Neither endpoint infers deletions—remote deprovisioning requires an explicit policy.

Production targets must use HTTPS and must not resolve to a loopback, private, or link-local address; non-production environments accept HTTP and private targets so both endpoints can be exercised against docker-compose networks and local IdP emulators.

Configuration

Variable	Required	Default	Description
SHOWCASE_BASE_URL	Yes	http://localhost:8080	External base URL
SCIM_API_TOKEN	Yes in production	-	Bearer token for authenticated requests and outbound client operations
SCIM_DATA_DIR	No	./data	SQLite database directory
SCIM_RETENTION	No	24h	Retention for visitor-created users and groups (updated_at). 0 disables the reaper. Demo data is re-seeded after each sweep.
SHOWCASE_ENV	No	development	Environment mode

Run

docker run -p 8080:8080 \
  -e SHOWCASE_BASE_URL=http://localhost:8080 \
  -e SCIM_API_TOKEN=change-me \
  -e SCIM_DATA_DIR=/app/data \
  -v scim-data:/app/data \
  ghcr.io/parlesec/protocolsoup-scim:latest

Operational Notes

• IdP connector URL is typically http(s)://<host>/scim/v2.
• Demo data (users and groups) is seeded on first startup.
• SCIM_API_TOKEN is checked via bearer auth middleware. Treat it as a credential.
• The same bearer authentication protects /scim/client/*, including outbound provisioning and sync.
• Mount SCIM_DATA_DIR for persistent provisioning state across container restarts.

Hosted instance	Not for real identity data
Visitors may create users and groups. Records older than SCIM_RETENTION (default 24h) are deleted and demo data is restored. Do not send real employee or customer records to the hosted instance.