scimitar 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 834a7c3f5dba88856dfea8fdfcc1807f49b36739d1c5886e0dc96e7ca5621642
-  data.tar.gz: 7aaa9fae826b8142c3c3418b825ca86c7de46bb543dcdfb19b042caea15f988e
+  metadata.gz: 742d9f1195cc1ec3c86c17e2ca731119413925f3b5e0a3bd67fc90bf7183c2dd
+  data.tar.gz: c4e90cbd8d59eb564deebfd0278e96f2f1896b9fa6c0eb8697f1975115e2cf47
 SHA512:
-  metadata.gz: c3db5de7ca04d57be95f3638183936ab1cd4621b3aba22e0bcd6eaa3b2e876dfe2e79f86711da6de1106908ae96fd444c060b6bc10055e0b8f476faff6e18ca0
-  data.tar.gz: 701c4cb7d93f9dcfa89906bcfb222ba734d4ed83f0f2404969d8375df2a963c2376629508733d7e2852250d8652dac8e9ec07a6482f3a382fa64aaf2ac4ef9e0
+  metadata.gz: b1df7b83b8adaf904891983a1059a690ed7435917c8ae409a81254a2b13314e35ce45d630aecc917165c527314cd140913ce4d31494da4a8ca54c65f8b7f6d6f
+  data.tar.gz: 2855fcbe539ae73ff31fbae32a7e4841a31be1c48c39eae94ae34b9ab96341fdb17e53ee82d42c318a5bf928143d39181461a9bbb86d435ecb37e4fdda6876da

data/app/controllers/scimitar/active_record_backed_resources_controller.rb

@@ -131,8 +131,8 @@ module Scimitar
         raise NotImplementedError
       end
 
-      # Find a RIP user record. Subclasses can override this if they need
-      # special lookup behaviour.
+      # Find a record by ID. Subclasses can override this if they need special
+      # lookup behaviour.
       #
       # +record_id+:: Record ID (SCIM schema 'id' value - "our" ID).
       #

data/app/controllers/scimitar/application_controller.rb

@@ -25,10 +25,12 @@ module Scimitar
       #
       # ...to "globally" invoke this handler if you wish.
       #
-      # +_exception+:: Exception instance (currently unused).
       #
-      def handle_resource_not_found(_exception)
-        handle_scim_error(NotFoundError.new(params[:id]))
+      # +exception+:: Exception instance, used for a configured error reporter
+      #               via #handle_scim_error (if present).
+      #
+      def handle_resource_not_found(exception)
+        handle_scim_error(NotFoundError.new(params[:id]), exception)
       end
 
       # This base controller uses:
@@ -38,9 +40,22 @@ module Scimitar
       # ...to "globally" invoke this handler for all Scimitar errors (including
       # subclasses).
       #
+      # Mandatory parameters are:
+      #
       # +error_response+:: Scimitar::ErrorResponse (or subclass) instance.
       #
-      def handle_scim_error(error_response)
+      # Optional parameters are:
+      #
+      # *exception+:: If a Ruby exception was the reason this method is being
+      #               called, pass it here. Any configured exception reporting
+      #               mechanism will be invokved with the given parameter.
+      #               Otherwise, the +error_response+ value is reported.
+      #
+      def handle_scim_error(error_response, exception = error_response)
+        unless Scimitar.engine_configuration.exception_reporter.nil?
+          Scimitar.engine_configuration.exception_reporter.call(exception)
+        end
+
         render json: error_response, status: error_response.status
       end
 
@@ -55,7 +70,7 @@ module Scimitar
       # +exception+:: Exception instance.
       #
       def handle_bad_json_error(exception)
-        handle_scim_error(ErrorResponse.new(status: 400, detail: "Invalid JSON - #{exception.message}"))
+        handle_scim_error(ErrorResponse.new(status: 400, detail: "Invalid JSON - #{exception.message}"), exception)
       end
 
       # This base controller uses:
@@ -68,7 +83,7 @@ module Scimitar
       #
       def handle_unexpected_error(exception)
         Rails.logger.error("#{exception.message}\n#{exception.backtrace}")
-        handle_scim_error(ErrorResponse.new(status: 500, detail: exception.message))
+        handle_scim_error(ErrorResponse.new(status: 500, detail: exception.message), exception)
       end
 
     # =========================================================================
@@ -82,12 +97,17 @@ module Scimitar
       # request and subclass processing.
       #
       def require_scim
