powerhome-scimitar 1.0.0

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,257 @@
+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
+
+    before_action :obtain_id_column_name_from_attribute_map
+
+    # 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
+        .order(@id_column => :asc)
+        .offset(pagination_info.offset)
+        .limit(pagination_info.limit)
+        .to_a()
+
+      super(pagination_info, page_of_results) do | record |
+        record_to_scim(record)
+      end
+    end
+
+    # GET/id (show)
+    #
+    def show
+      super do |record_id|
+        record = self.find_record(record_id)
+        record_to_scim(record)
+      end
+    end
+
+    # POST (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, &block)
+          record_to_scim(record)
+        end
+      end
+    end
+
+    # PUT (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, &block)
+          record_to_scim(record)
+        end
+      end
+    end
+
+    # PATCH (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, &block)
+          record_to_scim(record)
+        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
+
+      # 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.
+      #
+      # +record_id+:: Record ID (SCIM schema 'id' value - "our" ID).
+      #
+      def find_record(record_id)
+        self.storage_scope().find_by!(@id_column => record_id)
+      end
+
+      # DRY up controller actions - pass a record; returns the SCIM
+      # representation, with a "show" location specified via #url_for.
+      #
+      def record_to_scim(record)
+        record.to_scim(
+          location: url_for(action: :show, id: record.send(@id_column)),
+          include_attributes: params.fetch(:attributes, "").split(",")
+        )
+      end
+
+      # Save a record, dealing with validation exceptions by raising SCIM
+      # errors.
+      #
+      # +record+:: ActiveRecord subclass to save.
+      #
+      # 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.
+      #
+      # 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, &block)
+        if block_given?
+          yield(record)
+        else
+          record.save!
+        end
+      rescue *self.scimitar_rescuable_exceptions() => exception
+        handle_on_save_exception(record, exception)
+      end
+
+      # 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 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_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
+        #
+        #   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 exception.is_a?(ActiveRecord::RecordNotUnique) || record.errors.any? { | e | e.type == :taken }
+          raise Scimitar::ErrorResponse.new(
+            status:   409,
+            scimType: 'uniqueness',
+            detail:   "Operation failed due to a uniqueness constraint: #{details}"
+          )
+        else
+          raise Scimitar::ResourceInvalidError.new(details)
+        end
+      end
+
+      # Called via +before_action+ - stores in @id_column the name of whatever
+      # model column is used to store the record ID, via
+      # Scimitar::Resources::Mixin::scim_attributes_map.
+      #
+      # Default is <tt>:id</tt>.
+      #
+      def obtain_id_column_name_from_attribute_map
+        attrs      = storage_class().scim_attributes_map() || {}
+        @id_column = attrs[:id] || :id
+      end
+
+  end
+end

data/app/controllers/scimitar/application_controller.rb

@@ -0,0 +1,157 @@
+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, 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:
+      #
+      #    rescue_from Scimitar::ErrorResponse, with: :handle_scim_error
+      #
+      # ...to "globally" invoke this handler for all Scimitar errors (including
+      # subclasses).
+      #
+      # Mandatory parameters are:
+      #
+      # +error_response+:: Scimitar::ErrorResponse (or subclass) instance.
+      #
+      # 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
+
+      # 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}"), exception)
+      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), exception)
+      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
+        scim_mime_type = Mime::Type.lookup_by_extension(:scim).to_s
+
+        if request.media_type.nil? || request.media_type.empty?
+          request.format = :scim
+          request.headers['CONTENT_TYPE'] = scim_mime_type
+        elsif request.media_type.downcase == scim_mime_type
+          request.format = :scim
+        elsif request.format == :scim
+          request.headers['CONTENT_TYPE'] = scim_mime_type
+        else
+          handle_scim_error(ErrorResponse.new(status: 406, detail: "Only #{scim_mime_type} 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?
+
+        # 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
+        handle_scim_error(Scimitar::AuthenticationError.new) unless authenticated?
+      end
+
+      def authenticated?
+        result = if Scimitar.engine_configuration.basic_authenticator.present?
+          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 do |token, options|
+            instance_exec(token, options, &Scimitar.engine_configuration.token_authenticator)
+          end
+        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

data/app/controllers/scimitar/schemas_controller.rb

@@ -0,0 +1,21 @@
+require_dependency "scimitar/application_controller"
+
+module Scimitar
+  class SchemasController < ApplicationController
+    def index
+      schemas = Scimitar::Engine.schemas
+
+      schemas.each do |schema|
+        schema.meta.location = scim_schemas_url(name: schema.id)
+      end
+
+      schemas_by_id = schemas.reduce({}) do |hash, schema|
+        hash[schema.id] = schema
+        hash
+      end
+
+      render json: schemas_by_id[params[:name]] || schemas
+    end
+
+  end
+end

data/app/controllers/scimitar/service_provider_configurations_controller.rb

@@ -0,0 +1,8 @@
+require_dependency "scimitar/application_controller"
+module Scimitar
+  class ServiceProviderConfigurationsController < ApplicationController
+    def show
+      render json: Scimitar.service_provider_configuration(location: request.url)
+    end
+  end
+end