devise_scim 0.1.11

data/docs/idp_setup.md

@@ -0,0 +1,335 @@
+# IdP Setup Guide
+
+## Overview
+
+`devise_scim` implements the **SCIM 2.0 server** (RFC 7643 / RFC 7644). Your application is the SCIM provider; the Identity Provider (Okta, Microsoft Entra, JumpCloud, etc.) is the SCIM client.
+
+The IdP initiates all communication by pushing user lifecycle events to your app's SCIM endpoints. Your app never calls out to the IdP — it only responds to inbound HTTP requests from it.
+
+Typical lifecycle events:
+
+- User created in the IdP directory → `POST /scim/v2/Users`
+- User profile updated → `PATCH /scim/v2/Users/:id`
+- User deactivated or removed → `DELETE /scim/v2/Users/:id` or `PATCH` with `active=false`
+- Group membership changed → `PATCH /scim/v2/Groups/:id` (when `enable_groups: true`)
+
+---
+
+## Obtaining Credentials
+
+### Bearer token (multi-tenant)
+
+```ruby
+# Rails console
+tenant = DeviseScim::ScimTenant.create!(name: "Acme Corp", auth_method: "token")
+raw_token = tenant.rotate_token!
+# => "a3f8c2d1e9b7..."   — copy this now; it will not be shown again
+```
+
+Provide `raw_token` to the IdP as the Bearer token. The BCrypt digest is stored in `token_digest`; the raw value is never persisted.
+
+### Bearer token (single-tenant)
+
+Set the token in an environment variable and reference it in the initializer:
+
+```ruby
+# config/initializers/devise_scim.rb
+config.token = ENV.fetch("SCIM_BEARER_TOKEN", nil)
+```
+
+Generate a token:
+
+```bash
+ruby -e "require 'securerandom'; puts SecureRandom.hex(32)"
+```
+
+Set `SCIM_BEARER_TOKEN` in your deployment environment and in the IdP's SCIM configuration.
+
+### OAuth 2.0 (client credentials grant)
+
+OAuth is only available when `auth_method: :oauth` and Doorkeeper >= 5.6 is installed.
+
+```ruby
+# Rails console
+app = Doorkeeper::Application.create!(
+  name: "Acme SCIM",
+  uid: SecureRandom.hex(8),
+  secret: SecureRandom.hex(16),
+  redirect_uri: "",
+  scopes: ""
+)
+puts "client_id:     #{app.uid}"
+puts "client_secret: #{app.secret}"
+```
+
+In multi-tenant OAuth mode, associate the application with the tenant:
+
+```ruby
+tenant.update!(auth_method: "oauth", doorkeeper_application: app)
+```
+
+Provide `client_id` and `client_secret` to the IdP.
+
+---
+
+## Okta Setup
+
+1. In Okta Admin, go to **Applications → Applications → Browse App Catalog**.
+2. Search for **SCIM 2.0** or open your existing app and navigate to **Provisioning → Configure API Integration**.
+3. Check **Enable API Integration**.
+4. Set the fields:
+
+   | Field | Value |
+   |---|---|
+   | SCIM connector base URL | `https://yourapp.com/scim/v2` |
+   | Unique identifier field for users | `userName` |
+   | Authentication Mode | `HTTP Header` (Bearer) or `OAuth` |
+   | Authorization / Bearer Token | the raw token from `rotate_token!` |
+
+5. Click **Test API Credentials** — expect HTTP 200 with a `ServiceProviderConfig` response.
+6. Under **Provisioning → To App**, enable:
+   - **Create Users**
+   - **Update User Attributes**
+   - **Deactivate Users**
+   - **Push Groups** (only if `enable_groups: true` in your config)
+
+**Attribute mapping** (Okta attribute → SCIM attribute → your model column via the adapter):
+
+| Okta attribute | SCIM attribute | Default AR column |
+|---|---|---|
+| `login` / `email` | `userName` | `email` |
+| `firstName` | `name.givenName` | `first_name` |
+| `lastName` | `name.familyName` | `last_name` |
+| `active` | `active` | `scim_active` |
+
+**What Okta sends for each operation:**
+
+- **CREATE** — `POST /Users` with a full SCIM user payload (`schemas`, `userName`, `name`, `emails`, `active`).
+- **UPDATE** — `PATCH /Users/:id` with a `Operations` array. Each operation has an `op` (replace/add/remove), optional `path`, and `value`.
+- **DEACTIVATE** — `PATCH /Users/:id` with `{ op: "replace", path: "active", value: false }`, or `DELETE /Users/:id` depending on your Okta app settings.
+
+---
+
+## Microsoft Entra (Azure AD) Setup
+
+1. In the Azure portal, go to **Azure Active Directory → Enterprise Applications → New Application → Create your own application → Non-gallery**.
+2. Name the app (e.g., "YourApp SCIM"), select **Integrate any other application you don't find in the gallery**.
+3. Navigate to **Provisioning → Get started → Provisioning Mode: Automatic**.
+4. Under **Admin Credentials**:
+
+   | Field | Value |
+   |---|---|
+   | Tenant URL | `https://yourapp.com/scim/v2` |
+   | Secret Token | the raw Bearer token |
+
+5. Click **Test Connection** — expect a success message.
+6. Expand **Mappings** to review attribute mappings. Defaults are reasonable; adjust if your column names differ.
+
+**Entra-specific notes:**
+
+- Entra sends `externalId` alongside `userName`. The gem maps `externalId` → `scim_uid` in single-tenant mode (the `ArelVisitor`'s `SCIM_TO_AR` table maps `"externalId"` → `"scim_uid"`).
+- Entra performs **soft-match** on first sync: if a user with matching `userName` (email) already exists in your app, Entra will attempt to link to that record rather than create a duplicate. The gem's claiming behavior (see the multi-tenancy guide) complements this — the user is claimed and `scim_claimed_at` is set.
+- Entra's provisioning cycle runs on a ~40-minute schedule by default. Use **Provision on demand** in the Azure portal to test individual users immediately.
+
+---
+
+## OAuth Token Endpoint
+
+Available only when `config.auth_method = :oauth`.
+
+```
+POST {route_prefix}/oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET
+```
+
+Example:
+
+```bash
+curl -X POST https://yourapp.com/scim/v2/oauth/token \
+  -d "grant_type=client_credentials" \
+  -d "client_id=abc123" \
+  -d "client_secret=xyz456"
+```
+
+Doorkeeper handles the response format (RFC 6749):
+
+```json
+{
+  "access_token": "TOKEN",
+  "token_type": "Bearer",
+  "expires_in": 7200,
+  "created_at": 1700000000
+}
+```
+
+The IdP then uses the returned `access_token` as the Bearer token for subsequent SCIM requests. Tokens expire per Doorkeeper's configuration (`access_token_expires_in`).
+
+The OAuth token endpoint is mounted by the router only when `auth_method == :oauth` — it does not appear in the route table for token-authenticated apps.
+
+---
+
+## Bearer Token Setup
+
+**Single-tenant pattern:**
+
+```ruby
+# config/initializers/devise_scim.rb
+config.auth_method = :token
+config.token = ENV.fetch("SCIM_BEARER_TOKEN", nil)
+```
+
+Set `SCIM_BEARER_TOKEN` in your production environment (Heroku config vars, AWS SSM, Kubernetes secret, etc.). Never commit the raw token to source control.
+
+The middleware compares the incoming Bearer token against `config.token` using `ActiveSupport::SecurityUtils.secure_compare` — a timing-safe comparison that prevents timing-oracle attacks.
+
+**Rotating tokens without downtime (single-tenant):**
+
+There is no grace period for single-tenant token auth — the new value in `config.token` is active as soon as the process restarts. To avoid a gap:
+
+1. Generate a new token.
+2. Update `SCIM_BEARER_TOKEN` in your deployment environment and deploy (process restarts with new token).
+3. Update the token in the IdP.
+4. The window where the old token is rejected and the new one not yet entered in the IdP is typically seconds — most IdPs retry on 401.
+
+**Multi-tenant token rotation:**
+
+See the `rotate_token!` documentation in the multi-tenancy guide. The new token_digest is active immediately after `rotate_token!` returns; update the IdP promptly.
+
+---
+
+## Testing Connectivity
+
+Before configuring an IdP, verify your endpoints respond correctly.
+
+**Discovery:**
+
+```bash
+curl -s -H "Authorization: Bearer YOUR_TOKEN" \
+  https://yourapp.com/scim/v2/ServiceProviderConfig | jq .
+```
+
+Expected: HTTP 200, `Content-Type: application/scim+json`, body with `schemas` array.
+
+**List users:**
+
+```bash
+curl -s -H "Authorization: Bearer YOUR_TOKEN" \
+  "https://yourapp.com/scim/v2/Users" | jq .
+```
+
+Expected: HTTP 200, `ListResponse` with `totalResults`, `startIndex`, `itemsPerPage`, `Resources`.
+
+**Create a user:**
+
+```bash
+curl -s -X POST https://yourapp.com/scim/v2/Users \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/scim+json" \
+  -d '{
+    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
+    "userName": "test@example.com",
+    "name": { "givenName": "Test", "familyName": "User" },
+    "active": true
+  }' | jq .
+```
+
+Expected: HTTP 201, full SCIM user representation.
+
+**Filter users:**
+
+```bash
+curl -s -G -H "Authorization: Bearer YOUR_TOKEN" \
+  https://yourapp.com/scim/v2/Users \
+  --data-urlencode 'filter=userName eq "test@example.com"' | jq .
+```
+
+> [!NOTE]
+> All SCIM endpoints respond with `Content-Type: application/scim+json`. Some HTTP clients or test tools may show a warning if they expect `application/json` — this is correct per RFC 7644.
+
+---
+
+## Okta SCIM Test Harness
+
+Okta provides a Runscope-based SCIM 2.0 test harness that validates your provider before activating provisioning in production. Run it against a staging environment exposed via a public URL (e.g. `ngrok http 3000`).
+
+**How to run:**
+
+1. In Okta Admin → your SCIM app → **Provisioning** tab → **Test API Credentials** — verifies the base URL and token before any test.
+2. Navigate to the [Okta SCIM Test Suite](https://developer.okta.com/docs/guides/scim-provisioning-integration-test/) and import the Runscope test bucket for SCIM 2.0.
+3. Set environment variables in Runscope:
+   - `base_url` — e.g. `https://abc123.ngrok-free.app/scim/v2`
+   - `auth_header` — `Bearer YOUR_TOKEN`
+4. Run the full test suite.
+
+**Expected results against `devise_scim` v0.1.0:**
+
+| Test group | Result | Notes |
+|---|---|---|
+| Authentication | Pass | 401 on missing/invalid token |
+| User create (`POST /Users`) | Pass | Returns 201 with `id`, full user representation |
+| User read (`GET /Users/:id`) | Pass | Returns 200 with correct schema |
+| User list (`GET /Users`) | Pass | Pagination via `startIndex` + `count`; filter via `userName eq "..."` |
+| User update (`PUT /Users/:id`) | Pass | Full replace |
+| User patch (`PATCH /Users/:id`) | Pass | `replace` op on `active`, `name.*`, `emails` |
+| User deprovision (`PATCH active=false`) | Pass | Calls `after_deprovision`; `active` returns false on next GET |
+| User reprovision (`PATCH active=true`) | Pass | Re-activates; `scim_source` preserved |
+| ServiceProviderConfig | Pass | Correct `schemas`, `filter.supported`, `patch.supported` |
+| Schemas discovery | Pass | Returns User and Group schema definitions |
+
+> [!NOTE]
+> Group tests require a `ScimAdapter` that implements `handle_group_create`, `handle_group_update`, and `handle_group_destroy`. The default adapter returns `501 Not Implemented` for these, which Okta's harness flags as a warning (not a failure) when Groups provisioning is disabled in the Okta app.
+
+---
+
+## SCIM Filter Support
+
+The gem implements a full recursive-descent SCIM filter parser (RFC 7644 §3.4.2.2).
+
+**Supported comparison operators:**
+
+| Operator | Meaning | Example |
+|---|---|---|
+| `eq` | Equal | `userName eq "alice@example.com"` |
+| `ne` | Not equal | `active ne true` |
+| `co` | Contains | `userName co "example"` |
+| `sw` | Starts with | `userName sw "alice"` |
+| `ew` | Ends with | `userName ew ".com"` |
+| `pr` | Present (not null) | `userName pr` |
+| `gt` | Greater than | `meta.created gt "2024-01-01"` |
+| `ge` | Greater than or equal | `meta.created ge "2024-01-01"` |
+| `lt` | Less than | `meta.created lt "2025-01-01"` |
+| `le` | Less than or equal | `meta.created le "2025-01-01"` |
+
+**Logical operators:** `and`, `or` (standard precedence — `and` binds tighter than `or`).
+
+**Supported SCIM attributes and their AR column mappings:**
+
+| SCIM attribute | AR column |
+|---|---|
+| `userName` | `email` |
+| `externalId` | `scim_uid` |
+| `active` | `scim_active` |
+| `id` | `id` |
+| `emails` / `emails.value` | `email` |
+| `name.givenName` | `first_name` |
+| `name.familyName` | `last_name` |
+
+Filters referencing unmapped or non-existent columns respond with HTTP 400 and SCIM error type `invalidFilter`.
+
+---
+
+## Common Issues
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `401 Unauthorized` on all requests | Token mismatch or tenant inactive | Verify the raw token in the IdP matches the one from `rotate_token!`. Check `tenant.active?`. In single-tenant mode, verify `SCIM_BEARER_TOKEN` env var is set and the process has restarted. |
+| `401` with correct token | Warden intercepting the middleware's 401 | This is handled internally by `warden.custom_failure!`. If you see it in a custom setup, ensure the `DeviseScim::Middleware::Authenticator` is mounted before Warden. |
+| `404` for a user that exists | User is outside this tenant's scope | In multi-tenant mode, `GET /Users/:id` returns 404 if the user has no active `scim_tenant_users` record for the current tenant. Check the join table. |
+| `409 Conflict` on `POST /Users` for a user that was deprovisioned | User is deprovisioned but still `scim_active = false` | In single-tenant mode the gem re-provisions deprovisioned users. In multi-tenant mode it re-creates the join record. Verify the user's `scim_active` column and the join record's `active` flag. |
+| `409 Conflict` on `POST /Users` for a user in another tenant | `user_exclusivity: :one_to_one` and `exclusivity_conflict: :error` | Either set `exclusivity_conflict: :reassign` to move the user, or set `user_exclusivity: :multiple` to allow shared membership. |
+| `400 invalidFilter` | Filter uses an unsupported attribute or malformed syntax | Check the `SCIM_TO_AR` mapping in `ArelVisitor`. The attribute must map to a column that exists on your model. |
+| `500` on filter with valid attribute | Column exists in the mapping but not in the database | Run `rails db:migrate`. The `add_scim_to_users` migration adds `first_name`/`last_name` only if they're present on the model. |
+| Okta "Test API Credentials" fails | Base URL includes a trailing slash, or route prefix mismatch | Ensure the base URL ends with `/scim/v2` (no trailing slash) and matches `config.route_prefix`. |
+| Entra creates duplicate users | Soft-match not firing | Entra matches on `userName`. Ensure your `userName` SCIM attribute maps to the same value as your `email` column — the default adapter uses `record.email` for `userName`. |

data/docs/multi_tenant.md

@@ -0,0 +1,328 @@
+# Multi-Tenancy Guide
+
+## Overview
+
+In multi-tenant mode (`config.tenancy = :multi`), each Identity Provider (IdP) is represented as a **tenant** — an AR record that holds its own credentials and configuration. Every SCIM request arrives with a credential (Bearer token or OAuth token) that the middleware resolves to a specific tenant record before the request reaches any controller.
+
+All database operations are then scoped to that tenant via the `scim_tenant_users` join table. A single application can serve many IdPs simultaneously; each sees only its own users and cannot see or modify records provisioned by another tenant.
+
+Key design properties:
+
+- One tenant per IdP — credentials are stored per tenant, not in environment variables.
+- `scim_tenant_users` is the authority for membership — a user exists in a tenant's scope only if a matching active join record exists.
+- Each tenant assigns its own `scim_uid` (the IdP's external ID) — the UID lives on the join record so the same user can carry different external IDs across tenants.
+
+---
+
+## Schema Overview
+
+Three tables work together:
+
+**`users`** — your application's Devise user table, extended with SCIM tracking columns:
+
+| Column | Type | Purpose |
+|---|---|---|
+| `scim_uid` | string | IdP's external ID (single-tenant only; in multi-tenant mode this lives on the join) |
+| `scim_source` | string | `"scim"` if provisioned via SCIM, `nil` for manually created users |
+| `scim_active` | boolean | Whether the user is active |
+| `scim_deprovisioned_at` | datetime | Timestamp of last soft-delete |
+| `scim_raw` | text / jsonb | Raw SCIM payload from last write (debugging aid) |
+
+**`scim_tenants`** — one row per IdP:
+
+| Column | Type | Purpose |
+|---|---|---|
+| `name` | string | Human-readable label |
+| `auth_method` | string | `"token"` or `"oauth"` |
+| `token_digest` | string | BCrypt digest of the Bearer token |
+| `active` | boolean | Whether this tenant is accepting requests |
+| `doorkeeper_application_id` | integer | FK to `oauth_applications` (OAuth mode) |
+
+**`scim_tenant_users`** — the join table that scopes all operations:
+
+| Column | Type | Purpose |
+|---|---|---|
+| `scim_tenant_id` | bigint | FK to the tenant (or custom FK — see below) |
+| `user_id` | bigint | FK to your users table |
+| `scim_uid` | string | The IdP's external ID for this user **within this tenant** |
+| `provisioned_at` | datetime | When the user was first provisioned by this tenant |
+| `scim_claimed_at` | datetime | Set when an existing user (not net-new) was claimed by this tenant |
+| `active` | boolean | Whether this assignment is currently active |
+| `scim_raw` | text / jsonb | Raw SCIM payload from last write |
+
+`scim_uid` lives on the join table — not on `users` — so the same user can have different external IDs per tenant, and a user's presence in one tenant's scope has no bearing on another's.
+
+There are two unique indexes on `scim_tenant_users`:
+
+- `(scim_tenant_id, user_id)` — one join record per user per tenant
+- `(scim_tenant_id, scim_uid) WHERE scim_uid IS NOT NULL` — prevents duplicate UID assignment within a tenant
+
+---
+
+## Built-In ScimTenant Model
+
+For most applications the built-in `DeviseScim::ScimTenant` is all you need.
+
+**1. Generate and migrate:**
+
+```bash
+rails g devise_scim:install User --multi-tenant
+rails db:migrate
+```
+
+This generates:
+
+- `db/migrate/add_scim_to_users.rb` — adds SCIM columns to your users table
+- `db/migrate/create_scim_tenants.rb` — creates `scim_tenants`
+- `db/migrate/create_scim_tenant_users.rb` — creates `scim_tenant_users`
+- `config/initializers/devise_scim.rb` — pre-configured for multi-tenant mode
+
+The default `config.tenant_model` is `"DeviseScim::ScimTenant"`. You do not need to set it explicitly.
+
+**2. Create a tenant and obtain a token:**
+
+```ruby
+# Rails console
+tenant = DeviseScim::ScimTenant.create!(name: "Acme Corp", auth_method: "token")
+raw_token = tenant.rotate_token!
+# => "a3f8c2d1e9b7..."   — store this securely; it will not be shown again
+```
+
+> [!WARNING]
+> `rotate_token!` returns the raw token exactly once. Store it immediately and provide it to your IdP. The raw value is never persisted — only the BCrypt digest is stored in `token_digest`.
+
+---
+
+## Custom Tenant Model
+
+If you already have an AR model representing organizations, accounts, or workspaces, you can use it as the SCIM tenant instead of `DeviseScim::ScimTenant`.
+
+**1. Include the concern in your existing model:**
+
+```ruby
+# app/models/org.rb
+class Org < ApplicationRecord
+  include DeviseScim::Concerns::ScimTenant
+  # ... rest of your model
+end
+```
+
+**2. Run the generator with `--tenant-model`:**
+
+```bash
+rails g devise_scim:install User --multi-tenant --tenant-model=Org
+rails db:migrate
+```
+
+The generator creates an **additive** migration that only adds columns that do not already exist:
+
+```ruby
+class AddScimToOrgs < ActiveRecord::Migration[7.2]
+  def change
+    unless column_exists?(:orgs, :token_digest)
+      add_column :orgs, :token_digest, :string
+    end
+    unless column_exists?(:orgs, :auth_method)
+      add_column :orgs, :auth_method, :string, null: false, default: "token"
+    end
+    unless column_exists?(:orgs, :doorkeeper_application_id)
+      add_column :orgs, :doorkeeper_application_id, :bigint
+      add_foreign_key :orgs, :oauth_applications,
+                      column: :doorkeeper_application_id, on_delete: :nullify
+    end
+  end
+end
+```
+
+It also updates the initializer to set:
+
+```ruby
+config.tenant_model = "Org"
+```
+
+**FK column derivation:** the join table's tenant FK column is derived by underscoring the model name and appending `_id`:
+
+| `tenant_model` | FK column on `scim_tenant_users` |
+|---|---|
+| `DeviseScim::ScimTenant` (default) | `scim_tenant_id` |
+| `Org` | `org_id` |
+| `MyAccount` | `my_account_id` |
+
+The `tenant_fk_column` helper in the controller (`"#{tenant_model.demodulize.underscore}_id"`) performs this derivation at runtime.
+
+> [!IMPORTANT]
+> Your custom tenant model must respond to `active` (for `scim_active?`) and `token_digest` (for `authenticate_token`). If your model uses a different column for the human-readable name, override `scim_tenant_label_column` — see below.
+
+---
+
+## ScimTenant Concern API
+
+These methods are mixed into any model that `include DeviseScim::Concerns::ScimTenant`.
+
+### `authenticate_token(raw_token)` — class method
+
+```ruby
+DeviseScim::ScimTenant.authenticate_token("a3f8c2d1e9b7...")
+# => #<DeviseScim::ScimTenant id=1 name="Acme Corp"> or nil
+```
+
+Queries all records where `auth_method = "token"` and `active = true`, then BCrypt-compares each `token_digest` against `raw_token`. Returns the matching record or `nil`.
+
+Called by the middleware's `TokenStrategy` on every SCIM request in multi-tenant mode.
+
+### `rotate_token!` — instance method
+
+```ruby
+raw = tenant.rotate_token!
+# => "a3f8c2d1e9b7..."
+```
+
+Generates a 64-character hex token, BCrypt-hashes it into `token_digest`, and saves the record. Returns the raw token. The raw value is not stored anywhere — if you lose it, call `rotate_token!` again to issue a new one.
+
+### `scim_active?` — instance method
+
+```ruby
+tenant.scim_active?  # => true / false
+```
+
+Delegates to the `active` column. Override if your model uses a different boolean column.
+
+### `scim_tenant_label_column` — class method
+
+```ruby
+# Default:
+def self.scim_tenant_label_column
+  :name
+end
+```
+
+Override in your model to point at the column used as the human-readable label (validated for presence on save):
+
+```ruby
+class Org < ApplicationRecord
+  include DeviseScim::Concerns::ScimTenant
+
+  def self.scim_tenant_label_column
+    :display_name
+  end
+end
+```
+
+---
+
+## Console Commands
+
+**Create a tenant and obtain its token:**
+
+```ruby
+tenant = DeviseScim::ScimTenant.create!(name: "Acme Corp", auth_method: "token")
+raw = tenant.rotate_token!
+puts raw   # copy to clipboard — shown once only
+```
+
+**Rotate a token without downtime:**
+
+```ruby
+tenant = DeviseScim::ScimTenant.find_by!(name: "Acme Corp")
+new_raw = tenant.rotate_token!
+# 1. Update token_digest is persisted immediately.
+# 2. Update the IdP with new_raw.
+# 3. Old token is now invalid — there is no grace period.
+```
+
+> [!WARNING]
+> Token rotation is instantaneous. The old token is invalid as soon as `rotate_token!` returns. Update the IdP before rotating if you need zero downtime, or accept a brief authentication failure window.
+
+**Link a tenant to a Doorkeeper application (OAuth mode):**
+
+```ruby
+app = Doorkeeper::Application.find_by!(name: "Acme SCIM")
+tenant = DeviseScim::ScimTenant.find_by!(name: "Acme Corp")
+tenant.update!(auth_method: "oauth", doorkeeper_application: app)
+```
+
+**List all active tenants:**
+
+```ruby
+DeviseScim::ScimTenant.where(active: true).map { |t| [t.id, t.name, t.auth_method] }
+```
+
+**Deactivate a tenant:**
+
+```ruby
+DeviseScim::ScimTenant.find_by!(name: "Acme Corp").update!(active: false)
+# The middleware will reject all requests from this tenant's credentials immediately.
+```
+
+---
+
+## User Scoping
+
+In multi-tenant mode every read and write goes through `tenant_scope`, which uses a pure-Arel join — no string interpolation:
+
+```ruby
+# ApplicationController#tenant_scope (simplified)
+stu  = ScimTenantUser.arel_table
+dm   = devise_model.arel_table
+join = dm.join(stu).on(stu[:user_id].eq(dm[:id])).join_sources
+cond = stu[tenant_fk_column].eq(current_scim_tenant.id).and(stu[:active].eq(true))
+devise_model.joins(join).where(cond)
+```
+
+Consequences:
+
+- `GET /Users` returns only users with an **active** join record for the current tenant.
+- `GET /Users/:id`, `PUT /Users/:id`, `PATCH /Users/:id`, `DELETE /Users/:id` — if the user exists in the database but has no active join for this tenant, the controller raises `NotFound` and responds with 404. A tenant cannot read or modify another tenant's users.
+- Deprovisioning (`DELETE /Users/:id`) sets `active = false` on the join record, not on the user row itself (unless `soft_delete` is also true, in which case both are updated).
+
+---
+
+## User Exclusivity Scenarios
+
+The `user_exclusivity` and `exclusivity_conflict` settings control what happens when `POST /Users` arrives for a user who already has a join record in a **different** tenant.
+
+| `user_exclusivity` | `exclusivity_conflict` | Scenario: user is in tenant B, tenant A provisions them | Result |
+|---|---|---|---|
+| `:multiple` (default) | any | User exists in tenant B | New join created; user now active in both A and B |
+| `:one_to_one` | `:error` (default) | User exists in tenant B | 409 Conflict — user belongs to another tenant |
+| `:one_to_one` | `:reassign` | User exists in tenant B | Tenant B's join set to `active=false`; new active join created for tenant A |
+
+**`:multiple` (default):** a user may belong to any number of tenants simultaneously. This is the right choice when your users may legitimately exist in multiple organizations, or when you do not want SCIM provisioning in one IdP to affect another.
+
+**`:one_to_one`:** enforces that a user belongs to at most one tenant at a time. Use this when each user maps to exactly one organization.
+
+When `:one_to_one` + `:reassign`: the old join record is not deleted — it is deactivated (`active = false`). This preserves the audit trail. If the user is later re-provisioned by tenant B, a new join record is created.
+
+Note: "belongs to another tenant" means there is an `active = true` join record with a different tenant FK. A user with only inactive join records (previously deprovisioned) is treated as unowned.
+
+---
+
+## Claiming Existing Users
+
+When `POST /Users` arrives and no matching user exists in the database, the controller creates a new user record and an active join record. This is the standard "net-new" provisioning path.
+
+When `POST /Users` arrives and a user with that email already exists but has **no** active join for this tenant (e.g., the user was created manually in your app), the controller **claims** the user:
+
+1. Sets `user.scim_source = "scim"` if the column exists.
+2. Saves the user if changed.
+3. Creates a new `ScimTenantUser` join record with `active = true`, `provisioned_at = Time.current`, and `scim_claimed_at = Time.current`.
+4. Calls `adapter.after_provision`.
+
+`scim_claimed_at` being set indicates the user was claimed from a pre-existing account rather than created fresh. `provisioned_at` is always the timestamp of the first active assignment by this tenant.
+
+A claimed user is indistinguishable from a net-new user from the IdP's perspective — the response is HTTP 201 with the full SCIM user representation either way.
+
+Claiming an already-active member (join record exists and `active = true` for the same tenant) raises a 409 Conflict.
+
+---
+
+## Recommended UI Scaffold
+
+A minimal tenant management UI typically needs:
+
+- **Create form** — `name`, `auth_method` (`"token"` or `"oauth"`). On save, call `rotate_token!` and display the raw token in a one-time reveal modal. Never show it again.
+- **Token rotate button** — confirm intent, call `rotate_token!`, display raw token in a one-time reveal, remind the admin to update the IdP immediately.
+- **Doorkeeper app selector** — shown only when `auth_method = "oauth"`. Renders a `<select>` over `Doorkeeper::Application.all` and saves `doorkeeper_application_id`.
+- **Active toggle** — `update!(active: false/true)`. Deactivating immediately blocks all requests from that tenant's credentials.
+
+There is no built-in UI — the gem is intentionally a pure API layer. The above is a starting point for a standard Rails controller + views or a Hotwire component.