scimitar 2.11.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cb5109af12b712e491949d6627588dff6a4d70877253be26c4ee0af3b56c61e
-  data.tar.gz: 4271bb70e89fd17b97103073bc063de748e261b62b243fa0681b3e2934085f77
+  metadata.gz: 4e8493f9f42ec39cc98639167c39e60261400208a011e21d202116d5ca43daff
+  data.tar.gz: fb1fe271b42006d0e0054207d873b18ad15851d76597bf78c591f2254eab6688
 SHA512:
-  metadata.gz: aed187b7c9cc56fb1b0c3bae86b3274c6753078a71fb4fa6162776c056033edf19c085b830cfc3867acf7ab4e12732a6fe8100d758bd107840edd2e26c068aa0
-  data.tar.gz: f753d11931026a98c27d27525e88e512ee5a40d1920533243b352f6345ddb285de8efb38d6101afd360156b618365805c4a9bc440941701d7e9cd9cee5488810
+  metadata.gz: 4f2d68d767cdf33d97684697466dbca05122783f6a081010f874ef8546cc684c3fe9ca8c72478c6214a7493ffc3d80dfd8a742d03c0748968a32b3dc76980e05
+  data.tar.gz: 456146fa9cd91c44208e689ba4ba5663626e4ba8bcd3fbdcd592e78785e5af63449d41e68c465e84f8567352a505d02a200b8fbca36b38b7a9d61bc7784b73b8

data/README.md

