scimitar 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7c0cb7d5ff4346954d9aab0d83ae22fcd75fcc456b9be54d74e22334cf4e273
+  data.tar.gz: 47adaec88f0418f18294fb19374be773cbfafa6c94b8870e38a349f70a4c53b4
+SHA512:
+  metadata.gz: 59a7f529e86667e14de8a6c0a0b0bc9a26cd53b21b53656be8b2f37d31e4cddcc1d0fccdefe2ff695d31baf19764489903a59e61f31e863e78c544f5dd24d550
+  data.tar.gz: '09d32ab29c325fa047f9e77daababa2bc763b79ee97e3b0b961202b60901b3ace406f5f66f63fd5c56b015a86e368294d4ec1e4b98b3588e7f4b75c72280e9e3'

data/Rakefile

@@ -0,0 +1,16 @@
+require 'rake'
+require 'rspec/core/rake_task'
+require 'rdoc/task'
+require 'sdoc'
+
+RSpec::Core::RakeTask.new(:default) do | t |
+end
+
+Rake::RDocTask.new do | rd |
+  rd.rdoc_files.include('README.md', 'lib/**/*.rb', 'app/**/*.rb')
+
+  rd.title     = 'Scimitar'
+  rd.main      = 'README.md'
+  rd.rdoc_dir  = 'docs/rdoc'
+  rd.generator = 'sdoc'
+end

data/app/controllers/scimitar/active_record_backed_resources_controller.rb

@@ -0,0 +1,180 @@
+require_dependency "scimitar/application_controller"
+
+module Scimitar
+
+  # An ActiveRecord-centric subclass of Scimitar::ResourcesController. See that
+  # class's documentation first, as it describes things that your subclass must
+  # do which apply equally to subclasses of this ActiveRecord-focused code.
+  #
+  # In addition to requirements mentioned above, your subclass MUST override
+  # protected method #storage_scope, returning an ActiveRecord::Relation which
+  # is used as a starting scope for any 'index' (list) views. This gives you an
+  # opportunity to apply things like is-active filters, apply soft deletion
+  # scopes, apply security scopes and so-on. For example:
+  #
+  #     protected
+  #       def storage_scope
+  #         self.storage_class().where(is_deleted: false)
+  #       end
+  #
+  class ActiveRecordBackedResourcesController < ResourcesController
+
+    rescue_from ActiveRecord::RecordNotFound, with: :handle_resource_not_found # See Scimitar::ApplicationController
+
+    # GET (list)
+    #
+    def index
+      query = if params[:filter].blank?
+        self.storage_scope()
+      else
+        attribute_map = storage_class().new.scim_queryable_attributes()
+        parser        = ::Scimitar::Lists::QueryParser.new(attribute_map)
+
+        parser.parse(params[:filter])
+        parser.to_activerecord_query(self.storage_scope())
+      end
+
+      pagination_info = scim_pagination_info(query.count())
+
+      page_of_results = query
+        .offset(pagination_info.offset)
+        .limit(pagination_info.limit)
+        .to_a()
+
+      super(pagination_info, page_of_results) do | record |
+        record.to_scim(location: url_for(action: :show, id: record.id))
+      end
+    end
+
+    # GET/id (show)
+    #
+    def show
+      super do |record_id|
+        record = self.find_record(record_id)
+        record.to_scim(location: url_for(action: :show, id: record_id))
+      end
+    end
+
+    # POST (create)
+    #
+    def create
+      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)
+          record.to_scim(location: url_for(action: :show, id: record.id))
+        end
+      end
+    end
+
+    # PUT (replace)
+    #
+    def replace
+      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)
+          record.to_scim(location: url_for(action: :show, id: record.id))
+        end
+      end
+    end
+
+    # PATCH (update)
+    #
+    def update
+      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)
+          record.to_scim(location: url_for(action: :show, id: record.id))
+        end
+      end
+    end
+
+    # DELETE (remove)
+    #
+    # Deletion methods can vary quite a lot with ActiveRecord objects. If you
+    # just let this superclass handle things, it'll call:
+    #
+    #   https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-destroy-21
+    #
+    # ...i.e. the standard delete-record-with-callbacks method. If you pass
+    # a block, then this block is invoked and passed the ActiveRecord model
+    # instance to be destroyed. You can then do things like soft-deletions,
+    # updating an "active" flag, perform audit-related operations and so-on.
+    #
+    def destroy(&block)
+      super do |record_id|
+        record = self.find_record(record_id)
+
+        if block_given?
+          yield(record)
+        else
+          record.destroy!
+        end
+      end
+    end
+
+    # =========================================================================
+    # PROTECTED INSTANCE METHODS
+    # =========================================================================
+    #
+    protected
+
+      # Return an ActiveRecord::Relation used as the starting scope for #index
+      # lists and any 'find by ID' operation.
+      #
+      def storage_scope
+        raise NotImplementedError
+      end
+
+      # Find a RIP user record. Subclasses can override this if they need
+      # special lookup behaviour.
+      #
+      # +record_id+:: Record ID (SCIM schema 'id' value - "our" ID).
+      #
+      def find_record(record_id)
+        self.storage_scope().find(record_id)
+      end
+
+      # Save a record, dealing with validation exceptions by raising SCIM
+      # errors.
+      #
+      # +record+:: ActiveRecord subclass to save (via #save!).
+      #
+      # The return value is not used internally, making life easier for
+      # overriding subclasses to "do the right thing" / avoid mistakes (instead
+      # of e.g. requiring that a to-SCIM representation of 'record' is returned
+      # and relying upon this to generate correct response payloads - an early
+      # version of the gem did this and it caused a confusing subclass bug).
+      #
+      def save!(record)
+        record.save!
+
+      rescue ActiveRecord::RecordInvalid => exception
+        joined_errors = record.errors.full_messages.join('; ')
+
+        # https://tools.ietf.org/html/rfc7644#page-12
+        #
+        #   If the service provider determines that the creation of the requested
+        #   resource conflicts with existing resources (e.g., a "User" resource
+        #   with a duplicate "userName"), the service provider MUST return HTTP
+        #   status code 409 (Conflict) with a "scimType" error code of
+        #   "uniqueness"
+        #
+        if record.errors.any? { | e | e.type == :taken }
+          raise Scimitar::ErrorResponse.new(
+            status:   409,
+            scimType: 'uniqueness',
+            detail:   joined_errors
+          )
+        else
+          raise Scimitar::ResourceInvalidError.new(joined_errors)
+        end
+      end
+
+  end
+end

