From 92d45a0411c68711864cdc02e3b57cfe078402d7 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Mon, 27 Jul 2026 08:20:27 -0500 Subject: [PATCH] docs: document SCIM 2.0 handler opt-in and legacy flag (#27469) Documents the SCIM 2.0 handler introduced in #25572 and how to opt in. Adds a "SCIM 2.0 handler" subsection to the SCIM section of `docs/admin/users/oidc-auth/index.md`: - The handler follows RFC 7644 and supports user provisioning/deprovisioning and user listing. - Opt in with `CODER_SCIM_USE_LEGACY=false` (also `--scim-use-legacy` / `scimUseLegacy`); requires a server restart. - Behavior notes: delete/deactivate suspends (never hard-deletes), reactivation goes through dormant, usernames are immutable. - Notes it will eventually become the default behavior. Behavior details were verified against `enterprise/coderd/scimroutes.go`, `enterprise/coderd/scim/`, and the `SCIM Use Legacy` option in `codersdk/deployment.go`. `make lint/markdown` and `make lint/emdash` pass. --- Generated by Coder Agents on behalf of @Emyrk. --------- Co-authored-by: Nick Vigilante --- docs/admin/users/oidc-auth/index.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/admin/users/oidc-auth/index.md b/docs/admin/users/oidc-auth/index.md index 17271e3334..ec31071a83 100644 --- a/docs/admin/users/oidc-auth/index.md +++ b/docs/admin/users/oidc-auth/index.md @@ -161,6 +161,31 @@ it the Coder server. CODER_SCIM_AUTH_HEADER="your-api-key" ``` +### SCIM 2.0 handler + +Coder includes an opt-in SCIM 2.0 handler that follows [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644) and has been verified against an external SCIM 2.0 compliance suite. +It supports the following: + +- User provisioning and deprovisioning +- User listing + +To opt in, set: + +```dotenv +CODER_SCIM_USE_LEGACY=false +``` + +This is also available as the `--scim-use-legacy` server flag and the `scimUseLegacy` YAML option. +Changing it requires a restart of the Coder server. + +Behavior notes: + +- Coder never hard-deletes users. `DELETE /scim/v2/Users/{id}` and deactivation (`active: false`) both [suspend](../index.md#suspend-a-user) the user. +- Re-activating or re-creating a previously suspended user places them in the dormant state, and they become active again on their next login. +- Usernames are immutable. Attempts to change `userName` via `PUT` or `PATCH` return a `mutability` error. + +The SCIM 2.0 handler will eventually become the default behavior. + ## TLS If your OpenID Connect provider requires client TLS certificates for