-        if request.content_type&.downcase == Mime::Type.lookup_by_extension(:scim).to_s
+        scim_mime_type = Mime::Type.lookup_by_extension(:scim).to_s
+
+        if request.content_type.nil?
+          request.format = :scim
+          request.headers['CONTENT_TYPE'] = scim_mime_type
+        elsif request.content_type&.downcase == scim_mime_type
           request.format = :scim
         elsif request.format == :scim
-          request.headers['CONTENT_TYPE'] = Mime::Type.lookup_by_extension(:scim).to_s
+          request.headers['CONTENT_TYPE'] = scim_mime_type
         else
-          handle_scim_error(ErrorResponse.new(status: 406, detail: "Only #{Mime::Type.lookup_by_extension(:scim)} type is accepted."))
+          handle_scim_error(ErrorResponse.new(status: 406, detail: "Only #{scim_mime_type} type is accepted."))
         end
       end
 

data/app/models/scimitar/engine_configuration.rb

@@ -9,13 +9,17 @@ module Scimitar
 
     attr_accessor :basic_authenticator,
                   :token_authenticator,
-                  :application_controller_mixin
+                  :application_controller_mixin,
+                  :exception_reporter,
+                  :optional_value_fields_required
 
     def initialize(attributes = {})
 
-      # No defaults yet - reserved for future use.
+      # Set defaults that may be overridden by the initializer.
       #
-      defaults = {}
+      defaults = {
+        optional_value_fields_required: true
+      }
 
       super(defaults.merge(attributes))
     end

data/app/models/scimitar/error_response.rb

@@ -16,5 +16,17 @@ module Scimitar
       data['scimType'] = scimType if scimType
       data
     end
+
+    # Originally Scimitar used attribute "detail" for exception text; it was
+    # only for JSON responses at the time, but in hindsight was a bad choice.
+    # It should have been "message" given inheritance from StandardError, which
+    # then works properly with e.g. error reporting services.
+    #
+    # The "detail" attribute is still present, for backwards compatibility with
+    # any client code that might be using this class.
+    #
+    def message
+      self.detail
+    end
   end
 end

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

@@ -633,7 +633,7 @@ module Scimitar
               when 'pr'
                 arel_table.grouping(arel_column.not_eq_all(['', nil]))
               else
-                raise Scimitar::FilterError
+                raise Scimitar::FilterError.new("Unsupported operator: '#{scim_operator}'")
             end
 
             if index == 0
@@ -656,10 +656,10 @@ module Scimitar
         # +scim_attribute+:: SCIM attribute from a filter string.
         #
         def activerecord_columns(scim_attribute)
-          raise Scimitar::FilterError if scim_attribute.blank?
+          raise Scimitar::FilterError.new("No scim_attribute provided") if scim_attribute.blank?
 
           mapped_attribute = self.attribute_map()[scim_attribute]
-          raise Scimitar::FilterError if mapped_attribute.blank?
+          raise Scimitar::FilterError.new("Unable to find domain attribute from SCIM attribute: '#{scim_attribute}'") if mapped_attribute.blank?
 
           if mapped_attribute[:ignore]
             return []

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

@@ -138,7 +138,7 @@ module Scimitar
       end
 
       def as_json(options = {})
-        self.meta = Meta.new unless self.meta
+        self.meta = Meta.new unless self.meta && self.meta.is_a?(Meta)
         meta.resourceType = self.class.resource_type_id
         original_hash = super(options).except('errors')
         original_hash.merge!('schemas' => self.class.schemas.map(&:id))

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

