scimitar 2.6.0 → 2.7.0

data/app/controllers/scimitar/active_record_backed_resources_controller.rb

@@ -60,12 +60,20 @@ module Scimitar
 
     # POST (create)
     #
-    def create
+    # Calls #save! on the new record if no block is given, else invokes the
+    # block, passing it the new ActiveRecord model instance to be saved. It
+    # is up to the block to make any further changes and persist the record.
+    #
+    # Blocks are invoked from within a wrapping database transaction.
+    # ActiveRecord::RecordInvalid exceptions are handled for you, rendering
+    # an appropriate SCIM error.
+    #
+    def create(&block)
       super do |scim_resource|
         self.storage_class().transaction do
           record = self.storage_class().new
           record.from_scim!(scim_hash: scim_resource.as_json())
-          self.save!(record)
+          self.save!(record, &block)
           record_to_scim(record)
         end
       end
@@ -73,12 +81,16 @@ module Scimitar
 
     # PUT (replace)
     #
-    def replace
+    # Calls #save! on the updated record if no block is given, else invokes the
+    # block, passing the updated record which the block must persist, with the
+    # same rules as for #create.
+    #
+    def replace(&block)
       super do |record_id, scim_resource|
         self.storage_class().transaction do
           record = self.find_record(record_id)
           record.from_scim!(scim_hash: scim_resource.as_json())
-          self.save!(record)
+          self.save!(record, &block)
           record_to_scim(record)
         end
       end
@@ -86,12 +98,16 @@ module Scimitar
 
     # PATCH (update)
     #
-    def update
+    # Calls #save! on the updated record if no block is given, else invokes the
+    # block, passing the updated record which the block must persist, with the
+    # same rules as for #create.
+    #
+    def update(&block)
       super do |record_id, patch_hash|
         self.storage_class().transaction do
           record = self.find_record(record_id)
           record.from_scim_patch!(patch_hash: patch_hash)
-          self.save!(record)
+          self.save!(record, &block)
           record_to_scim(record)
         end
       end
@@ -134,6 +150,17 @@ module Scimitar
         raise NotImplementedError
       end
 
+      # Return an Array of exceptions that #save! can rescue and handle with a
+      # SCIM error automatically.
+      #
+      def scimitar_rescuable_exceptions
+        [
+          ActiveRecord::RecordInvalid,
+          ActiveRecord::RecordNotSaved,
+          ActiveRecord::RecordNotUnique,
+        ]
+      end
+
       # Find a record by ID. Subclasses can override this if they need special
       # lookup behaviour.
       #
@@ -158,8 +185,8 @@ module Scimitar
       # If you just let this superclass handle things, it'll call the standard
       # +#save!+ method on the record. If you pass a block, then this block is
       # invoked and passed the ActiveRecord model instance to be saved. You can
-      # then do things like calling a different method, using a service object of
-      # some kind, perform audit-related operations and so-on.
+      # then do things like calling a different method, using a service object
+      # of some kind, perform audit-related operations and so-on.
       #
       # The return value is not used internally, making life easier for
       # overriding subclasses to "do the right thing" / avoid mistakes (instead
@@ -173,16 +200,25 @@ module Scimitar
         else
           record.save!
         end
-      rescue ActiveRecord::RecordInvalid => exception
-        handle_invalid_record(exception.record)
+      rescue *self.scimitar_rescuable_exceptions() => exception
+        handle_on_save_exception(record, exception)
       end
 
-      # Deal with validation errors by responding with an appropriate SCIM error.
+      # Deal with exceptions related to errors upon saving, by responding with
+      # an appropriate SCIM error. This is most effective if the record has
+      # validation errors defined, but falls back to the provided exception's
+      # message otherwise.
       #
-      # +record+:: The record with validation errors.
+      # +record+::    The record that provoked the exception. Mandatory.
+      # +exception+:: The exception that was raised. If omitted, a default of
+      #               'Unknown', in English with no I18n, is used.
       #
