better_auth-scim 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26a7c3c25bebca9f5019560372ecfb0a0c735527fcd04e7da74b75875ce85114
-  data.tar.gz: e1ec7062829cc935822883aab00490d8dfd33b44b6e8f3ad0a43933a684d2c69
+  metadata.gz: 8ffe12400df4278b53ac2c8673635a6db362e875fb85c3d268e079a97b2a0568
+  data.tar.gz: d52b222ff8315e95df2df47922acc44e4eaa625a9df903d472a55d63c9130e90
 SHA512:
-  metadata.gz: 3bd60c706aeab0fde80fcd123b5e3f9aa20d6d90c3cb5cabcc688503e7b810524a12f5a140f780da9d593bc61e27292abc25d00b2b5c758d829cb623012da2aa
-  data.tar.gz: 0b741fd545a206c5a38b906ed7c8640bee7859cfce090708e8256062d791deb0a7017ae52f36554ae56827dbd7f513727f632b7e00b9f4b633586f4a7ef7a821
+  metadata.gz: bf07cda2658e52e8f3bc61164298df2b785f81ed1227e66ae2e03c9217e9d426fddc8f4d487c68f8212d6995d5f33a82efbf4f96a973116ddc4cd518bf5e7996
+  data.tar.gz: 4736ac7244374c48111234fb9b210b6b54e5330bc3f1f1063e34e2397cd08c544f03f8f33f5084b48a77fe6800030ba27d6b976568adca8be1f63678991de44f

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.10.0 - 2026-05-21
+
+- Improved SCIM route, adapter, user, and rate-limit coverage.
+- Clarified SCIM setup docs and runtime dependencies.
+
 ## 0.7.0 - 2026-05-05
 
 - Changed generated SCIM provider tokens to use hashed storage by default. Set `store_scim_token: "plain"` only when plaintext database storage is intentionally required.

data/README.md

