devise_scim 0.1.11

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ed8cd737f5466cd3adeeb6f4b1274d0807057f079759ce29f5313d4f4fc414ff
+  data.tar.gz: db59a0c733d18f8c319e8019beabd0e5735d6f9f49d7420c999f7ee419b82be0
+SHA512:
+  metadata.gz: 3424132891dd868226265693e899136de30c43184091e130144e3763ca3cea21fec366473af0346a1925ea7b0a6ba8cc091ed6f28d520292e108a9b894cff470
+  data.tar.gz: b2e3d46585e47da0ae8fb0de86359c1b31b783dc19ad8300d9cd681f6a586b4010a810a5409caa3cbb1d4829848aa5dd8a697665781d65c42ae2d4f142038859

data/AGENTS.md

@@ -0,0 +1,124 @@
+# AGENTS.md
+
+This is `devise_scim` — a SCIM 2.0 server engine for Rails + Devise applications.
+
+## Key directory layout
+
+| Path | Contents |
+|------|----------|
+| `lib/devise_scim/` | Gem code: configuration, auth strategies, filter system, SCIM structs, routing, adapter base class, Railtie/engine |
+| `app/controllers/devise_scim/` | Controller layer: UsersController, GroupsController, ServiceProviderController, SchemasController, ResourceTypesController, ApplicationController |
+| `lib/generators/` | `devise_scim:install` and `devise_scim:adapter` generators, plus all `.rb.tt` migration and initializer templates |
+| `spec/` | RSpec suite — unit specs for every subsystem, request specs for all endpoints |
+| `spec/internal/` | Combustion test app: `db/schema.rb`, `config/routes.rb`, minimal models, warden initializer |
+| `lib/devise_scim/rspec/` | Host-app test harness: shared examples for Users/Groups/discovery endpoints, `ScimHelpers`, FactoryBot factories |
+
+## Required checks before any commit
+
+Run all three before opening a PR. A single failure is a blocker.
+
+```sh
+bundle exec rspec                              # 0 failures required
+bundle exec rubocop                            # 0 offenses required (run --autocorrect for safe fixes first)
+bundle exec brakeman --force --no-pager        # 0 security warnings required
+```
+
+## Configuration contract
+
+All configuration lives in `DeviseScim::Configuration` (`lib/devise_scim/configuration.rb`). The generated initializer template is `lib/generators/devise_scim/templates/devise_scim.rb.tt`.
+
+**Rule:** changing a default or adding a new attribute requires updating **both** files. The `.tt` template is what host apps receive — it must stay in sync with `configuration.rb`.
+
+| Attribute | Valid values | Default |
+|-----------|-------------|---------|
+| `route_prefix` | Any string | `"/scim/v2"` |
+| `tenancy` | `:single`, `:multi` | `:single` |
+| `auth_method` | `:token`, `:oauth` | `:token` |
+| `token` | String or `nil` | `nil` |
+| `oauth_client_id` | String or `nil` | `nil` |
+| `oauth_client_secret` | String or `nil` | `nil` |
+| `devise_model` | String (class name) | `"User"` |
+| `tenant_model` | String (class name) | `"DeviseScim::ScimTenant"` |
+| `enable_groups` | `true`, `false` | `false` |
+| `soft_delete` | `true`, `false` | `true` |
+| `deprovision_manual_users` | `false`, `true`, `:error` | `false` |
+| `user_exclusivity` | `:multiple`, `:one_to_one` | `:multiple` |
+| `exclusivity_conflict` | `:error`, `:reassign` | `:error` |
+| `adapter` | String (class name) or `nil` | `nil` |
+
+Validation is in `Configuration#validate!` — add a corresponding guard there for any new attribute with a constrained value set.
+
+## Migration template location
+
+Templates live in `lib/generators/devise_scim/templates/*.rb.tt`.
+
+| Template | Purpose |
+|----------|---------|
+| `add_scim_to_users.rb.tt` | Adds SCIM columns to the user table (single- and multi-tenant) |
+| `create_scim_tenants.rb.tt` | Creates the `scim_tenants` table (built-in tenant, multi-tenant only) |
+| `add_scim_to_tenant.rb.tt` | Adds SCIM columns to an existing tenant table (`--tenant-model` flag) |
+| `create_scim_tenant_users.rb.tt` | Creates the `scim_tenant_users` join table (multi-tenant only) |
+| `devise_scim.rb.tt` | Initializer |
+| `application_scim_adapter.rb.tt` | Adapter skeleton (adapter generator) |
+
+The multi-tenant templates reference the `tenant_fk_column` helper method defined in `InstallGenerator` — it resolves to `scim_tenant_id` for the built-in model or `<tenant_model_underscored>_id` for a custom one. The `add_scim_to_tenant.rb.tt` template guards every `add_column` with `unless column_exists?` so it is safe to run against an existing table.
+
+## Auth strategies
+
+```
+lib/devise_scim/auth/
+  base_strategy.rb    # extracts Bearer token from Authorization header
+  token_strategy.rb   # compares against config.token (single) or ScimTenant.authenticate_token (multi)
+  oauth_strategy.rb   # validates Doorkeeper access tokens
+lib/devise_scim/middleware/authenticator.rb
+```
+
+`Authenticator` is a Rack middleware inserted early in the stack. It intercepts every request whose path starts with `route_prefix`, delegates to the appropriate strategy, and either sets `env["devise_scim.tenant"]` (multi-tenant) or returns a 401 SCIM error response. It also calls `warden.custom_failure!` so Warden does not swallow the 401.
+
+Do not move auth logic into controllers — the middleware layer is the single authentication boundary.
+
+## Filter system
+
+```
+lib/devise_scim/filter/
+  parser.rb        # tokenizer + recursive descent parser → AST
+  arel_visitor.rb  # walks AST → pure Arel conditions
+```
+
+The tokenizer uses explicit `m = regex.match(s)` calls rather than `gsub` to avoid `$&` clobbering. Keep it that way — `String#gsub` clears `$&` even for String patterns, which silently breaks the tokenizer.
+
+`ArelVisitor` maps SCIM attribute names to AR column names and emits only Arel nodes — **no string interpolation, ever**. If you add a new filterable attribute, add it to the column mapping in `ArelVisitor` and add a spec in `spec/filter/arel_visitor_spec.rb`.
+
+## Adding a new SCIM attribute
+
+1. Add the field to the relevant struct in `lib/devise_scim/scim/user.rb` or `lib/devise_scim/scim/group.rb`.
+2. Update `from_h` to parse the new attribute from the incoming hash.
+3. Update `to_h` to serialize it in the outgoing hash.
+4. Update `ScimAdapter#attributes_for_create`, `#attributes_for_update`, and `#to_scim` defaults in `lib/devise_scim/scim_adapter.rb` as appropriate.
+5. If the attribute is filterable, add the SCIM→column mapping to `ArelVisitor`.
+6. Add spec coverage: a unit spec for the struct, a request spec or shared-example assertion for the endpoint.
+
+## Test app
+
+`spec/internal/` is a [Combustion](https://github.com/pat/combustion) application loaded before the RSpec suite.
+
+- **Schema:** `spec/internal/db/schema.rb` is loaded at suite start via `ActiveRecord::Schema.define`. Do not drop or rename existing tables or columns — doing so breaks specs that depend on those structures.
+- **Routes:** `spec/internal/config/routes.rb` mounts three `scim_for` variants (default, groups-enabled, OAuth-enabled) to exercise conditional route generation. Keep all three.
+- **Models:** `spec/internal/app/models/` contains the minimal `User` and `ScimGroup` models used by the suite.
+
+When adding a new integration spec, use the existing models and schema. Add columns to the schema only when genuinely required, and add them to the end of the relevant `create_table` block.
+
+## Commit message convention
+
+- Imperative mood, under 72 characters on the subject line (`Add`, `Fix`, `Remove`, not `Added` / `Fixes`)
+- Body explains **why**, not what — the diff already shows what changed
+- Reference an issue number in the body when one exists (`Closes #123`)
+
+Example:
+
+```
+Add :reassign exclusivity_conflict mode
+
+Reassigning to a new tenant is safer than returning an error when an
+IdP reprovisioning cycle runs across a tenant boundary. Closes #47.
+```

data/CHANGELOG.md

@@ -0,0 +1,47 @@
+## [Unreleased]
+
+## [0.1.11] - 2026-04-28
+
+## [0.1.10] - 2026-04-28
+
+## [0.1.9] - 2026-04-28
+
+## [0.1.8] - 2026-04-28
+
+## [0.1.7] - 2026-04-28
+
+## [0.1.6] - 2026-04-28
+
+## [0.1.5] - 2026-04-28
+
+## [0.1.4] - 2026-04-28
+
+## [0.1.3] - 2026-04-28
+
+## [0.1.2] - 2026-04-27
+
+## [0.1.1] - 2026-04-27
+
+## [0.1.0] - 2026-04-27
+
+### Added
+
+- SCIM 2.0 server engine (RFC 7643 / 7644) mountable into any Rails + Devise application
+- `UsersController` — full CRUD with PATCH op application, re-provisioning matrix, and configurable deprovision behavior for manual users
+- `GroupsController` — protocol layer delegating to `ScimAdapter`; gracefully handles unimplemented group operations
+- `ServiceProviderController`, `SchemasController`, `ResourceTypesController` — static RFC 7643 discovery responses
+- `ScimAdapter` base class — pluggable attribute mapping for create/update, `to_scim`, lifecycle callbacks (`after_provision`, `after_deprovision`), and no-op group callbacks
+- Single-tenant and multi-tenant deployment modes (`config.tenancy`)
+- Bearer token authentication with bcrypt-safe digest comparison (`config.auth_method = :token`)
+- OAuth 2.0 client credentials authentication via optional Doorkeeper integration (`config.auth_method = :oauth`)
+- `DeviseScim::Concerns::ScimTenant` — brings the full tenant interface to host-app models (`authenticate_token`, `rotate_token!`, `scim_active?`)
+- `DeviseScim::Concerns::ScimGroupIdentifiable` — optional concern for group/role models to standardize `scim_group_uid` storage and lookup
+- SCIM filter parser — tokenizer and recursive-descent AST builder supporting `eq`, `ne`, `co`, `sw`, `ew`, `pr`, `gt`, `ge`, `lt`, `le`, `and`, `or`, `not`
+- `ArelVisitor` — pure Arel condition builder (no string interpolation) that maps SCIM attribute names to AR columns
+- `DeviseScim::Middleware::Authenticator` — Warden-aware middleware that resolves the tenant from the inbound credential
+- `scim_for` routing helper with `groups:` and `oauth:` opt-in flags
+- Install generator (`rails g devise_scim:install`) supporting single-tenant, multi-tenant, and custom tenant-model modes; Doorkeeper preflight check for OAuth/multi-tenant
+- Adapter generator (`rails g devise_scim:adapter`)
+- RSpec test harness (`require "devise_scim/rspec"`) — `ScimHelpers`, `ScimAssertions`, shared examples for Users, Groups, and discovery endpoints; FactoryBot factories
+- Minitest test harness (`require "devise_scim/minitest"`) with equivalent helpers and assertions
+- Comprehensive documentation: `README.md`, `docs/custom_adapter.md`, `docs/multi_tenant.md`, `docs/idp_setup.md`, `docs/testing.md`, `docs/contributing.md`

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Code of Conduct
+
+"devise_scim" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us through the [Issues](https://github.com/vertigo-prime/devise_scim/issues) tab.
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ben Vinson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,348 @@
+# devise_scim
+
+**SCIM 2.0 server for Rails + Devise**
+
+## What is this?
+
+`devise_scim` mounts a fully compliant SCIM 2.0 server inside any Rails + Devise application, handling user and group provisioning from identity providers like Okta, Azure AD, and OneLogin. Unlike most existing gems it supports both single- and multi-tenant architectures out of the box, is actively maintained, makes no external API calls (pure Ruby — no third-party SCIM SDK), and conforms strictly to RFC 7643 and RFC 7644.
+
+## Requirements
+
+- Ruby 3.2+
+- Rails 7.0+
+- Devise 4.9+
+- bcrypt
+
+## Doorkeeper
+
+> [!IMPORTANT]
+> `doorkeeper >= 5.6` is required **only** when using OAuth 2.0 authentication (`auth_method: :oauth`) or multi-tenant mode (`tenancy: :multi`). If the gem is missing, `DeviseScim::ConfigurationError` is raised at boot. Add `gem 'doorkeeper', '~> 5.6'` to your Gemfile **before** running the generator with `--oauth` or `--multi-tenant` — the generator performs a preflight check and will abort if it is absent.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'devise_scim'
+```
+
+```sh
+bundle install
+```
+
+## Quick start: single-tenant, bearer token
+
+**1. Run the generator**
+
+```sh
+rails g devise_scim:install User
+```
+
+This creates `config/initializers/devise_scim.rb` and the required migrations.
+
+**2. Configure the generated initializer**
+
+```ruby
+# config/initializers/devise_scim.rb
+DeviseScim.configure do |config|
+  config.route_prefix = "/scim/v2"
+  config.tenancy      = :single
+  config.auth_method  = :token
+  config.token        = ENV.fetch("SCIM_BEARER_TOKEN")
+  config.devise_model = "User"
+end
+```
+
+**3. Mount routes**
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  scim_for :users
+end
+```
+
+**4. Run migrations**
+
+```sh
+rails db:migrate
+```
+
+## Quick start: single-tenant, OAuth (Doorkeeper)
+
+**Prerequisites:** add Doorkeeper to your Gemfile first.
+
+```ruby
+gem 'doorkeeper', '~> 5.6'
+```
+
+```sh
+bundle install
+rails g devise_scim:install User --oauth
+rails db:migrate
+```
+
+The generator runs `rails g doorkeeper:install` for you if Doorkeeper's tables are not yet present (with your confirmation).
+
+The token endpoint is mounted at `{route_prefix}/oauth/token`. Configure your IdP to POST client credentials there.
+
+```ruby
+# config/initializers/devise_scim.rb
+DeviseScim.configure do |config|
+  config.route_prefix        = "/scim/v2"
+  config.tenancy             = :single
+  config.auth_method         = :oauth
+  config.oauth_client_id     = ENV.fetch("SCIM_CLIENT_ID")
+  config.oauth_client_secret = ENV.fetch("SCIM_CLIENT_SECRET")
+  config.devise_model        = "User"
+end
+```
+
+## Quick start: multi-tenant (built-in ScimTenant)
+
+```ruby
+# Gemfile
+gem 'doorkeeper', '~> 5.6'
+```
+
+```sh
+bundle install
+rails g devise_scim:install User --multi-tenant
+rails db:migrate
+```
+
+Create tenants in the console (see [Tenant management](#tenant-management)).
+
+## Quick start: multi-tenant (existing model)
+
+Use this when you already have an `Org` (or similar) model that should act as the SCIM tenant.
+
+```sh
+rails g devise_scim:install User --multi-tenant --tenant-model=Org
+rails db:migrate
+```
+
+Include the concern in your model:
+
+```ruby
+class Org < ApplicationRecord
+  include DeviseScim::Concerns::ScimTenant
+end
+```
+
+The generator adds only the columns that are missing — every `add_column` call in the migration is guarded with `unless column_exists?`.
+
+## Generator reference
+
+```sh
+rails g devise_scim:install <ModelName> [--oauth] [--multi-tenant] [--tenant-model=ModelName]
+```
+
+| Flag | Effect |
+|------|--------|
+| `--oauth` | Configures OAuth 2.0 client-credentials auth; requires Doorkeeper |
+| `--multi-tenant` | Generates tenant + join-table migrations; requires Doorkeeper |
+| `--tenant-model=Org` | Uses existing `Org` model instead of the built-in `DeviseScim::ScimTenant` |
+
+**Preflight behavior:** the generator checks whether `doorkeeper` appears in your Gemfile when `--oauth` or `--multi-tenant` is set. If Doorkeeper is in the Gemfile but its tables have not been generated yet, it prompts to run `rails g doorkeeper:install` before continuing.
+
+**Action order:**
+
+1. `preflight_check` — validates Doorkeeper presence
+2. `copy_user_migration` — `add_scim_to_<table>.rb`
+3. `copy_tenant_migrations` — `create_scim_tenants.rb` + `create_scim_tenant_users.rb` (or `add_scim_to_<tenant_table>.rb` if `--tenant-model` given)
+4. `copy_initializer` — `config/initializers/devise_scim.rb`
+
+> [!NOTE]
+> The `devise_model` value in the generated initializer is automatically set from the generator argument — no manual editing needed.
+
+## `rails g devise_scim:adapter`
+
+Generates a pre-filled `ApplicationScimAdapter` that overrides the base adapter's defaults:
+
+```sh
+rails g devise_scim:adapter
+# → app/scim/application_scim_adapter.rb
+```
+
+Then wire it up:
+
+```ruby
+config.adapter = "ApplicationScimAdapter"
+```
+
+## Configuration reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `route_prefix` | `String` | `"/scim/v2"` | Mount path for all SCIM endpoints |
+| `tenancy` | `:single` \| `:multi` | `:single` | Single or multi-tenant mode |
+| `auth_method` | `:token` \| `:oauth` | `:token` | Authentication strategy |
+| `token` | `String\|nil` | `nil` | Bearer token (single-tenant token auth only) |
+| `oauth_client_id` | `String\|nil` | `nil` | OAuth client ID (single-tenant OAuth only) |
+| `oauth_client_secret` | `String\|nil` | `nil` | OAuth client secret (single-tenant OAuth only) |
+| `devise_model` | `String` | `"User"` | Devise model class name |
+| `tenant_model` | `String` | `"DeviseScim::ScimTenant"` | Tenant model class name (multi-tenant only) |
+| `enable_groups` | `Boolean` | `false` | Mount `/Groups` endpoints |
+| `soft_delete` | `Boolean` | `true` | `true` = set `scim_active=false` on DELETE; `false` = destroy record |
+| `deprovision_manual_users` | `false` \| `true` \| `:error` | `false` | Behaviour when DELETE targets a manually-created user |
+| `user_exclusivity` | `:multiple` \| `:one_to_one` | `:multiple` | Whether a user may belong to multiple tenants (multi-tenant only) |
+| `exclusivity_conflict` | `:error` \| `:reassign` | `:error` | Conflict resolution when `user_exclusivity: :one_to_one` (multi-tenant only) |
+| `adapter` | `String\|nil` | `nil` | Adapter class name; uses built-in defaults when `nil` |
+
+## Routes reference
+
+`scim_for :users` mounts the following routes under `route_prefix` (default `/scim/v2`):
+
+```
+GET    /scim/v2/Users
+POST   /scim/v2/Users
+GET    /scim/v2/Users/:id
+PUT    /scim/v2/Users/:id
+PATCH  /scim/v2/Users/:id
+DELETE /scim/v2/Users/:id
+
+# when enable_groups: true
+GET    /scim/v2/Groups
+POST   /scim/v2/Groups
+GET    /scim/v2/Groups/:id
+PUT    /scim/v2/Groups/:id
+PATCH  /scim/v2/Groups/:id
+DELETE /scim/v2/Groups/:id
+
+# when auth_method: :oauth
+POST   /scim/v2/oauth/token
+
+# always present
+GET    /scim/v2/ServiceProviderConfig
+GET    /scim/v2/Schemas
+GET    /scim/v2/ResourceTypes
+```
+
+Override the prefix with the `at:` option:
+
+```ruby
+scim_for :users, at: "/api/scim/v2"
+```
+
+## Tenant management
+
+```ruby
+# Create a tenant
+tenant = DeviseScim::ScimTenant.create!(name: "Acme Corp", auth_method: "token", active: true)
+
+# Issue a bearer token — only returned once, store it securely
+raw_token = tenant.rotate_token!
+```
+
+> [!WARNING]
+> `rotate_token!` returns the raw token **exactly once**. Only the bcrypt digest is persisted. Store the raw token immediately (e.g. copy it to your IdP's configuration) — it cannot be retrieved again. Call `rotate_token!` again to issue a replacement, which invalidates the previous token.
+
+```ruby
+# Link to a Doorkeeper OAuth application (OAuth auth method)
+app = Doorkeeper::Application.find_by(name: "Acme IdP")
+tenant.update!(doorkeeper_application: app, auth_method: "oauth")
+
+# Check active status
+tenant.scim_active? # => true / false
+
+# Deactivate (blocks all further SCIM requests for this tenant)
+tenant.update!(active: false)
+```
+
+## User source tracking and deprovision
+
+The `scim_source` column on the user record tracks how the user was created:
+
+| Value | Meaning |
+|-------|---------|
+| `"scim"` | Created or claimed via SCIM provisioning |
+| `nil` | Created manually (e.g. sign-up, seed data, console) |
+
+The `deprovision_manual_users` config controls what happens when a DELETE request targets a user with `scim_source: nil`:
+
+| `scim_source` | `deprovision_manual_users` | Result |
+|---------------|---------------------------|--------|
+| `"scim"` | any | Deprovision (soft-delete or destroy) — 204 No Content |
+| `nil` | `false` (default) | Skip silently — 200 OK |
+| `nil` | `true` | Deprovision — 204 No Content |
+| `nil` | `:error` | 409 Conflict |
+
+## Re-provisioning
+
+When a POST to `/Users` matches a user with `scim_active: false` (previously deprovisioned), the gem re-provisions them rather than returning a conflict:
+
+- `scim_active` is set to `true`
+- `scim_deprovisioned_at` is cleared
+- `after_provision` callback is invoked on the adapter
+
+This allows IdPs to deprovision and later re-provision the same user without manual intervention.
+
+## User exclusivity (multi-tenant)
+
+Available only in `tenancy: :multi` mode.
+
+| `user_exclusivity` | Behaviour |
+|--------------------|-----------|
+| `:multiple` (default) | A user may belong to any number of tenants simultaneously |
+| `:one_to_one` | A user may belong to at most one tenant at a time |
+
+When `:one_to_one` is set and a POST `/Users` matches a user already assigned to a different tenant, `exclusivity_conflict` controls the outcome:
+
+| `exclusivity_conflict` | Outcome |
+|------------------------|---------|
+| `:error` (default) | 409 Conflict |
+| `:reassign` | Deactivates the old tenant join record, creates a new one for the requesting tenant |
+
+## Group provisioning
+
+The gem handles the SCIM protocol layer for groups; business logic lives in your adapter. When `enable_groups: true`, implement the following methods in your `ApplicationScimAdapter`:
+
+```ruby
+def handle_group_create  # called on POST /Groups
+def handle_group_update  # called on PUT/PATCH /Groups/:id
+def handle_group_destroy # called on DELETE /Groups/:id
+def group_to_scim        # returns a DeviseScim::Scim::Group instance
+```
+
+The base adapter raises `NotImplementedError` for `group_to_scim` and no-ops the other callbacks — groups succeed at the protocol level until you implement the methods. See `docs/custom_adapter.md` for a full walkthrough.
+
+## Test harness
+
+The gem ships a test harness you can include in your host app's test suite.
+
+**RSpec:**
+
+```ruby
+# spec/rails_helper.rb
+require "devise_scim/rspec"
+```
+
+```ruby
+RSpec.describe "SCIM Users" do
+  it_behaves_like "a SCIM Users endpoint", devise_model: User
+end
+```
+
+**Minitest:**
+
+```ruby
+require "devise_scim/minitest"
+
+class ScimUsersTest < ActionDispatch::IntegrationTest
+  include DeviseScim::Minitest::ScimAssertions
+  # ...
+end
+```
+
+The shared RSpec example covers index, show, create, replace, PATCH update, delete, re-provisioning, authentication enforcement, and multi-tenant scenarios. See `docs/testing.md` for available options and writing custom assertions.
+
+## License
+
+MIT. Used at your own risk. No liability is held by the author.
+
+## Contributing
+
+This gem was developed with significant assistance from Claude (Anthropic). Contributions and audits welcome, AI or otherwise.
+
+1. Please follow the [contributing guidelines](CONTRIBUTING.md) for submitting pull requests and reporting issues.
+2. Ensure your code adheres to the [code of conduct](CODE_OF_CONDUCT.md) and is tested with the provided test harness.

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require "brakeman"
+
+namespace :brakeman do
+  desc "Run Brakeman security scan"
+  task :check do
+    Brakeman.run(app_path: ".", force_scan: true, print_report: true, quiet: false)
+  end
+end
+
+task default: %i[spec rubocop brakeman:check]

data/app/controllers/devise_scim/application_controller.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module DeviseScim
+  class ApplicationController < ActionController::API
+    before_action :set_content_type
+
+    rescue_from NotFound,      with: :render_not_found
+    rescue_from Conflict,      with: :render_conflict
+    rescue_from InvalidFilter, with: :render_invalid_filter
+
+    protected
+
+    def current_scim_tenant
+      request.env["devise_scim.tenant"]
+    end
+
+    def multi_tenant?
+      DeviseScim.configuration.tenancy == :multi
+    end
+
+    def devise_model
+      DeviseScim.configuration.devise_model.constantize
+    end
+
+    def tenant_scope
+      if multi_tenant? && current_scim_tenant
+        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)
+      else
+        devise_model.all
+      end
+    end
+
+    # "DeviseScim::ScimTenant" → "scim_tenant_id"; "Org" → "org_id"
+    def tenant_fk_column
+      "#{DeviseScim.configuration.tenant_model.demodulize.underscore}_id"
+    end
+
+    def scim_adapter_for(record, scim_object)
+      klass = (DeviseScim.configuration.adapter || "DeviseScim::ScimAdapter").constantize
+      klass.new(record, scim_object, tenant: current_scim_tenant)
+    end
+
+    def render_scim(obj, status: :ok)
+      render body: obj.to_json, status: status, content_type: "application/scim+json"
+    end
+
+    private
+
+    def set_content_type
+      response.headers["Content-Type"] = "application/scim+json"
+    end
+
+    def render_not_found(err)
+      render_scim(Scim::Error.not_found(err.message), status: :not_found)
+    end
+
+    def render_conflict(err)
+      render_scim(Scim::Error.conflict(err.message), status: :conflict)
+    end
+
+    def render_invalid_filter(err)
+      render_scim(Scim::Error.bad_request(err.message, scim_type: "invalidFilter"), status: :bad_request)
+    end
+  end
+end