-      def handle_invalid_record(record)
-        joined_errors = record.errors.full_messages.join('; ')
+      def handle_on_save_exception(record, exception = RuntimeError.new('Unknown'))
+        details = if record.errors.present?
+          record.errors.full_messages.join('; ')
+        else
+          exception.message
+        end
 
         # https://tools.ietf.org/html/rfc7644#page-12
         #
@@ -192,14 +228,14 @@ module Scimitar
         #   status code 409 (Conflict) with a "scimType" error code of
         #   "uniqueness"
         #
-        if record.errors.any? { | e | e.type == :taken }
+        if exception.is_a?(ActiveRecord::RecordNotUnique) || record.errors.any? { | e | e.type == :taken }
           raise Scimitar::ErrorResponse.new(
             status:   409,
             scimType: 'uniqueness',
-            detail:   joined_errors
+            detail:   "Operation failed due to a uniqueness constraint: #{details}"
           )
         else
-          raise Scimitar::ResourceInvalidError.new(joined_errors)
+          raise Scimitar::ResourceInvalidError.new(details)
         end
       end
 

data/app/controllers/scimitar/application_controller.rb

@@ -124,8 +124,13 @@ module Scimitar
         #
         # https://stackoverflow.com/questions/10239970/what-is-the-delimiter-for-www-authenticate-for-multiple-schemes
         #
-        response.set_header('WWW_AUTHENTICATE', 'Basic' ) if Scimitar.engine_configuration.basic_authenticator.present?
-        response.set_header('WWW_AUTHENTICATE', 'Bearer') if Scimitar.engine_configuration.token_authenticator.present?
+        response.set_header('WWW-Authenticate', 'Basic' ) if Scimitar.engine_configuration.basic_authenticator.present?
+        response.set_header('WWW-Authenticate', 'Bearer') if Scimitar.engine_configuration.token_authenticator.present?
+
+        # No matter what a caller might request via headers, the only content
+        # type we can ever respond with is JSON-for-SCIM.
+        #
+        response.set_header('Content-Type', "#{Mime::Type.lookup_by_extension(:scim)}; charset=utf-8")
       end
 
       def authenticate
@@ -134,11 +139,15 @@ module Scimitar
 
       def authenticated?
         result = if Scimitar.engine_configuration.basic_authenticator.present?
-          authenticate_with_http_basic(&Scimitar.engine_configuration.basic_authenticator)
+          authenticate_with_http_basic do |username, password|
+            instance_exec(username, password, &Scimitar.engine_configuration.basic_authenticator)
+          end
         end
 
         result ||= if Scimitar.engine_configuration.token_authenticator.present?
-          authenticate_with_http_token(&Scimitar.engine_configuration.token_authenticator)
+          authenticate_with_http_token do |token, options|
+            instance_exec(token, options, &Scimitar.engine_configuration.token_authenticator)
+          end
         end
 
         return result

data/app/models/scimitar/complex_types/address.rb

@@ -7,12 +7,6 @@ module Scimitar
     #
     class Address < Base
       set_schema Scimitar::Schema::Address
-
-      # Returns the JSON representation of an Address.
-      #
-      def as_json(options = {})
-        {'type' => 'work'}.merge(super(options))
-      end
     end
   end
 end

data/app/models/scimitar/resource_invalid_error.rb

@@ -2,7 +2,7 @@ module Scimitar
   class ResourceInvalidError < ErrorResponse
 
     def initialize(error_message)
-      super(status: 400, scimType: 'invalidValue', detail:"Operation failed since record has become invalid: #{error_message}")
+      super(status: 400, scimType: 'invalidValue', detail: "Operation failed since record has become invalid: #{error_message}")
     end
 
   end

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

@@ -952,7 +952,10 @@ module Scimitar
 
                 when 'replace'
                   if path_component == 'root'