@@ -10,6 +10,7 @@ module Scimitar
       def self.scim_attributes
         @scim_attributes ||= [
           Attribute.new(name: 'type',          type: 'string'),
+          Attribute.new(name: 'primary',       type: 'boolean'),
           Attribute.new(name: 'formatted',     type: 'string'),
           Attribute.new(name: 'streetAddress', type: 'string'),
           Attribute.new(name: 'locality',      type: 'string'),

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

@@ -7,7 +7,7 @@ module Scimitar
     class Vdtp < Base
       def self.scim_attributes
         @scim_attributes ||= [
-          Attribute.new(name: 'value',   type: 'string', required: true),
+          Attribute.new(name: 'value',   type: 'string', required: Scimitar.engine_configuration.optional_value_fields_required),
           Attribute.new(name: 'display', type: 'string', mutability: 'readOnly'),
           Attribute.new(name: 'type',    type: 'string'),
           Attribute.new(name: 'primary', type: 'boolean'),

data/config/initializers/scimitar.rb

@@ -79,4 +79,24 @@ Scimitar.engine_configuration = Scimitar::EngineConfiguration.new({
   # Note that both basic and token authentication can be declared, with the
   # parameters in the inbound HTTP request determining which is invoked.
 
+  # 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
+  # configure a Proc to do so. It is passed a Ruby exception subclass object.
+  # For example, a minimal sentry.io reporter might do this:
+  #
+  #     exception_reporter: Proc.new do | exception |
+  #       Sentry.capture_exception(exception)
+  #     end
+  #
+  # You will still need to configure your reporting system according to its
+  # documentation (e.g. via a Rails "config/initializers/<foo>.rb" file).
+
+  # Scimilar treats "VDTP" (Value, Display, Type, Primary) attribute values,
+  # used for e.g. e-mail addresses or phone numbers, as required by default.
+  # If you encounter a service which calls these with e.g. "null" value data,
+  # you can configure all values to be optional. You'll need to deal with
+  # whatever that means for you receiving system in your model code.
+  #
+  #     optional_value_fields_required: false
 })

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 = '1.1.0'
+  VERSION = '1.3.0'
 
   # Date for VERSION. If this changes, be sure to re-run "bundle install"
   # or "bundle update".
   #
-  DATE = '2021-09-15'
+  DATE = '2022-07-14'
 
 end

data/spec/controllers/scimitar/application_controller_spec.rb

@@ -169,5 +169,74 @@ RSpec.describe Scimitar::ApplicationController do
       expect(parsed_body).to include('status' => '500')
       expect(parsed_body).to include('detail' => 'Bang')
     end
-  end
+
+    context 'with an exception reporter' do
+      around :each do | example |
+        original_configuration = Scimitar.engine_configuration.exception_reporter
+        Scimitar.engine_configuration.exception_reporter = Proc.new do | exception |
+          @exception = exception
+        end
+        example.run()
+      ensure
+        Scimitar.engine_configuration.exception_reporter = original_configuration
+      end
+
+      context 'and "internal server error"' do
+        it 'is invoked' do
+          get :index, params: { format: :scim }
+
+          expect(@exception).to be_a(RuntimeError)
+          expect(@exception.message).to eql('Bang')
+        end
+      end
+
+      context 'and "not found"' do
+        controller do
+          def index
+            handle_resource_not_found(ActiveRecord::RecordNotFound.new(42))
+          end
+        end
+
+        it 'is invoked' do
+          get :index, params: { format: :scim }
+
+          expect(@exception).to be_a(ActiveRecord::RecordNotFound)
+          expect(@exception.message).to eql('42')
+        end
+      end
+
+      context 'and bad JSON' do
+        controller do
+          def index
+            begin
+              raise 'Hello'
+            rescue
+              raise ActionDispatch::Http::Parameters::ParseError
+            end
+          end
+        end
+
+        it 'is invoked' do
+          get :index, params: { format: :scim }
+
+          expect(@exception).to be_a(ActionDispatch::Http::Parameters::ParseError)
+          expect(@exception.message).to eql('Hello')
+        end
+      end
+
+      context 'and a bad content type' do
+        controller do
+          def index; end
+        end
+
+        it 'is invoked' do
+          request.headers['Content-Type'] = 'text/plain'
+          get :index
+
+          expect(@exception).to be_a(Scimitar::ErrorResponse)
+          expect(@exception.message).to eql('Only application/scim+json type is accepted.')
+        end
+      end
+    end # "context 'exception reporter' do"
+  end # "context 'error handling' do"
 end

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

@@ -18,6 +18,4 @@ RSpec.describe Scimitar::ComplexTypes::Email do
       expect(described_class.new(value: 'a@b.c').as_json).to eq('value' => 'a@b.c')
     end
   end
-
 end
-

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

@@ -1,7 +1,6 @@
 require 'spec_helper'
 
 RSpec.describe Scimitar::Resources::Base do
-
   context '#valid?' do
     MyCustomSchema = Class.new(Scimitar::Schema::Base) do
       def self.id
@@ -21,6 +20,9 @@ RSpec.describe Scimitar::Resources::Base do
           ),
           Scimitar::Schema::Attribute.new(
             name: 'complexNames', complexType: Scimitar::ComplexTypes::Name, multiValued:true, required: false
+          ),
+          Scimitar::Schema::Attribute.new(
+            name: 'vdtpTestByEmail', complexType: Scimitar::ComplexTypes::Email, required: false
           )
         ]
       end