data/app/controllers/scimitar/application_controller.rb

@@ -0,0 +1,129 @@
+module Scimitar
+  class ApplicationController < ActionController::Base
+
+    rescue_from StandardError,                                with: :handle_unexpected_error
+    rescue_from ActionDispatch::Http::Parameters::ParseError, with: :handle_bad_json_error # Via "ActionDispatch::Request.parameter_parsers" block in lib/scimitar/engine.rb
+    rescue_from Scimitar::ErrorResponse,                      with: :handle_scim_error
+
+    before_action :require_scim
+    before_action :add_mandatory_response_headers
+    before_action :authenticate
+
+    if Scimitar.engine_configuration.application_controller_mixin
+      include Scimitar.engine_configuration.application_controller_mixin
+    end
+
+    # =========================================================================
+    # PROTECTED INSTANCE METHODS
+    # =========================================================================
+    #
+    protected
+
+      # You can use:
+      #
+      #    rescue_from SomeException, with: :handle_resource_not_found
+      #
+      # ...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]))
+      end
+
+      # This base controller uses:
+      #
+      #    rescue_from Scimitar::ErrorResponse, with: :handle_scim_error
+      #
+      # ...to "globally" invoke this handler for all Scimitar errors (including
+      # subclasses).
+      #
+      # +error_response+:: Scimitar::ErrorResponse (or subclass) instance.
+      #
+      def handle_scim_error(error_response)
+        render json: error_response, status: error_response.status
+      end
+
+      # This base controller uses:
+      #
+      #     rescue_from ActionDispatch::Http::Parameters::ParseError, with: :handle_bad_json_error
+      #
+      # ...to "globally" handle JSON errors implied by parse errors raised via
+      # the "ActionDispatch::Request.parameter_parsers" block in
+      # lib/scimitar/engine.rb.
+      #
+      # +exception+:: Exception instance.
+      #
+      def handle_bad_json_error(exception)
+        handle_scim_error(ErrorResponse.new(status: 400, detail: "Invalid JSON - #{exception.message}"))
+      end
+
+      # This base controller uses:
+      #
+      #     rescue_from StandardError, with: :handle_unexpected_error
+      #
+      # ...to "globally" handle 500-style cases with a SCIM response.
+      #
+      # +exception+:: Exception instance.
+      #
+      def handle_unexpected_error(exception)
+        Rails.logger.error("#{exception.message}\n#{exception.backtrace}")
+        handle_scim_error(ErrorResponse.new(status: 500, detail: exception.message))
+      end
+
+    # =========================================================================
+    # PRIVATE INSTANCE METHODS
+    # =========================================================================
+    #
+    private
+
+      # Tries to be permissive in what it receives - ".scim" extensions or a
+      # Content-Type header (or both) lead to both being set up for the inbound
+      # request and subclass processing.
+      #
+      def require_scim
+        if request.content_type&.downcase == Mime::Type.lookup_by_extension(:scim).to_s
+          request.format = :scim
+        elsif request.format == :scim
+          request.headers['CONTENT_TYPE'] = Mime::Type.lookup_by_extension(:scim).to_s
+        else
+          handle_scim_error(ErrorResponse.new(status: 406, detail: "Only #{Mime::Type.lookup_by_extension(:scim)} type is accepted."))
+        end
+      end
+
+      def add_mandatory_response_headers
+
+        # https://tools.ietf.org/html/rfc7644#section-2
+        #
+        #   "...a SCIM service provider SHALL indicate supported HTTP
+        #   authentication schemes via the "WWW-Authenticate" header."
+        #
+        # Rack may not handle an attempt to set two instances of the header and
+        # there is much debate on how to specify multiple methods in one header
+        # so we just let Token override Basic (since Token is much stronger, or
+        # at least has the potential to do so) if that's how Rack handles it.
+        #
+        # 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?
+      end
+
+      def authenticate
+        handle_scim_error(Scimitar::AuthenticationError.new) unless authenticated?
+      end
+
+      def authenticated?
+        result = if Scimitar.engine_configuration.basic_authenticator.present?
+          authenticate_with_http_basic(&Scimitar.engine_configuration.basic_authenticator)
+        end
+
+        result ||= if Scimitar.engine_configuration.token_authenticator.present?
+          authenticate_with_http_token(&Scimitar.engine_configuration.token_authenticator)
+        end
+
+        return result
+      end
+
+  end
+end