-                    altering_hash[path_component].merge!(value)
+                    dot_pathed_value = value.inject({}) do |hash, (k, v)|
+                      hash.deep_merge!(::Scimitar::Support::Utilities.dot_path(k.split('.'), v))
+                    end
+                    altering_hash[path_component].deep_merge!(dot_pathed_value)
                   else
                     altering_hash[path_component] = value
                   end

data/app/models/scimitar/schema/attribute.rb

@@ -105,9 +105,9 @@ module Scimitar
 
       def simple_type?(value)
         (type == 'string' && value.is_a?(String)) ||
-          (type == 'boolean' && (value.is_a?(TrueClass) || value.is_a?(FalseClass))) ||
-          (type == 'integer' && (value.is_a?(Integer))) ||
-          (type == 'dateTime' && valid_date_time?(value))
+        (type == 'boolean' && (value.is_a?(TrueClass) || value.is_a?(FalseClass))) ||
+        (type == 'integer' && (value.is_a?(Integer))) ||
+        (type == 'dateTime' && valid_date_time?(value))
       end
 
       def valid_date_time?(value)

data/config/initializers/scimitar.rb

@@ -37,11 +37,11 @@ Rails.application.config.to_prepare do # (required for >= Rails 7 / Zeitwerk)
   #
   Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
 
-    # If you have filters you want to run for any Scimitar action/route, you can
-    # define them here. You can also override any shared controller methods
+    # If you have filters you want to run for any Scimitar action/route, you
+    # can define them here. You can also override any shared controller methods
     # here. For example, you might use a before-action to set up some
     # multi-tenancy related state, skip Rails CSRF token verification, or
-    # customize how Scimitar generates URLs:
+    # customise how Scimitar generates URLs:
     #
     #     application_controller_mixin: Module.new do
     #       def self.included(base)

data/lib/scimitar/support/utilities.rb

@@ -0,0 +1,51 @@
+module Scimitar
+
+  # Namespace containing various chunks of Scimitar support code that don't
+  # logically fit into other areas.
+  #
+  module Support
+
+    # A namespace that contains various stand-alone utility methods which act
+    # as helpers for other parts of the code base, without risking namespace
+    # pollution by e.g. being part of a module loaded into a client class.
+    #
+    module Utilities
+
+      # Takes an array of components that usually come from a dotted path such
+      # as <tt>foo.bar.baz</tt>, along with a value that is found at the end of
+      # that path, then converts it into a nested Hash with each level of the
+      # Hash corresponding to a step along the path.
+      #
+      # This was written to help with edge case SCIM uses where (most often, at
+      # least) inbound calls use a dotted notation where nested values are more
+      # commonly accepted; converting to nesting makes it easier for subsequent
+      # processing code, which needs only handle nested Hash data.
+      #
+      # As an example, passing:
+      #
+      #     ['foo', 'bar', 'baz'], 'value'
+      #
+      # ...yields:
+      #
+      #     {'foo' => {'bar' => {'baz' => 'value'}}}
+      #
+      # Parameters:
+      #
+      # +array+:: Array containing path components, usually acquired from a
+      #           string with dot separators and a call to String#split.
+      #
+      # +value+:: The value found at the path indicated by +array+.
+      #
+      # If +array+ is empty, +value+ is returned directly, with no nesting
+      # Hash wrapping it.
+      #
+      def self.dot_path(array, value)
+        return value if array.empty?
+
+        {}.tap do | hash |
+          hash[array.shift()] = self.dot_path(array, value)
+        end
+      end
+    end
+  end
+end

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.6.0'
+  VERSION = '2.7.0'
 
   # Date for VERSION. If this changes, be sure to re-run "bundle install"
   # or "bundle update".
   #
-  DATE = '2023-11-14'
+  DATE = '2024-01-15'
 
 end

data/lib/scimitar.rb

@@ -1,5 +1,6 @@
 require 'scimitar/version'
 require 'scimitar/support/hash_with_indifferent_case_insensitive_access'