@@ -57,5 +59,28 @@ RSpec.describe Scimitar::Resources::Base do
       expect(resource.valid?).to be(false)
       expect(resource.errors.full_messages).to match_array(["Complexnames has to follow the complexType format.", "Complexnames familyname has the wrong type. It has to be a(n) string."])
     end
-  end
+
+    context 'configuration of required values in VDTP schema' do
+      around :each do | example |
+        original_configuration = Scimitar.engine_configuration.optional_value_fields_required
+        Scimitar::Schema::Email.instance_variable_set('@scim_attributes', nil)
+        example.run()
+      ensure
+        Scimitar.engine_configuration.optional_value_fields_required = original_configuration
+        Scimitar::Schema::Email.instance_variable_set('@scim_attributes', nil)
+      end
+
+      it 'requires a value by default' do
+        resource = MyCustomResource.new(vdtpTestByEmail: { value: nil }, enforce: false)
+        expect(resource.valid?).to be(false)
+        expect(resource.errors.full_messages).to match_array(['Vdtptestbyemail value is required'])
+      end
+
+      it 'can be configured for optional values' do
+        Scimitar.engine_configuration.optional_value_fields_required = false
+        resource = MyCustomResource.new(vdtpTestByEmail: { value: nil }, enforce: false)
+        expect(resource.valid?).to be(true)
+      end
+    end # "context 'configuration of required values in VDTP schema' do"
+  end # "context '#valid?' do"
 end

data/spec/models/scimitar/schema/base_spec.rb

@@ -11,7 +11,7 @@ RSpec.describe Scimitar::Schema::Base do
   end
 
   context '#initialize' do
-    it 'creates a meta' do
+    it 'creates "meta"' do
       schema = described_class.new
       expect(schema.meta.resourceType).to eql('Schema')
     end

data/spec/models/scimitar/schema/user_spec.rb

@@ -419,6 +419,16 @@ RSpec.describe Scimitar::Schema::User do
             "name": "type",
             "type": "string"
           },
+          {
+            "multiValued": false,
+            "required": false,
+            "caseExact": false,
+            "mutability": "readWrite",
+            "uniqueness": "none",
+            "returned": "default",
+            "name": "primary",
+            "type": "boolean"
+          },
           {
             "multiValued": false,
             "required": false,

data/spec/requests/active_record_backed_resources_controller_spec.rb

@@ -180,6 +180,7 @@ RSpec.describe Scimitar::ActiveRecordBackedResourcesController do
               givenName: 'Given',
               familyName: 'Family'
             },
+            meta: { resourceType: 'User' },
             emails: [
               {
                 type: 'work',

data/spec/requests/application_controller_spec.rb

@@ -11,11 +11,14 @@ RSpec.describe Scimitar::ApplicationController do
   end
 
   context 'format handling' do
-    it 'renders "not acceptable" if the request does not use SCIM type' do
+    it 'renders "OK" if the request does not provide any Content-Type value' do
       get '/CustomRequestVerifiers', params: { format: :html }
 
-      expect(response).to have_http_status(:not_acceptable)
-      expect(JSON.parse(response.body)['detail']).to eql('Only application/scim+json type is accepted.')
+      expect(response).to have_http_status(:ok)
+      parsed_body = JSON.parse(response.body)
+      expect(parsed_body['request']['is_scim'     ]).to eql(true)
+      expect(parsed_body['request']['format'      ]).to eql('application/scim+json')
+      expect(parsed_body['request']['content_type']).to eql('application/scim+json')
     end
 
     it 'renders 400 if given bad JSON' do

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: scimitar
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
-- RIP Global
+- RIPA Global
 - Andrew David Hodgkinson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-09-15 00:00:00.000000000 Z
+date: 2022-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -115,17 +115,17 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.2'
 description: SCIM v2 support for Users and Groups in Ruby On Rails
 email:
-- dev@ripglobal.com
+- dev@ripaglobal.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -237,11 +237,14 @@ files:
 - spec/spec_helper.rb
 - spec/spec_helper_spec.rb
 - spec/support/hash_with_indifferent_case_insensitive_access_spec.rb
-homepage: https://ripglobal.com/
+homepage: https://www.ripaglobal.com/
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/RIPGlobal/scimitar
+  homepage_uri: https://www.ripaglobal.com/
+  source_code_uri: https://github.com/RIPAGlobal/scimitar/
+  bug_tracker_uri: https://github.com/RIPAGlobal/scimitar/issues/
+  changelog_uri: https://github.com/RIPAGlobal/scimitar/blob/master/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths: