docs: document SCIM 2.0 handler opt-in and legacy flag - #27469

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

• docs/admin/users/oidc-auth/index.md

Documentation Check

This PR is a docs change. One accuracy issue in the new prose:

Updates Needed

• docs/admin/users/oidc-auth/index.md - The behavior note "Attempts to change userName via PUT or PATCH return a mutability error" does not match the code in enterprise/coderd/scim/users.go:

  • PUT (Replace) returns a plain 400 via scimErrors.ScimErrorBadRequest("changing the 'userName' field is not supported ..."). That helper sets no scimType, so it is not a mutability-typed error (there is a separate ScimErrorMutability the code does not use).
  • PATCH (Patch) only processes the active attribute and silently ignores userName (see the // TODO: Honor mutability rules of fields like userName at users.go:323), so it returns no error at all.

  Suggested reword: keep "Usernames are immutable," but describe the actual behavior, e.g. that a PUT with a changed userName is rejected with a 400 Bad Request, and PATCH currently only applies the active attribute and ignores other fields.

The rest of the section checks out against the code: opt-in via CODER_SCIM_USE_LEGACY=false / --scim-use-legacy / scimUseLegacy (default true, so false opts in), DELETE and active: false both suspend (never hard-delete), and re-activation/re-creation of a suspended user goes through the dormant state (scimUserStatus).

Automated review via Coder Agents

I did not mean to close this