+require 'scimitar/support/utilities'
 require 'scimitar/engine'
 
 module Scimitar

data/spec/apps/dummy/app/controllers/custom_create_mock_users_controller.rb

@@ -0,0 +1,25 @@
+# For tests only - uses custom 'create' implementation which passes a block to
+# Scimitar::ActiveRecordBackedResourcesController#create.
+#
+class CustomCreateMockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  OVERRIDDEN_NAME = SecureRandom.uuid
+
+  def create
+    super do | resource |
+      resource.first_name = OVERRIDDEN_NAME
+      resource.save!
+    end
+  end
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/app/controllers/custom_replace_mock_users_controller.rb

@@ -0,0 +1,25 @@
+# For tests only - uses custom 'replace' implementation which passes a block to
+# Scimitar::ActiveRecordBackedResourcesController#create.
+#
+class CustomReplaceMockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  OVERRIDDEN_NAME = SecureRandom.uuid
+
+  def replace
+    super do | resource |
+      resource.first_name = OVERRIDDEN_NAME
+      resource.save!
+    end
+  end
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/app/controllers/custom_update_mock_users_controller.rb

@@ -0,0 +1,25 @@
+# For tests only - uses custom 'update' implementation which passes a block to
+# Scimitar::ActiveRecordBackedResourcesController#create.
+#
+class CustomUpdateMockUsersController < Scimitar::ActiveRecordBackedResourcesController
+
+  OVERRIDDEN_NAME = SecureRandom.uuid
+
+  def update
+    super do | resource |
+      resource.first_name = OVERRIDDEN_NAME
+      resource.save!
+    end
+  end
+
+  protected
+
+    def storage_class
+      MockUser
+    end
+
+    def storage_scope
+      MockUser.all
+    end
+
+end

data/spec/apps/dummy/config/routes.rb

@@ -17,14 +17,26 @@ Rails.application.routes.draw do
   get    'Groups/:id', to: 'mock_groups#show'
   patch  'Groups/:id', to: 'mock_groups#update'
 
-  # For testing blocks passed to ActiveRecordBackedResourcesController#destroy
+  # For testing blocks passed to ActiveRecordBackedResourcesController#create,
+  # #update, #replace and #destroy.
   #
+  post   'CustomCreateUsers',      to: 'custom_create_mock_users#create'
+  patch  'CustomUpdateUsers/:id',  to: 'custom_update_mock_users#update'
+  put    'CustomReplaceUsers/:id', to: 'custom_replace_mock_users#replace'
   delete 'CustomDestroyUsers/:id', to: 'custom_destroy_mock_users#destroy'
 
+  # Needed because the auto-render of most of the above includes a 'url_for'
+  # call for a 'show' action, so we must include routes (implemented in the
+  # base class) for the "show" endpoint.
+  #
+  get  'CustomCreateUsers/:id',  to: 'custom_create_mock_users#show'
+  get  'CustomUpdateUsers/:id',  to: 'custom_update_mock_users#show'
+  get  'CustomReplaceUsers/:id', to: 'custom_replace_mock_users#show'
+
   # For testing blocks passed to ActiveRecordBackedResourcesController#save!
   #
-  post 'CustomSaveUsers', to: 'custom_save_mock_users#create'
-  get 'CustomSaveUsers/:id', to: 'custom_save_mock_users#show'
+  post 'CustomSaveUsers',     to: 'custom_save_mock_users#create'
+  get  'CustomSaveUsers/:id', to: 'custom_save_mock_users#show'
 
   # For testing environment inside Scimitar::ApplicationController subclasses.
   #

data/spec/controllers/scimitar/application_controller_spec.rb

@@ -24,7 +24,7 @@ RSpec.describe Scimitar::ApplicationController do
       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('Basic')
+      expect(response.headers['WWW-Authenticate']).to eql('Basic')
     end
 
     it 'renders failure with bad password' do
