From 0f093c89f61c07809241cd5641f1922cd8ab240f Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Thu, 23 Jul 2026 20:11:02 +0000 Subject: [PATCH 1/5] docs: document SCIM 2.0 handler opt-in and legacy flag --- docs/admin/users/oidc-auth/index.md | 45 +++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/admin/users/oidc-auth/index.md b/docs/admin/users/oidc-auth/index.md index 17271e33343..7df377db9c4 100644 --- a/docs/admin/users/oidc-auth/index.md +++ b/docs/admin/users/oidc-auth/index.md @@ -161,6 +161,51 @@ it the Coder server. CODER_SCIM_AUTH_HEADER="your-api-key" ``` +### SCIM 2.0 handler + +Coder ships two SCIM implementations: + +- **Legacy handler** (current default): the original implementation, scoped + to the provisioning flows used by Okta cloud. It mixes SCIM 1.0 and 2.0 + behaviors, does not serve the SCIM discovery endpoints, and treats `PATCH` + requests as full-resource updates rather than + [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644) patch operations. +- **SCIM 2.0 handler** (opt-in): a rewrite that follows RFC 7644 and has been + verified against an external SCIM 2.0 compliance suite. It adds: + + - Discovery endpoints: `/scim/v2/ServiceProviderConfig`, + `/scim/v2/Schemas`, and `/scim/v2/ResourceTypes`. + - `GET /scim/v2/Users` with pagination and basic `userName` filtering. + - `GET`, `PUT`, `PATCH`, and `DELETE` on `/scim/v2/Users/{id}`, where + `PATCH` accepts RFC 7644 patch operations. + - Spec-compliant error responses. + +To turn off the legacy behavior and opt into the SCIM 2.0 handler, set: + +```dotenv +CODER_SCIM_USE_LEGACY=false +``` + +This is also available as the `--scim-use-legacy` server flag and the +`scimUseLegacy` YAML option. Because the setting selects which handler is +mounted at server startup, changing it requires a restart of the Coder +server. + +Behavior notes for the SCIM 2.0 handler: + +- 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 legacy handler remains the default for backward compatibility while the +new handler is validated in production. In a future release the default will +flip to the SCIM 2.0 handler, and the legacy handler will eventually be +removed. + ## TLS If your OpenID Connect provider requires client TLS certificates for From 04705230e11db47ae6e1abff9e75958aabf9b60a Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Thu, 23 Jul 2026 20:19:39 +0000 Subject: [PATCH 2/5] docs: focus SCIM section on the new SCIM 2.0 flow --- docs/admin/users/oidc-auth/index.md | 32 ++++++++--------------------- 1 file changed, 9 insertions(+), 23 deletions(-) diff --git a/docs/admin/users/oidc-auth/index.md b/docs/admin/users/oidc-auth/index.md index 7df377db9c4..0e3bfd29473 100644 --- a/docs/admin/users/oidc-auth/index.md +++ b/docs/admin/users/oidc-auth/index.md @@ -163,35 +163,24 @@ CODER_SCIM_AUTH_HEADER="your-api-key" ### SCIM 2.0 handler -Coder ships two SCIM implementations: +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: -- **Legacy handler** (current default): the original implementation, scoped - to the provisioning flows used by Okta cloud. It mixes SCIM 1.0 and 2.0 - behaviors, does not serve the SCIM discovery endpoints, and treats `PATCH` - requests as full-resource updates rather than - [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644) patch operations. -- **SCIM 2.0 handler** (opt-in): a rewrite that follows RFC 7644 and has been - verified against an external SCIM 2.0 compliance suite. It adds: +- User provisioning and deprovisioning +- User listing - - Discovery endpoints: `/scim/v2/ServiceProviderConfig`, - `/scim/v2/Schemas`, and `/scim/v2/ResourceTypes`. - - `GET /scim/v2/Users` with pagination and basic `userName` filtering. - - `GET`, `PUT`, `PATCH`, and `DELETE` on `/scim/v2/Users/{id}`, where - `PATCH` accepts RFC 7644 patch operations. - - Spec-compliant error responses. - -To turn off the legacy behavior and opt into the SCIM 2.0 handler, set: +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. Because the setting selects which handler is -mounted at server startup, changing it requires a restart of the Coder +`scimUseLegacy` YAML option. Changing it requires a restart of the Coder server. -Behavior notes for the SCIM 2.0 handler: +Behavior notes: - Coder never hard-deletes users. `DELETE /scim/v2/Users/{id}` and deactivation (`active: false`) both [suspend](../index.md#suspend-a-user) @@ -201,10 +190,7 @@ Behavior notes for the SCIM 2.0 handler: - Usernames are immutable. Attempts to change `userName` via `PUT` or `PATCH` return a `mutability` error. -The legacy handler remains the default for backward compatibility while the -new handler is validated in production. In a future release the default will -flip to the SCIM 2.0 handler, and the legacy handler will eventually be -removed. +The SCIM 2.0 handler will eventually become the default behavior. ## TLS From 6a5254e526d5c8c3ad6f54b6f57fd20002a2ccac Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Thu, 23 Jul 2026 16:09:25 -0500 Subject: [PATCH 3/5] Update docs/admin/users/oidc-auth/index.md Co-authored-by: Nick Vigilante --- docs/admin/users/oidc-auth/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/admin/users/oidc-auth/index.md b/docs/admin/users/oidc-auth/index.md index 0e3bfd29473..11cbb89941e 100644 --- a/docs/admin/users/oidc-auth/index.md +++ b/docs/admin/users/oidc-auth/index.md @@ -163,9 +163,8 @@ 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: +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 From ef32caad7b11e45506d634cd61f7e28e749e55ab Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Thu, 23 Jul 2026 16:09:32 -0500 Subject: [PATCH 4/5] Update docs/admin/users/oidc-auth/index.md Co-authored-by: Nick Vigilante --- docs/admin/users/oidc-auth/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/admin/users/oidc-auth/index.md b/docs/admin/users/oidc-auth/index.md index 11cbb89941e..6dc7fe2b5fa 100644 --- a/docs/admin/users/oidc-auth/index.md +++ b/docs/admin/users/oidc-auth/index.md @@ -175,9 +175,8 @@ To opt in, set: 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. +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: From aa0292b4961467179d23312df25bac09db1aed36 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Thu, 23 Jul 2026 16:09:42 -0500 Subject: [PATCH 5/5] Update docs/admin/users/oidc-auth/index.md Co-authored-by: Nick Vigilante --- docs/admin/users/oidc-auth/index.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/admin/users/oidc-auth/index.md b/docs/admin/users/oidc-auth/index.md index 6dc7fe2b5fa..ec31071a83e 100644 --- a/docs/admin/users/oidc-auth/index.md +++ b/docs/admin/users/oidc-auth/index.md @@ -180,13 +180,9 @@ 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. +- 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.