@@ -14,9 +14,7 @@ require "better_auth/scim"
 
 BetterAuth.auth(
   plugins: [
-    BetterAuth::Plugins.scim(
-      provider_ownership: { enabled: true }
-    )
+    BetterAuth::Plugins.scim
   ]
 )
 ```
@@ -42,6 +40,17 @@ Implemented API methods include token generation, provider connection management
 Options use Ruby snake_case names: `store_scim_token`, `default_scim`, `provider_ownership`, `required_role`, `before_scim_token_generated`, and `after_scim_token_generated`.
 `store_scim_token` defaults to `"hashed"` so generated SCIM provider tokens are
 not stored in plaintext.
+`provider_ownership` defaults to `{ enabled: true }`, a Ruby-specific security
+default that scopes personal SCIM provider management to the user who generated
+the provider token. To preserve legacy shared management of non-organization
+providers, configure `provider_ownership: { enabled: false }`; only use that mode
+when all authenticated users who can access SCIM management routes are trusted to
+view, rotate, or delete unowned personal providers.
+
+Organization-scoped SCIM bearer tokens must include the organization component
+generated by `generate_scim_token`. Removing that component invalidates the token.
+Deleting a SCIM user unlinks the current provider account first; the underlying
+Better Auth user is deleted only when no other accounts remain.
 
 The plugin exposes upstream-style surface metadata:
 
@@ -52,3 +61,23 @@ The plugin exposes upstream-style surface metadata:
 ## Production recommendations
 
 - In the accounts table (`accounts` or the configured table name), use a unique composite index on `(providerId, accountId)` to prevent duplicate SCIM accounts under concurrent provisioning. The gem does not create this constraint automatically because index syntax and migrations depend on your database adapter and application.
+
+## Testing
+
+Run the default SCIM package suite from this package directory:
+
+```sh
+rbenv exec bundle exec rake test
+```
+
+The suite includes SCIM route coverage for memory, custom, secondary-storage,
+and database-backed rate limiting. It also runs a live SQLite adapter smoke test
+against a temporary database.
+
+External adapter smoke tests are skip-gated. They run only when the relevant gem
+and service are available:
+
+- PostgreSQL: `BETTER_AUTH_POSTGRES_URL`
+- MySQL: `BETTER_AUTH_MYSQL_HOST`, `BETTER_AUTH_MYSQL_PORT`, `BETTER_AUTH_MYSQL_USER`, `BETTER_AUTH_MYSQL_PASSWORD`, `BETTER_AUTH_MYSQL_DATABASE`
+- MSSQL: `BETTER_AUTH_MSSQL_URL`, `BETTER_AUTH_MSSQL_MASTER_URL`
+- MongoDB: `BETTER_AUTH_MONGODB_URL`

data/lib/better_auth/plugins/scim.rb

@@ -24,7 +24,7 @@ module BetterAuth
     singleton_class.remove_method(:scim) if singleton_class.method_defined?(:scim) || singleton_class.private_method_defined?(:scim)
 
     def scim(options = {})
-      config = {store_scim_token: "hashed"}.merge(normalize_hash(options))
+      config = {store_scim_token: "hashed", provider_ownership: {enabled: true}}.merge(normalize_hash(options))
       Plugin.new(
         id: "scim",
         version: BetterAuth::SCIM::VERSION,
@@ -61,6 +61,7 @@ module BetterAuth
 
       {
         scimProvider: {
+          model_name: "scim_providers",
           fields: scim_provider_fields
         }
       }

data/lib/better_auth/scim/mappings.rb

@@ -5,9 +5,10 @@ module BetterAuth
     module_function
 
     def scim_user_update(body)
+      email = scim_primary_email(body)&.downcase
       {
-        email: scim_primary_email(body)&.downcase,
-        name: scim_display_name(body, body[:user_name].to_s),
+        email: email,
+        name: scim_display_name(body, email),
         updatedAt: Time.now
       }.compact
     end

data/lib/better_auth/scim/middlewares.rb

@@ -23,6 +23,7 @@ module BetterAuth
             where: [{field: "providerId", value: provider_id}].tap { |where| where << {field: "organizationId", value: organization_id} if organization_id }
           )
           raise scim_error("UNAUTHORIZED", "Invalid SCIM token") unless provider
+          raise scim_error("UNAUTHORIZED", "Invalid SCIM token") unless provider["organizationId"].to_s == organization_id.to_s
           raise scim_error("UNAUTHORIZED", "Invalid SCIM token") unless scim_token_matches?(ctx, config, token, provider.fetch("scimToken"))
         end
 

data/lib/better_auth/scim/provider_management.rb

@@ -49,7 +49,7 @@ module BetterAuth
       end
     end
 
-    def scim_assert_provider_access!(ctx, user_id, provider, required_roles)
+    def scim_assert_provider_access!(ctx, user_id, provider, required_roles, config = {})
       return unless provider
 
       organization_id = provider["organizationId"]
@@ -59,6 +59,8 @@ module BetterAuth
         member = scim_find_organization_member(ctx, user_id, organization_id)
         raise APIError.new("FORBIDDEN", message: "You must be a member of the organization to access this provider") unless member
         raise APIError.new("FORBIDDEN", message: "Insufficient role for this operation") unless scim_has_required_role?(member.fetch("role", ""), required_roles)
+      elsif scim_provider_ownership_enabled?(config)
+        raise APIError.new("FORBIDDEN", message: "You must be the owner to access this provider") unless provider["userId"] == user_id
       elsif provider.key?("userId") && provider["userId"] && provider["userId"] != user_id
         raise APIError.new("FORBIDDEN", message: "You must be the owner to access this provider")
       end

data/lib/better_auth/scim/routes.rb

@@ -7,7 +7,7 @@ module BetterAuth
     module_function
 
     def scim_generate_token_endpoint(config)
-      Endpoint.new(path: "/scim/generate-token", method: "POST", metadata: scim_openapi_metadata("Generates a new SCIM token for the given provider")) do |ctx|
+      Endpoint.new(path: "/scim/generate-token", method: "POST", metadata: scim_generate_token_openapi_metadata) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         raw_provider_id = body[:provider_id]
@@ -34,7 +34,7 @@ module BetterAuth
 
         existing = ctx.context.adapter.find_one(model: "scimProvider", where: [{field: "providerId", value: provider_id}])
         if existing
-          scim_assert_provider_access!(ctx, session.fetch(:user).fetch("id"), existing, required_roles)
+          scim_assert_provider_access!(ctx, session.fetch(:user).fetch("id"), existing, required_roles, config)
           ctx.context.adapter.delete(model: "scimProvider", where: [{field: "id", value: existing.fetch("id")}])
         end
 
@@ -61,6 +61,8 @@ module BetterAuth
           if organization_id
             member = org_memberships[organization_id]
             member && scim_has_required_role?(member.fetch("role", ""), required_roles)
+          elsif scim_provider_ownership_enabled?(config)
+            provider["userId"] == user_id
           else
             !provider.key?("userId") || provider["userId"].nil? || provider["userId"] == user_id
           end
@@ -73,17 +75,17 @@ module BetterAuth
       Endpoint.new(path: "/scim/get-provider-connection", method: "GET", metadata: scim_openapi_metadata("Get SCIM provider connection.")) do |ctx|
         session = Routes.current_session(ctx)
         provider = scim_provider_by_provider_id!(ctx, scim_provider_id_query(ctx))
-        scim_assert_provider_access!(ctx, session.fetch(:user).fetch("id"), provider, scim_required_roles(ctx, config))
+        scim_assert_provider_access!(ctx, session.fetch(:user).fetch("id"), provider, scim_required_roles(ctx, config), config)
         ctx.json(scim_normalized_provider(provider))
       end
     end
 
     def scim_delete_provider_connection_endpoint(config)
-      Endpoint.new(path: "/scim/delete-provider-connection", method: "POST", metadata: scim_openapi_metadata("Delete SCIM provider connection.")) do |ctx|
+      Endpoint.new(path: "/scim/delete-provider-connection", method: "POST", metadata: scim_delete_provider_openapi_metadata) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         provider = scim_provider_by_provider_id!(ctx, body[:provider_id])
-        scim_assert_provider_access!(ctx, session.fetch(:user).fetch("id"), provider, scim_required_roles(ctx, config))
+        scim_assert_provider_access!(ctx, session.fetch(:user).fetch("id"), provider, scim_required_roles(ctx, config), config)
         ctx.context.adapter.delete(model: "scimProvider", where: [{field: "providerId", value: provider.fetch("providerId")}])
         ctx.json({success: true})
       end
@@ -168,8 +170,12 @@ module BetterAuth
 
     def scim_delete_user_endpoint(config)
       Endpoint.new(path: "/scim/v2/Users/:userId", method: "DELETE", metadata: scim_hidden_metadata("Delete SCIM user.", [*SCIM_SUPPORTED_MEDIA_TYPES, ""]), use: [scim_auth_middleware(config)]) do |ctx|
-        user, = scim_find_user_with_account!(ctx)
-        ctx.context.internal_adapter.delete_user(user.fetch("id"))
+        user, account = scim_find_user_with_account!(ctx)
+        ctx.context.adapter.transaction do
+          ctx.context.internal_adapter.delete_account(account.fetch("id"))
+          remaining_accounts = ctx.context.internal_adapter.find_accounts(user.fetch("id"))
+          ctx.context.internal_adapter.delete_user(user.fetch("id")) if remaining_accounts.empty?
+        end
         ctx.json(nil, status: 204)
       end
     end
@@ -177,9 +183,14 @@ module BetterAuth
     def scim_list_users_endpoint(config)
       Endpoint.new(path: "/scim/v2/Users", method: "GET", metadata: scim_hidden_metadata("List SCIM users.", SCIM_SUPPORTED_MEDIA_TYPES), use: [scim_auth_middleware(config)]) do |ctx|
         provider = ctx.context.scim_provider
+        filter_value = nil
+        if ctx.query[:filter] || ctx.query["filter"]
+          _filter_field, filter_value = scim_parse_filter(ctx.query[:filter] || ctx.query["filter"])
+        end
+        start_index, count = scim_list_pagination(ctx.query)
+        empty_list = {schemas: [SCIM_LIST_RESPONSE_SCHEMA], totalResults: 0, itemsPerPage: 0, startIndex: start_index, Resources: []}
         accounts = ctx.context.adapter.find_many(model: "account", where: [{field: "providerId", value: provider.fetch("providerId")}])
         account_user_ids = accounts.map { |account| account.fetch("userId") }.uniq
-        empty_list = {schemas: [SCIM_LIST_RESPONSE_SCHEMA], totalResults: 0, itemsPerPage: 0, startIndex: 1, Resources: []}
         if account_user_ids.empty?
           ctx.json(empty_list)
         else
@@ -198,15 +209,22 @@ module BetterAuth
             ctx.json(empty_list)
           else
             where = [{field: "id", value: user_ids, operator: "in"}]
-            if ctx.query[:filter] || ctx.query["filter"]
-              _filter_field, filter_value = scim_parse_filter(ctx.query[:filter] || ctx.query["filter"])
+            if filter_value
               where << {field: "email", value: filter_value.to_s.downcase, operator: "eq"}
             end
 
-            users = ctx.context.internal_adapter.list_users(where: where, sort_by: {field: "email", direction: "asc"})
+            total_results = ctx.context.internal_adapter.count_total_users(where: where)
+            offset = start_index - 1
+            limit = count || ((offset > 0) ? [total_results - offset, 0].max : nil)
+            users = ctx.context.internal_adapter.list_users(
+              where: where,
+              sort_by: {field: "email", direction: "asc"},
+              limit: limit,
+              offset: offset.positive? ? offset : nil
+            )
             accounts_by_user = accounts.each_with_object({}) { |account, result| result[account.fetch("userId")] ||= account }
             resources = users.map { |user| scim_user_resource(user, accounts_by_user[user.fetch("id")], ctx.context.base_url) }
-            ctx.json({schemas: [SCIM_LIST_RESPONSE_SCHEMA], totalResults: resources.length, itemsPerPage: resources.length, startIndex: 1, Resources: resources})
+            ctx.json({schemas: [SCIM_LIST_RESPONSE_SCHEMA], totalResults: total_results, itemsPerPage: resources.length, startIndex: start_index, Resources: resources})
           end
         end
       end
@@ -293,5 +311,27 @@ module BetterAuth
 
       [user, account]
     end
+
+    def scim_list_pagination(query)
+      start_index = scim_positive_integer(query[:startIndex] || query[:start_index] || query["startIndex"] || query["start_index"], 1)
+      count = if query.key?(:count) || query.key?("count")
+        scim_non_negative_integer(query[:count] || query["count"], 0)
+      end
+      [start_index, count]
+    end
+
+    def scim_positive_integer(value, fallback)
+      parsed = Integer(value)
+      parsed.positive? ? parsed : fallback
+    rescue ArgumentError, TypeError
+      fallback
+    end
+
+    def scim_non_negative_integer(value, fallback)
+      parsed = Integer(value)
+      parsed.negative? ? fallback : parsed
+    rescue ArgumentError, TypeError
+      fallback
+    end
   end
 end

data/lib/better_auth/scim/scim_filters.rb

@@ -6,7 +6,7 @@ module BetterAuth
 
     def scim_parse_filter(filter)
       match = filter.to_s.match(/\A\s*([^\s]+)\s+(eq|ne|co|sw|ew|pr)\s*(?:"([^"]*)"|([^\s]+))?\s*\z/i)
-      raise scim_error("BAD_REQUEST", "Invalid SCIM filter", scim_type: "invalidFilter") unless match
+      raise scim_error("BAD_REQUEST", "Invalid filter expression", scim_type: "invalidFilter") unless match
 
       field = match[1]
       operator = match[2].downcase

data/lib/better_auth/scim/scim_metadata.rb

@@ -29,6 +29,48 @@ module BetterAuth
       }
     end
 
+    def scim_generate_token_openapi_metadata
+      {
+        openapi: {
+          summary: "Generates a new SCIM token for the given provider",
+          requestBody: OpenAPI.json_request_body(
+            OpenAPI.object_schema(
+              {
+                provider_id: {type: "string", description: "SCIM provider identifier"},
+                organization_id: {type: "string", description: "Organization ID to restrict the SCIM token to"}
+              },
+              required: ["provider_id"]
+            )
+          ),
+          responses: scim_openapi_responses.merge(
+            "201" => OpenAPI.json_response(
+              "SCIM token generated",
+              OpenAPI.object_schema({scimToken: {type: "string"}}, required: ["scimToken"])
+            )
+          )
+        }
+      }
+    end
+
+    def scim_delete_provider_openapi_metadata
+      {
+        openapi: {
+          summary: "Delete SCIM provider connection.",
+          requestBody: OpenAPI.json_request_body(
+            OpenAPI.object_schema(
+              {
+                provider_id: {type: "string", description: "SCIM provider identifier"}
+              },
+              required: ["provider_id"]
+            )
+          ),
+          responses: scim_openapi_responses.merge(
+            "200" => OpenAPI.json_response("SCIM provider connection deleted", OpenAPI.success_response_schema)
+          )
+        }
+      }
+    end
+
     def scim_openapi_responses
       {
         "200" => {description: "Success"},

data/lib/better_auth/scim/scim_tokens.rb

@@ -48,7 +48,7 @@ module BetterAuth
     def scim_default_provider(config, provider_id, organization_id)
       Array(config[:default_scim]).find do |provider|
         candidate = normalize_hash(provider)
-        next true if candidate[:provider_id].to_s == provider_id.to_s && organization_id.to_s.empty?
+        next true if candidate[:provider_id].to_s == provider_id.to_s && organization_id.to_s.empty? && candidate[:organization_id].to_s.empty?
 
         candidate[:provider_id].to_s == provider_id.to_s &&
           !organization_id.to_s.empty? &&

data/lib/better_auth/scim/validation.rb

@@ -4,6 +4,9 @@ module BetterAuth
   module Plugins
     module_function
 
+    SCIM_MAX_PATCH_OPERATIONS = 100
+    SCIM_MAX_PATCH_VALUE_DEPTH = 5
+
     def scim_validate_user_body!(body)
       raise scim_error("BAD_REQUEST", BASE_ERROR_CODES["VALIDATION_ERROR"]) unless body[:user_name].is_a?(String)
       raise scim_error("BAD_REQUEST", BASE_ERROR_CODES["VALIDATION_ERROR"]) if body[:user_name].empty?
@@ -26,8 +29,13 @@ module BetterAuth
       schemas = Array(body[:schemas])
       raise scim_error("BAD_REQUEST", "Invalid schemas for PatchOp") unless schemas.include?("urn:ietf:params:scim:api:messages:2.0:PatchOp")
 
-      Array(body[:operations]).each_with_index do |operation, index|
-        op = normalize_hash(operation)[:op]
+      operations = body[:operations]
+      raise scim_error("BAD_REQUEST", BASE_ERROR_CODES["VALIDATION_ERROR"]) unless operations.is_a?(Array)
+      raise scim_error("BAD_REQUEST", "Too many SCIM patch operations") if operations.length > SCIM_MAX_PATCH_OPERATIONS
+
+      operations.each_with_index do |operation, index|
+        normalized = normalize_hash(operation)
+        op = normalized[:op]
         next if op.nil? || op.to_s.empty?
 
         unless op.is_a?(String)
@@ -38,14 +46,19 @@ module BetterAuth
 
         raise scim_patch_validation_error("[body.Operations.#{index}.op] Invalid option: expected one of \"replace\"|\"add\"|\"remove\"")
       end
+
+      operations.each { |operation| scim_validate_patch_value_depth!(normalize_hash(operation)[:value]) }
+    end
+
+    def scim_validate_patch_value_depth!(value, depth = 0)
+      return unless value.is_a?(Hash)
+      raise scim_error("BAD_REQUEST", "SCIM patch value is too deeply nested") if depth > SCIM_MAX_PATCH_VALUE_DEPTH
+
+      value.each_value { |nested| scim_validate_patch_value_depth!(nested, depth + 1) }
     end
 
     def scim_patch_validation_error(message)
-      APIError.new(
-        "BAD_REQUEST",
-        message: BASE_ERROR_CODES["VALIDATION_ERROR"],
-        body: {code: "VALIDATION_ERROR", message: message}
-      )
+      scim_error("BAD_REQUEST", message)
     end
   end
 end

data/lib/better_auth/scim/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   module SCIM
-    VERSION = "0.8.0"
+    VERSION = "0.10.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_auth-scim
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Sebastian Sala
@@ -85,6 +85,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: standardrb
   requirement: !ruby/object:Gem::Requirement
@@ -127,14 +141,14 @@ files:
 - lib/better_auth/scim/utils.rb
 - lib/better_auth/scim/validation.rb
 - lib/better_auth/scim/version.rb
-homepage: https://github.com/sebasxsala/better-auth
+homepage: https://github.com/sebasxsala/better-auth-rb
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/sebasxsala/better-auth
-  source_code_uri: https://github.com/sebasxsala/better-auth
-  changelog_uri: https://github.com/sebasxsala/better-auth/blob/main/packages/better_auth-scim/CHANGELOG.md
-  bug_tracker_uri: https://github.com/sebasxsala/better-auth/issues
+  homepage_uri: https://github.com/sebasxsala/better-auth-rb
+  source_code_uri: https://github.com/sebasxsala/better-auth-rb
+  changelog_uri: https://github.com/sebasxsala/better-auth-rb/blob/main/packages/better_auth-scim/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sebasxsala/better-auth-rb/issues
 rdoc_options: []
 require_paths:
 - lib