@@ -1,8 +1,8 @@
 # Scimitar
 
 [![Gem Version](https://badge.fury.io/rb/scimitar.svg)](https://badge.fury.io/rb/scimitar)
-[![Build Status](https://app.travis-ci.com/RIPAGlobal/scimitar.svg?branch=main)](https://app.travis-ci.com/RIPAGlobal/scimitar)
-[![License](https://img.shields.io/badge/license-mit-blue.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://github.com/pond/scimitar/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/pond/scimitar/actions/)
+[![License](https://img.shields.io/badge/license-mit-blue.svg)](https://github.com/pond/scimitar/blob/main/LICENSE.txt)
 
 A SCIM v2 API endpoint implementation for Ruby On Rails.
 
@@ -58,17 +58,35 @@ All three are provided under the MIT license. Scimitar is too.
 
 Scimitar is best used with Rails and ActiveRecord, but it can be used with other persistence back-ends too - you just have to do more of the work in controllers using Scimitar's lower level controller subclasses, rather than relying on Scimitar's higher level ActiveRecord abstractions.
 
+Some aspects of configuration are handled via a `config/initializers/scimitar.rb` file. It is **strongly recommended** that you wrap Scimitar configuration with `Rails.application.config.to_prepare do...` so that any changes you make to configuration during local development are reflected via auto-reload, rather than requiring a server restart:
+
+```ruby
+Rails.application.config.to_prepare do
+  Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
+    # ...see subsections below for configuration options...
+  end
+end
+```
+
+In general, Scimitar's own development and tests assume this approach. If you choose to put the configuration directly into an initializer file without the `to_prepare` wrapper, you will be at a _slightly_ higher risk of tripping over unrecognised Scimitar bugs; please make sure that your own application test coverage is reasonably comprehensive.
+
 ### Authentication
 
-Noting the _Security_ section later - to set up an authentication method, create a `config/initializers/scimitar.rb` in your Rails application and define a token-based authenticator and/or a username-password authenticator in the [engine configuration section documented in the sample file](https://github.com/pond/scimitar/blob/main/config/initializers/scimitar.rb). For example:
+You can define a token-based authenticator, a basic username-password authenticator or a custom authenticator in the [engine configuration section documented in the sample file](https://github.com/pond/scimitar/blob/main/config/initializers/scimitar.rb) and examples of these are given in the sub-sections below. In all cases, it boils down to a `Proc` that you define which is invoked for every handled request. Your `Proc` code executes as if it were an instance method of an ApplicationController subclass which is handling a `before_action` callback in the normal Rails fashion, so it has full access to all the usual Rails objects such as `request` and `response`.
+
+Please take note of the _Security_ section later for additional information related to authorisation, as well as other security considerations.
+
+#### Token-based
+
+The `Proc` shown below must evaluate to `true` or `false`. The way you do that is up to you; in the examples below, code within the `Proc.new` block is just for illustration.
 
 ```ruby
 Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
   token_authenticator: Proc.new do | token, options |
 
-    # This is where you'd write the code to validate `token` - the means by
+    # This is where you'd write the code to validate `token`. The means by
     # which your application issues tokens to SCIM clients, or validates them,
-    # is outside the scope of the gem; the required mechanisms vary by client.
+    # is outside the scope of the gem. The required mechanisms vary by client.
     # More on this can be found in the 'Security' section later.
     #
     SomeLibraryModule.validate_access_token(token)
@@ -77,19 +95,65 @@ Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
 })
 ```
 
-When it comes to token access, Scimitar neither enforces nor presumes any kind of encoding for bearer tokens. You can use anything you like, including encoding/encrypting JWTs if you so wish - https://rubygems.org/gems/jwt may be useful. The way in which a client might integrate with your SCIM service varies by client and you will have to check documentation to see how a token gets conveyed to that client in the first place (e.g. a full OAuth flow with your application, or just a static token generated in some UI which an administrator copies and pastes into their client's SCIM configuration UI).
+Scimitar returns either a 401 error if your block evaluated to `false`, else consider the request authenticated and set HTTP header `WWW-Authenticate` to a value of **`Bearer`(( in the response per [RFC 7644](https://tools.ietf.org/html/rfc7644#section-2).
+
+Scimitar neither enforces nor presumes any kind of encoding for bearer tokens. You can use anything you like, including encoding/encrypting JWTs if you so wish - https://rubygems.org/gems/jwt may be useful. The way in which a client might integrate with your SCIM service varies by client and you will have to check documentation to see how a token gets conveyed to that client in the first place (e.g. a full OAuth flow with your application, or just a static token generated in some UI which an administrator copies and pastes into their client's SCIM configuration UI).
 
-**Strongly recommended:** You should wrap any Scimitar configuration with `Rails.application.config.to_prepare do...` so that any changes you make to configuration during local development are reflected via auto-reload, rather than requiring a server restart.
+#### Username and password-based
+
+For username/passwords, use something like this (again, the code inside the `Proc` is just an illustration):
 
 ```ruby
-Rails.application.config.to_prepare do
-  Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
-    # ...
+Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
+  basic_authenticator: Proc.new do | username, password |
+
+    User.find_by_username(username)&.valid_password?(password) || false
+
   end
-end
+})
 ```
 
-In general, Scimitar's own development and tests assume this approach. If you choose to put the configuration directly into an initializer file without the `to_prepare` wrapper, you will be at a _slightly_ higher risk of tripping over unrecognised Scimitar bugs; please make sure that your own application test coverage is reasonably comprehensive.
+Scimitar returns either a 401 error if your block evaluated to `false`, else consider the request authenticated and set HTTP header `WWW-Authenticate` to a value of **`Basic`** in the response per [RFC 7644](https://tools.ietf.org/html/rfc7644#section-2).
+
+#### Custom
+
+To fully take over authentication, you can supply a custom authenticator. If the authentication mechanism you're using does not already do so, **you become responsible for setting an appropriate value for the `WWW-Authenticate` header** in your response to indicate the appropriate authentication type. Scimitar won't do that itself, since it doesn't know what approach your custom code is using.
+
+Here's an example where Warden is being used for authentication, with Warden storing the authenticated information under a scope of `scim_v2` in this case, so the user could be later read back using `warden.user(:scim_v2)` (though you can use any Warden scope name you want, of course, or not use any authentication scope at all).
+
+```ruby
+Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
+  custome_authenticator: Proc.new do
+
+    # In this example we catch the Warden 'throw' for failed authentication, as
+    # well as allowing Warden to successfully find an *authenticated* user, but
+    # then fail *authorisation* based on some hypothetical permissions check.
+    #
+    catch(:warden) do
+      response.headers['WWW-Authenticate'] = '...something...'
+
+      warden = request.env["warden"]
+      user   = warden.authenticate!(scope: :scim_v2)
+      user.can_use_scim? # (just a hypothetical User model method that might check some permissions)
+    end or false
+
+  end
+})
+```
+
+If you _only_ wanted Warden authentication and not further authorisation, that block becomes even simpler:
+
+```ruby
+catch(:warden) do
+  response.headers['WWW-Authenticate'] = '...something...'
+
+  warden = request.env["warden"]
+  warden.authenticate!(scope: :scim_v2) # This'll either throw (caught -> block 'nil' -> "or false" -> false), else continue
+  true # If we reach this line, Warden didn't throw, so authentication was successful
+end or false
+```
+
+Scimitar handles `false` responses for you, rendering a `401` response, _but_ you can override that for even more customised behaviour if you want. Should your Proc have already responded, either by calling `handle_scim_error` and passing it an instance of an `Exception` - e.g. the `Scimitar::ErrorResponse` subclass of `Exception` initialised with `status: <HTTP status code>, detail: "error message"`) - or by any other means, then Scimitar won't render its standard 401 at all and your code becomes responsible for the returned JSON payload.
 
 ### Routes
 
@@ -118,6 +182,10 @@ Internally Scimitar always invokes URL helpers in the controller layer. I.e. any
 
 Note that Okta has some [curious documentation on its use of `POST` vs `PATCH` for Groups](https://developer.okta.com/docs/api/openapi/okta-scim/guides/scim-20/#update-a-specific-group-name), which per [this Scimitar issue](https://github.com/pond/scimitar/issues/153#issuecomment-2468897194) has caused at least one person some trouble. Defining the routes for both verbs as shown above (though in that issue's case, it was for the Group resource) _does_ still seem to work, but take care if integrating with Okta to try and at least manually test, if not auto-test, `PATCH`/`PUT` operations initiated from Okta's side, just to make sure.
 
+### Google Workspace note
+
+Using SCIM with Google Workspace might only work for a subset of applications. Since web UIs for major service providers change very often, it doesn't make sense to provide extensive documentation here as it would get out of date quickly; you may have to figure out the setup as best you can using whatever current Google documentation exists for their system. There are [some notes which were relevant around mid-2025](https://github.com/pond/scimitar/issues/142#issuecomment-2699050541) (from when a workarond/fix was incorporated into Scimitar to allow it to work with Google Workspace) which may help you get started.
+
 ### Data models
 
 Scimitar assumes that each SCIM resource maps to a single corresponding class in your system. This might be an abstraction over more complex underpinings, but either way, a 1:1 relationship is expected. For example, a SCIM User might map to a User ActiveRecord model in your Rails application, while a SCIM Group might map to some custom class called Team which operates on a more complex set of data "under the hood".

data/app/controllers/scimitar/application_controller.rb

@@ -130,7 +130,9 @@ module Scimitar
       end
 
       def authenticate
-        handle_scim_error(Scimitar::AuthenticationError.new) unless authenticated?
+        unless authenticated?
+          handle_scim_error(Scimitar::AuthenticationError.new) unless self.performed?
+        end
       end
 
       def authenticated?
@@ -146,6 +148,10 @@ module Scimitar
           end
         end
 
+        result ||= if Scimitar.engine_configuration.custom_authenticator.present?
+          instance_exec(&Scimitar.engine_configuration.custom_authenticator)
+        end
+
         return result
       end
 

data/app/models/scimitar/engine_configuration.rb

@@ -11,6 +11,7 @@ module Scimitar
       :uses_defaults,
       :basic_authenticator,
       :token_authenticator,
+      :custom_authenticator,
       :application_controller_mixin,
       :exception_reporter,
       :optional_value_fields_required,

data/app/models/scimitar/lists/query_parser.rb

@@ -76,6 +76,22 @@ module Scimitar
       NEXT_TOKEN  = /\A(#{PAREN}|#{STR}|#{OP}|#{WORD})#{SEP}/.freeze
       IS_OPERATOR = /\A(?:#{OP})\Z/.freeze
 
+      MONGO_SIMPLE_COMPARISON_OPERATORS = {
+        "eq" => "$eq", # equal
+        "ne" => "$ne", # not equal
+        "lt" => "$lt", # less than
+        "le" => "$lte", # less than or equal
+        "gt" => "$gt", # greater than
+        "ge" => "$gte" # greater than or equal
+      }.freeze
+
+      # Present, starts with, ends with, contains
+      MONGO_COMPLEX_COMPARISON_OPERATORS = %w[pr sw ew co].freeze
+      MONGO_COMBINATION_OPERATORS = {
+        "and" => "$and",
+        "or" => "$or"
+      }.freeze
+
       # Initialise an object.
       #
       # +attribute_map+:: See Scimitar::Resources::Mixin and documentation on
@@ -182,6 +198,33 @@ module Scimitar
         )
       end
 
+      # Having called #parse, call here to generate a Mongoid query
+      # For example, given this input:
+      #
+      #     userType eq "Employee" and (emails eq "a@b.com" or emails eq "a@b.org")
+      #
+      # this method will return a Mongoid query that looks like this:
+      #
+      #   {
+      #     "$and" => [
+      #       { :user_type => { "$eq" => 'Employee' } },
+      #       { "$or" => [
+      #         { :emails => { "$eq" => "a@b.com" } },
+      #         { :emails => { "$eq" => "a@b.org" } }
+      #       ]
+      #     ]
+      #  }
+      #
+      #  Use it with the Mongoid::Criteria#where method to filter results, e.g.:
+      #
+      #     User.where(parser.to_mongoid_query)
+      #
+      # Returns a Mongoid query that is the gem's
+      # best attempt at interpreting the SCIM filter string.
+      def to_mongoid_query
+        tree_node_to_mongoid_query(tree)
+      end
+
       # =======================================================================
       # PRIVATE INSTANCE METHODS
       # =======================================================================
@@ -658,6 +701,70 @@ module Scimitar
           return query
         end
 
+        # =====================================================================
+        # Mongoid query support
+        # =====================================================================
+
+        # Recursively processes an expression tree. Calls itself with nested tree
+        # fragments. Handles three cases:
+        # 1. Combination operators (and/or) - converted to { "operator" => [condition1, condition2]}
+        # 2. Simple comparison operators (eq, ne, lt, le, gt, ge) - converted to { column => { operator => value } }
+        # 3. Complex comparison operators (pr, sw, ew, co) - converted to { column => regex }
+        # or { column => { "$exists" => true, "$ne" => nil } }
+        def tree_node_to_mongoid_query(node)
+          op = node[0]
+
+          if MONGO_COMBINATION_OPERATORS.key?(op)
+            components = node.drop(1)
+            # Parser works in a way that max number of arguments is 2 here
+            # In case the request is A && B && C, it will be parsed as A && (B && C)
+            raise "Combination operators expect two arguments: #{node}" unless components.size == 2
+
+            {
+              MONGO_COMBINATION_OPERATORS[op] => [
+                tree_node_to_mongoid_query(components[0]),
+                tree_node_to_mongoid_query(components[1])
+              ]
+            }
+          elsif MONGO_SIMPLE_COMPARISON_OPERATORS.key?(op) || MONGO_COMPLEX_COMPARISON_OPERATORS.include?(op)
+            mongoid_comparison_operation(node)
+          else
+            raise "Unsupported operator: #{op}"
+          end
+        end
+
+        def mongoid_comparison_operation(node)
+          raise "No arrays allowed in comparison subnodes: #{node}" if node.any? { |subnode| subnode.is_a?(Array) }
+
+          column = attribute_map.dig(node[1], :column)
+          raise "Unsupported field: #{node[1]}" unless column
+
+          value = node[2]&.delete("\"")
+
+          if MONGO_SIMPLE_COMPARISON_OPERATORS.key?(node[0])
+            mongoid_simple_comparison_operation(MONGO_SIMPLE_COMPARISON_OPERATORS[node[0]], column, value)
+          elsif MONGO_COMPLEX_COMPARISON_OPERATORS.include?(node[0])
+            mongoid_complex_comparison_operation(node[0], column, value)
+          end
+        end
+
+        def mongoid_simple_comparison_operation(op, column, value)
+          { column => { op => value } }
+        end
+
+        def mongoid_complex_comparison_operation(op, column, value)
+          case op
+          when "pr"
+            { column => { "$exists" => true, "$ne" => nil } }
+          when "sw"
+            { column => /^#{Regexp.escape(value)}/ }
+          when "ew"
+            { column => /#{Regexp.escape(value)}$/ }
+          when "co"
+            { column => /#{Regexp.escape(value)}/ }
+          end
+        end
+
         # Apply a filter to a given base scope. Mandatory named parameters:
         #
         # +base_scope+::     Base scope (ActiveRecord::Relation, e.g. User.all)

data/app/models/scimitar/resources/mixin.rb

@@ -990,8 +990,12 @@ module Scimitar
             end
 
             found_data_for_recursion.each do | found_data |
+              extension_schema = self.class.scim_resource_type&.schemas&.detect { |schema| schema.id == path_component }
+
               attr_map = if path_component.to_sym == :root
                 with_attr_map
+              elsif extension_schema
+                with_attr_map.slice(*extension_schema.scim_attributes.map { |attr| attr.name.to_sym })
               else
                 with_attr_map[path_component.to_sym]
               end

data/config/initializers/scimitar.rb

@@ -86,6 +86,18 @@ Rails.application.config.to_prepare do # (required for >= Rails 7 / Zeitwerk)
     # Note that both basic and token authentication can be declared, with the
     # parameters in the inbound HTTP request determining which is invoked.
 
+    # If you want to support a custom authenticfation method:
+    #
+    #     custom_authenticator: Proc.new do
+    #       # Custom code here. don't forget to set a WWW-Authenticate header:
+    #       response.headers['WWW-Authenticate'] = '...something...'
+    #       # ...and evaluate to 'true' for success or 'false' for failure.
+    #     end
+    #
+    # If a basic and/or token authenticator has also been defined, then they're
+    # called first. The code will cascade through trying each and only call a
+    # custom authenticator if other mechanisms fail to authenticate.
+
     # Scimitar rescues certain error cases and exceptions, in order to return a
     # JSON response to the API caller. If you want exceptions to also be
     # reported to a third party system such as sentry.io or raygun.com, you can

data/lib/scimitar/version.rb

@@ -3,11 +3,11 @@ module Scimitar
   # Gem version. If this changes, be sure to re-run "bundle install" or
   # "bundle update".
   #
-  VERSION = '2.11.0'
+  VERSION = '2.12.0'
 
   # Date for VERSION. If this changes, be sure to re-run "bundle install"
   # or "bundle update".
   #
-  DATE = '2025-03-05'
+  DATE = '2025-08-15'
 
 end

data/spec/apps/dummy/config/initializers/warden.rb

@@ -0,0 +1,3 @@
+require 'warden'
+
+Rails.application.config.middleware.use Warden::Manager

data/spec/controllers/scimitar/application_controller_spec.rb

@@ -11,8 +11,6 @@ RSpec.describe Scimitar::ApplicationController do
     end
 
     controller do
-      rescue_from StandardError, with: :handle_resource_not_found
-
       def index
         render json: { 'message' => 'cool, cool!' }, format: :scim
       end
@@ -61,6 +59,7 @@ RSpec.describe Scimitar::ApplicationController do
     end
   end
 
+
   context 'token authentication' do
     before do
       Scimitar.engine_configuration = Scimitar::EngineConfiguration.new(
@@ -71,8 +70,6 @@ RSpec.describe Scimitar::ApplicationController do
     end
 
     controller do
-      rescue_from StandardError, with: :handle_resource_not_found
-
       def index
         render json: { 'message' => 'cool, cool!' }, format: :scim
       end
@@ -107,6 +104,134 @@ RSpec.describe Scimitar::ApplicationController do
     end
   end
 
+  context 'custom authentication, using Warden as an example' do
+    include Warden::Test::Helpers
+
+    controller do
+      def index
+        render json: { 'message' => 'cool, cool!' }, format: :scim
+      end
+    end
+
+    context 'with standard 401 handling' do
+      before do
+        Scimitar.engine_configuration = Scimitar::EngineConfiguration.new(
+          custom_authenticator: Proc.new do
+            catch(:warden) do
+              response.headers['WWW-Authenticate'] = 'SomeOtherValidScheme'
+
+              warden = request.env['warden']
+              warden.authenticate!(scope: :scim_v2)
+              true
+            end or false
+          end
+        )
+      end
+
+      context 'when authentication suceeds' do
+        it 'renders "success"' do
+          expect(warden).to receive(:authenticate!).and_return("A User instance or similar") # ('warden' is the proxy provided by the warden-rspec-rails gem)
+
+          get :index, params: { format: :scim }
+
+          expect(response).to be_ok
+          expect(JSON.parse(response.body)).to eql({ 'message' => 'cool, cool!' })
+          expect(response.headers['WWW-Authenticate']).to eql('SomeOtherValidScheme') # Proves the custom block ran
+        end
+      end
+
+      context 'when authentication fails' do # We're kinda just verifying the README.md example code here!
+        it 'renders 401' do
+          expect(warden).to receive(:authenticate!) { throw(:warden) } # ('warden' is the proxy provided by the warden-rspec-rails gem)
+
+          get :index, params: { format: :scim }
+
+          expect(response).to have_http_status(:unauthorized)
+          expect(response.headers['WWW-Authenticate']).to eql('SomeOtherValidScheme') # Proves the custom block ran
+
+          parsed_body = JSON.parse(response.body)
+
+          expect(parsed_body).to include('schemas' => ['urn:ietf:params:scim:api:messages:2.0:Error'])
+          expect(parsed_body).to include('detail' => 'Requires authentication')
+          expect(parsed_body).to include('status' => '401')
+        end
+      end
+    end
+
+    context 'with custom error handling' do
+      before do
+        Scimitar.engine_configuration = Scimitar::EngineConfiguration.new(
+          custom_authenticator: Proc.new do
+            render status: 499, json: { testing: true }
+            false
+          end
+        )
+      end
+
+      context 'when authentication fails' do
+        it 'renders the custom response' do
+          get :index, params: { format: :scim }
+
+          expect(response).to have_http_status(499)
+
+          parsed_body = JSON.parse(response.body)
+
+          expect(parsed_body).to eql('testing' => true)
+        end
+      end
+    end
+  end
+
+  context 'authentication cascade' do
+    before do
+      Scimitar.engine_configuration = Scimitar::EngineConfiguration.new(
+        basic_authenticator:  -> (username, password) { username == 'A' && password == 'B' },
+        token_authenticator:  -> (token,    options ) { token == 'A' },
+        custom_authenticator: ->                      { params[:let_me_in] == 'A' },
+      )
+    end
+
+    controller do
+      def index
+        render json: { 'message' => 'cool, cool!' }, format: :scim
+      end
+    end
+
+    it 'basic first' do
+      request.env['HTTP_AUTHORIZATION'] = ActionController::HttpAuthentication::Basic.encode_credentials('A', 'B')
+
+      get :index, params: { format: :scim }
+      expect(response).to be_ok
+
+      request.env['HTTP_AUTHORIZATION'] = ActionController::HttpAuthentication::Basic.encode_credentials('A', 'Wrong')
+
+      get :index, params: { format: :scim }
+      expect(response).to have_http_status(:unauthorized)
+    end
+
+    it 'token after basic' do
+      request.env['HTTP_AUTHORIZATION'] = 'Bearer A'
+
+      get :index, params: { format: :scim }
+      expect(response).to be_ok
+
+      request.env['HTTP_AUTHORIZATION'] = 'Bearer B'
+
+      get :index, params: { format: :scim }
+      expect(response).to have_http_status(:unauthorized)
+    end
+
+    it 'custom after basic and token' do
+      request.env['HTTP_AUTHORIZATION'] = 'Bearer Wrong'
+
+      get :index, params: { format: :scim, let_me_in: 'A' }
+      expect(response).to be_ok
+
+      get :index, params: { format: :scim, let_me_in: 'Wrong' }
+      expect(response).to have_http_status(:unauthorized)
+    end
+  end
+
   context 'authenticator evaluated within controller context' do
 
     # Define a controller with a custom instance method 'valid_token'.

data/spec/models/scimitar/lists/query_parser_spec.rb

@@ -698,6 +698,54 @@ RSpec.describe Scimitar::Lists::QueryParser do
     end # "context 'complex cases' do"
   end # "context '#to_activerecord_query' do"
 
+  context "#to_mongoid_query" do
+    context "when simple queries are used" do
+      it "generates expected Mongoid eq queries" do
+        @instance.parse('name.familyName eq "Doe"')
+        query = @instance.to_mongoid_query
+
+        expect(query).to eql(last_name: { "$eq" => "Doe" })
+      end
+
+      it "generates expected Mongoid ne queries" do
+        @instance.parse('name.familyName ne "Doe"')
+        query = @instance.to_mongoid_query
+
+        expect(query).to eql(last_name: { "$ne" => "Doe" })
+      end
+    end
+
+    context "when complex comparisons are used" do
+      it "generates expected Mongoid pr queries" do
+        @instance.parse('name.givenName pr')
+        query = @instance.to_mongoid_query
+
+        expect(query).to eql(first_name: { "$exists" => true, "$ne" => nil })
+      end
+
+      it "generates expected Mongoid co queries" do
+        @instance.parse('name.familyName co "Smith"')
+        query = @instance.to_mongoid_query
+
+        expect(query).to eql(last_name: /Smith/)
+      end
+    end
+
+    context "when combinations are user" do
+      it "generates expected Mongoid queries for AND and OR" do
+        @instance.parse('name.givenName eq "Jane" and (name.familyName co "Smith" or name.familyName eq "Doe")')
+        query = @instance.to_mongoid_query
+
+        expect(query).to eql(
+          "$and" => [
+            { first_name: { "$eq" => "Jane" }},
+            { "$or" => [{ last_name: /Smith/ }, { last_name: { "$eq" => "Doe" }}]}
+          ]
+        )
+      end
+    end
+  end
+
   # ===========================================================================
   # PRIVATE METHODS
   # ===========================================================================

data/spec/requests/active_record_backed_resources_controller_spec.rb

@@ -960,12 +960,12 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
         it_behaves_like 'it handles schema ID value keys without inline attributes', 'add'
         it_behaves_like 'it handles schema ID value keys without inline attributes', 'replace'
 
-        shared_examples 'it handles schema ID value keys with inline attributes' do
+        shared_examples 'it handles schema ID value keys with inline attributes' do | operation |
           it "and performs operation" do
             payload = {
               Operations: [
                 {
-                  op: 'add',
+                  op: operation,
                   value: {
                     'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization' => 'Foo Bar!',
                     'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department'   => 'Bar Foo!',
@@ -993,6 +993,110 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
 
         it_behaves_like 'it handles schema ID value keys with inline attributes', 'add'
         it_behaves_like 'it handles schema ID value keys with inline attributes', 'replace'
+
+        shared_examples 'it handles schema ID value keys of extension schema complex attributes via path' do | operation |
+          around :each do | example |
+            module ScimSchemaExtensions
+              module User
+                class EnterpisePositionSchema < Scimitar::Schema::Base
+                  def self.scim_attributes
+                    @scim_attributes ||= [
+                      Scimitar::Schema::Attribute.new(name: 'organization', type: 'string'),
+                      Scimitar::Schema::Attribute.new(name: 'department',   type: 'string'),
+                    ]
+                  end
+                end
+
+                class EnterpisePositionComplexType < Scimitar::ComplexTypes::Base
+                  set_schema EnterpisePositionSchema
+                end
+
+                class EnterpiseManager < Scimitar::Schema::Base
+                  def initialize(options = {})
+                    super(
+                      name:            'EnterpiseManager extension schema',
+                      description:     'EnterpiseManager extension for a Enterprise User',
+                      id:              self.class.id,
+                      scim_attributes: self.class.scim_attributes
+                    )
+                  end
+
+                  def self.id
+                    'urn:ietf:params:scim:schemas:extension:enterprise_manager:1.0:User'
+                  end
+
+                  def self.scim_attributes
+                    [
+                      Scimitar::Schema::Attribute.new(name: "position", complexType: EnterpisePositionComplexType),
+                    ]
+                  end
+                end
+              end
+            end
+
+            # change SCIM attributes map temporarily
+            class << MockUser
+              alias_method :original_scim_attributes_map, :scim_attributes_map
+
+              def scim_attributes_map
+                map = original_scim_attributes_map.merge(
+                  position: {
+                    organization: :organization,
+                    department:   :department,
+                  }
+                )
+                map.delete(:organization)
+                map.delete(:department)
+                map
+              end
+            end
+
+            # change extension schemas on User temporarily
+            @original_extended_schemas = Scimitar::Resources::User.extended_schemas
+            Scimitar::Resources::User.instance_variable_set(:@extended_schemas, [])
+            Scimitar::Resources::User.extend_schema ScimSchemaExtensions::User::EnterpiseManager
+
+            example.run()
+          ensure
+            # restore original setup
+            Scimitar::Resources::User.instance_variable_set(:@extended_schemas, @original_extended_schemas)
+
+            class << MockUser
+              alias_method :scim_attributes_map, :original_scim_attributes_map
+              remove_method :original_scim_attributes_map
+            end
+          end
+
+          it "and performs operation" do
+            payload = {
+              Operations: [
+                {
+                  op: operation,
+                  path: 'urn:ietf:params:scim:schemas:extension:enterprise_manager:1.0:User:position',
+                  value: {
+                    'organization' => 'Foo Bar!',
+                    'department'   => 'Bar Foo!'
+                  },
+                },
+              ]
+            }
+
+            @u2.update!(organization: 'Old org')
+            payload = spec_helper_hupcase(payload) if force_upper_case
+            patch "/Users/#{@u2.primary_key}", params: payload.merge(format: :scim)
+
+            expect(response.status                 ).to eql(200)
+            expect(response.headers['Content-Type']).to eql('application/scim+json; charset=utf-8')
+
+            @u2.reload
+
+            expect(@u2.organization).to eql('Foo Bar!')
+            expect(@u2.department  ).to eql('Bar Foo!')
+          end
+        end
+
+        it_behaves_like 'it handles schema ID value keys of extension schema complex attributes via path', 'add'
+        it_behaves_like 'it handles schema ID value keys of extension schema complex attributes via path', 'replace'
       end
 
       it 'which patches "returned: \'never\'" fields' do

data/spec/spec_helper.rb

@@ -20,6 +20,8 @@ abort("The Rails environment is running in production mode!") if Rails.env.produ
 
 require 'rspec/rails'
 require 'debug'
+require 'warden'
+require 'warden-rspec-rails'
 require 'scimitar'
 
 # ============================================================================
@@ -32,6 +34,8 @@ RSpec.configure do | config |
   config.filter_rails_from_backtrace!
   config.raise_errors_for_deprecations!
 
+  config.include(Warden::Test::ControllerHelpers, type: :controller) # (from the warden-rspec-rails gem)
+
   config.color                      = true
   config.tty                        = true
   config.order                      = :random

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scimitar
 version: !ruby/object:Gem::Version
-  version: 2.11.0
+  version: 2.12.0
 platform: ruby
 authors:
 - RIPA Global
 - Andrew David Hodgkinson
 bindir: bin
 cert_chain: []
-date: 2025-03-05 00:00:00.000000000 Z
+date: 2025-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: '1.11'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: '1.11'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: simplecov-rcov
   requirement: !ruby/object:Gem::Requirement
@@ -86,14 +86,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.12'
+        version: '6.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.12'
+        version: '6.14'
+- !ruby/object:Gem::Dependency
+  name: warden
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: warden-rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: doggo
   requirement: !ruby/object:Gem::Requirement
@@ -213,6 +241,7 @@ files:
 - spec/apps/dummy/config/initializers/cookies_serializer.rb
 - spec/apps/dummy/config/initializers/scimitar.rb
 - spec/apps/dummy/config/initializers/session_store.rb
+- spec/apps/dummy/config/initializers/warden.rb
 - spec/apps/dummy/config/routes.rb
 - spec/apps/dummy/db/migrate/20210304014602_create_mock_users.rb
 - spec/apps/dummy/db/migrate/20210308020313_create_mock_groups.rb
@@ -286,6 +315,7 @@ test_files:
 - spec/apps/dummy/config/initializers/cookies_serializer.rb
 - spec/apps/dummy/config/initializers/scimitar.rb
 - spec/apps/dummy/config/initializers/session_store.rb
+- spec/apps/dummy/config/initializers/warden.rb
 - spec/apps/dummy/config/routes.rb
 - spec/apps/dummy/db/migrate/20210304014602_create_mock_users.rb
 - spec/apps/dummy/db/migrate/20210308020313_create_mock_groups.rb