data/app/controllers/scimitar/resource_types_controller.rb

@@ -0,0 +1,28 @@
+require_dependency "scimitar/application_controller"
+
+module Scimitar
+  class ResourceTypesController < ApplicationController
+    def index
+      resource_types = Scimitar::Engine.resources.map do |resource|
+        resource.resource_type(scim_resource_type_url(name: resource.resource_type_id))
+      end
+
+      render json: resource_types
+    end
+
+    def show
+      resource_types = Scimitar::Engine.resources.reduce({}) do |hash, resource|
+        hash[resource.resource_type_id] = resource.resource_type(scim_resource_type_url(name: resource.resource_type_id))
+        hash
+      end
+
+      resource_type = resource_types[params[:name]]
+
+      if resource_type.nil?
+        raise Scimitar::NotFoundError.new(params[:name])
+      else
+        render json: resource_type
+      end
+    end
+  end
+end

data/app/controllers/scimitar/resources_controller.rb

@@ -0,0 +1,203 @@
+require_dependency "scimitar/application_controller"
+
+module Scimitar
+
+  # A Rails controller which is mostly idiomatic, with #index, #show, #create
+  # and #destroy methods mapping to the conventional HTTP methods in Rails.
+  # The #update method is used for partial-update PATCH calls, while the
+  # #replace method is used for whole-update PUT calls.
+  #
+  # Subclass this controller to deal with resource-specific API calls, for
+  # endpoints such as Users and Groups. Any one controller is assumed to be
+  # related to one class in your application which has mixed in
+  # Scimitar::Resources::Mixin. Your subclass MUST override protected method
+  # #storage_class, which returns that class. For example, if you had a class
+  # User with the mixin included, then:
+  #
+  #     protected
+  #       def storage_class
+  #         User
+  #       end
+  #
+  # ...is sufficient.
+  #
+  # The controller makes no assumptions about storage method - it does not have
+  # any ActiveRecord specialisations, for example. If you do use ActiveRecord,
+  # consider subclassing Scimitar::ActiveRecordBackedResourcesController
+  # instead as it does most of the mapping, persistence and error handling work
+  # for you.
+  #
+  class ResourcesController < ApplicationController
+
+    # GET (list)
+    #
+    # Pass a Scimitar::Lists::Count object providing pagination data along with
+    # a page of results in "your" data domain as an Enumerable, along with a
+    # block. Renders as "list" result by calling your block with each of the
+    # results, allowing you to use something like
+    # Scimitar::Resources::Mixin#to_scim to convert to a SCIM representation.
+    #
+    # +pagination_info+:: A Scimitar::Lists::Count instance with #total set.
+    #                     See e.g. protected method #scim_pagination_info to
+    #                     assist with this.
+    #
+    # +page_of_results+:: An Enumerable single page of results.
+    #
+    def index(pagination_info, page_of_results, &block)
+      render(json: {
+        schemas: [
+            'urn:ietf:params:scim:api:messages:2.0:ListResponse'
+        ],
+        totalResults: pagination_info.total,
+        startIndex:   pagination_info.start_index,
+        itemsPerPage: pagination_info.limit,
+        Resources:    page_of_results.map(&block)
+      })
+    end
+
+    # GET/id (show)
+    #
+    # Call with a block that is passed an ID to find in "your" domain. Evaluate
+    # to the SCIM representation of the arising found record.
+    #
+    def show(&block)
+      scim_resource = yield(self.safe_params()[:id])
+      render(json: scim_resource)
+    end
+
+    # POST (create)
+    #
+    # Call with a block that is passed a SCIM resource instance - e.g a
+    # Scimitar::Resources::User instance - representing an item to be created.
+    # Your ::storage_class class's ::scim_resource_type method determines the
+    # kind of object you'll be given.
+    #
+    # See also e.g. Scimitar::Resources::Mixin#from_scim!.
+    #
+    # Evaluate to the SCIM representation of the arising created record.
+    #
+    def create(&block)
+      with_scim_resource() do |resource|
+        render(json: yield(resource, :create), status: :created)
+      end
+    end
+
+    # PUT (replace)
+    #
+    # Similar to #create, but you're passed an ID to find as well as the
+    # resource details to then use for all replacement attributes in that found
+    # resource. See also e.g. Scimitar::Resources::Mixin#from_scim!.
+    #
+    # Evaluate to the SCIM representation of the arising created record.
+    #
+    def replace(&block)
+      with_scim_resource() do |resource|
+        render(json: yield(self.safe_params()[:id], resource))
+      end
+    end
+
+    # PATCH (update)
+    #
+    # A variant of #create where you're again passed the resource ID (in "your"
+    # domain) to look up, but then a Hash with patch operation details from the
+    # calling client. This can be passed to e.g.
+    # Scimitar::Resources::Mixin#from_scim_patch!.
+    #
+    # Evaluate to the SCIM representation of the arising created record.
+    #
+    def update(&block)
+      validate_request()
+
+      # Params includes all of the PATCH data at the top level along with other
+      # other Rails-injected params like 'id', 'action', 'controller'. These
+      # are harmless given no namespace collision and we're only interested in
+      # the 'Operations' key for the actual patch data.
+      #
+      render(json: yield(self.safe_params()[:id], self.safe_params().to_hash()))
+    end
+
+    # DELETE (remove)
+    #
+    def destroy
+      if yield(self.safe_params()[:id]) != false
+        head :no_content
+      else
+        raise ErrorResponse.new(
+          status: 500,
+          detail: "Failed to delete the resource with id '#{params[:id]}'. Please try again later."
+        )
+      end
+    end
+
+    # =========================================================================
+    # PROTECTED INSTANCE METHODS
+    # =========================================================================
+    #
+    protected
+
+      # The class including Scimitar::Resources::Mixin which declares mappings
+      # to the entity you return in #resource_type.
+      #
+      def storage_class
+        raise NotImplementedError
+      end
+
+      # For #index actions, returns a Scimitar::Lists::Count instance which can
+      # be used to access offset-vs-start-index (0-indexed or 1-indexed),
+      # per-page limit and also holds the total number-of-items count which you
+      # can optionally pass up-front here, or set via #total= later.
+      #
+      # +total_count+:: Optional integer total record count across all pages,
+      #                 else must be set later - BEFORE passing an instance to
+      #                 the #index implementation in this class.
+      #
+      def scim_pagination_info(total_count = nil)
+        ::Scimitar::Lists::Count.new(
+          start_index: params[:startIndex],
+          limit:       params[:count] || Scimitar.service_provider_configuration(location: nil).filter.maxResults,
+          total:       total_count
+        )
+      end
+
+    # =========================================================================
+    # PRIVATE INSTANCE METHODS
+    # =========================================================================
+    #
+    private
+
+      def validate_request
+        if request.raw_post.blank?
+          raise Scimitar::ErrorResponse.new(status: 400, detail: 'must provide a request body')
+        end
+      end
+
+      def with_scim_resource
+        validate_request()
+
+        resource_type = storage_class().scim_resource_type() # See Scimitar::Resources::Mixin
+        resource      = resource_type.new(self.safe_params().to_h)
+
+        if resource.valid?
+          yield(resource)
+        else
+          raise Scimitar::ErrorResponse.new(
+            status:   400,
+            detail:   "Invalid resource: #{resource.errors.full_messages.join(', ')}.",
+            scimType: 'invalidValue'
+          )
+        end
+
+      # Gem bugs aside - if this happens, we couldn't create "resource"; bad
+      # (or unsupported) attributes encountered in inbound payload data.
+      #
+      rescue NoMethodError => exception
+        Rails.logger.error("#{exception.message}\n#{exception.backtrace}")
+        raise Scimitar::ErrorResponse.new(status: 400, detail: 'Invalid request')
+      end
+
+      def safe_params
+        params.permit!
+      end
+
+  end
+end