SCIM 2.0 provisioning

PLUR Enterprise implements SCIM 2.0 for automated user and group provisioning. Your IdP creates and disables users, syncs group memberships, and updates profile attributes — without anyone touching the PLUR admin UI.

What SCIM gives you

• Joiner — a new hire shows up in your IdP, PLUR account created automatically.
• Mover — they switch teams in your IdP, group membership updates in PLUR.
• Leaver — they’re disabled in your IdP, the PLUR account is disabled (engrams retained for audit).

Endpoints

SCIM lives under /scim/v2/ (separate from the public API for protocol compliance):

Path	Purpose
GET /scim/v2/ServiceProviderConfig	SCIM capabilities advertisement
GET /scim/v2/ResourceTypes	Supported resources
GET /scim/v2/Schemas	User + Group schemas
GET/POST/PATCH/DELETE /scim/v2/Users	User CRUD
GET/POST/PATCH/DELETE /scim/v2/Groups	Group CRUD

The full surface conforms to RFC 7644 (SCIM 2.0 Protocol) and RFC 7643 (Schema).

Authentication

SCIM uses its own bearer token type — distinct from API keys for users. Tokens are managed at /admin/scim/tokens:

1. Log in to /admin.
2. Open SCIM tokens.
3. Click New token.
4. Copy the token; it won’t be shown again.
5. Paste into your IdP’s SCIM configuration.

Each token has a name, optional expiry, and a single role: SCIM provisioner. They are scoped to provisioning operations only — they cannot read engrams or sign in as a user.

Okta setup

1. Okta admin → Applications → your PLUR app → Provisioning → To App.
2. Enable: Create Users, Update User Attributes, Deactivate Users.
3. Connection settings:
   • SCIM connector base URL: https://plur.your-org.com/scim/v2
   • Unique identifier field: userName
   • Authentication mode: HTTP Header
   • HTTP Header value: Bearer <token from /admin/scim/tokens>
4. Test connection — should report all supported actions.
5. Map attributes (Okta → SCIM): userName, email, givenName, familyName, groups.

Microsoft Entra (Azure AD) setup

1. Entra → Enterprise applications → your PLUR app → Provisioning.
2. Mode: Automatic.
3. Tenant URL: https://plur.your-org.com/scim/v2
4. Secret token: <token from /admin/scim/tokens>
5. Test connection.
6. Map attributes per the Entra defaults; the SCIM schema PLUR advertises is the standard one.

Group provisioning

Groups in your IdP map to PLUR groups in the permission graph. A user in IdP group Engineering/Platform ends up with membership in PLUR group group:engineering/platform, which controls which scopes they can read and write.

The mapping is path-preserving: nested groups in the IdP become nested groups in PLUR. To prevent scope explosion, configure which IdP groups should sync at /admin/scim/groups.

Disabling users

When the IdP disables a user, SCIM sends PATCH /scim/v2/Users/{id} with active: false. PLUR:

1. Revokes the user’s session cookies.
2. Revokes all API keys owned by the user.
3. Marks the account disabled.
4. Retains the user’s engrams and episodes (audit trail).

Re-enabling restores access without data loss; the user logs in again to mint fresh credentials.

Hard delete

By default, SCIM DELETE is a soft delete — same as active: false. To enable hard delete (compliance scenarios), set PLUR_SCIM_HARD_DELETE=true in .env. Hard delete removes user-owned engrams in user:* scope; engrams in shared scopes (group:*, org:*, global) are reassigned to a placeholder identity.

Auditing

Every SCIM operation is recorded in audit_log:

SELECT ts, action, actor, target, payload
FROM audit_log
WHERE channel = 'scim'
ORDER BY ts DESC
LIMIT 50;

The admin dashboard at /admin/audit?channel=scim exposes the same data with filters.

Troubleshooting

• 401 from Okta/Entra — token wrong or revoked. Re-issue and update the IdP config.
• 409 on user create — userName collides with an existing local account. Either pre-link the accounts or rename the local one.
• Group memberships not syncing — Check /admin/scim/groups — the IdP group needs to be enabled for sync.
• Slow updates — IdPs batch SCIM calls. Okta is near-real-time; Azure runs on a 40-minute cycle by default.