@@ -84,7 +84,61 @@ RSpec.describe Scimitar::ApplicationController do
       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('Bearer')
+      expect(response.headers['WWW-Authenticate']).to eql('Bearer')
+    end
+
+    it 'renders failure with bad token' do
+      request.env['HTTP_AUTHORIZATION'] = 'Bearer Invalid'
+
+      get :index, params: { format: :scim }
+      expect(response).not_to be_ok
+    end
+
+    it 'renders failure with blank token' do
+      request.env['HTTP_AUTHORIZATION'] = 'Bearer'
+
+      get :index, params: { format: :scim }
+      expect(response).not_to be_ok
+    end
+
+    it 'renders failure with missing header' do
+      get :index, params: { format: :scim }
+      expect(response).not_to be_ok
+    end
+  end
+
+  context 'authenticator evaluated within controller context' do
+
+    # Define a controller with a custom instance method 'valid_token'.
+    #
+    controller do
+      def index
+        render json: { 'message' => 'cool, cool!' }, format: :scim
+      end
+
+      def valid_token
+        'B'
+      end
+    end
+
+    # Call the above controller method from the token authenticator Proc,
+    # proving that it was executed in the controller's context.
+    #
+    before do
+      Scimitar.engine_configuration = Scimitar::EngineConfiguration.new(
+        token_authenticator: Proc.new do | token, options |
+          token == self.valid_token()
+        end
+      )
+    end
+
+    it 'renders success when valid creds are given' do
+      request.env['HTTP_AUTHORIZATION'] = 'Bearer B'
+
+      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('Bearer')
     end
 
     it 'renders failure with bad token' do

data/spec/controllers/scimitar/schemas_controller_spec.rb

@@ -27,7 +27,7 @@ RSpec.describe Scimitar::SchemasController do
       expect(parsed_body['name']).to eql('User')
     end
 
-    it 'includes the controller customized schema location' do
+    it 'includes the controller customised schema location' do
       get :index, params: { name: Scimitar::Schema::User.id, format: :scim }
       expect(response).to be_ok
       parsed_body = JSON.parse(response.body)

data/spec/models/scimitar/complex_types/address_spec.rb

@@ -2,8 +2,8 @@ require 'spec_helper'
 
 RSpec.describe Scimitar::ComplexTypes::Address do
   context '#as_json' do
-    it 'assumes a type of "work" as a default' do
-      expect(described_class.new.as_json).to eq('type' => 'work')
+    it 'assumes no defaults' do
+      expect(described_class.new.as_json).to eq({})
     end
 
     it 'allows a custom address type' do
@@ -11,9 +11,8 @@ RSpec.describe Scimitar::ComplexTypes::Address do
     end
 
     it 'shows the set address' do
-      expect(described_class.new(country: 'NZ').as_json).to eq('type' => 'work', 'country' => 'NZ')
+      expect(described_class.new(country: 'NZ').as_json).to eq('country' => 'NZ')
     end
   end
 
 end
-

data/spec/models/scimitar/resources/mixin_spec.rb

@@ -2717,6 +2717,28 @@ RSpec.describe Scimitar::Resources::Mixin do
             expect(@instance.username).to eql('1234')
           end
 
+          it 'which updates nested values using root syntax' do
+            @instance.update!(first_name: 'Foo', last_name: 'Bar')
+
+            path = 'name.givenName'
+            path = path.upcase if force_upper_case
+
+            patch = {
+              'schemas'    => ['urn:ietf:params:scim:api:messages:2.0:PatchOp'],
+              'Operations' => [
+                {
+                  'op'    => 'replace',
+                  'value' => {
+                    path => 'Baz'
+                  }
+                }
+              ]
+            }
+
+            @instance.from_scim_patch!(patch_hash: patch)
+            expect(@instance.first_name).to eql('Baz')
+          end
+
           it 'which updates nested values' do
             @instance.update!(first_name: 'Foo', last_name: 'Bar')