scimitar 1.8.2 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f83c7d7e476706bfc909fa2e08761aa544333d9fd32f077b0c453949f06cb8e9
-  data.tar.gz: a9c847ec6f3ebd6d16cb8efae0093bc6fca33e5e05975532aeb17983eed79d0d
+  metadata.gz: 5860adcfd6c793922be88ef8bb7bb878571e8fcd34ea89ead9d0278f09582cff
+  data.tar.gz: 2f7bf25e40156c0f006255c0c015f6302c8de39fc1634be789dba462d43f8c4a
 SHA512:
-  metadata.gz: 7ab73ba381492e4db44d42db596c897fdeb4609d24e7d5bc4f2f02d86db358030f6c3f9817e8c5209cd57212e0eeb79eed13fd1dd2f0f816f96af28217542827
-  data.tar.gz: c1961bb8075943be194bfe129db14d96e60a016001f56b61b51c001e589a7e56c53899c0119b9a07bf1a0e9ef204bd66d6b7802694a795bf969294000c2837b1
+  metadata.gz: 8047867c9365db25571693526e765d1a1a6b6d9cd17278f4bca2037815b5f9e0b9945390cc5ffba0228b9fabd3b15deae253519bbbe74ada2c262718d1c54989
+  data.tar.gz: 6ef777d96c932404c1ae0209804010fee98e993ce289d4eac09e0c8c3395b0de390fb423611d599fb6750a5d46e34545e0685e9563441fcc2d582fb5b6d1618f

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 RIPA Global
+Copyright (c) 2024 RIPA Global
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -79,7 +79,7 @@ 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).
 
-**Important:** Under some more recent versions of Rails 6, you may need to wrap any Scimitar configuration with `Rails.application.config.to_prepare do...` to avoid `NameError: uninitialized constant...` exceptions arising due to autoloader problems:
+**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.
 
 ```ruby
 Rails.application.config.to_prepare do
@@ -89,6 +89,8 @@ Rails.application.config.to_prepare do
 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.
+
 ### Routes
 
 For each resource you support, add these lines to your `routes.rb`:
@@ -244,8 +246,6 @@ If you use ActiveRecord, your controllers can potentially be extremely simple by
 module Scim
   class UsersController < Scimitar::ActiveRecordBackedResourcesController
 
-    skip_before_action :verify_authenticity_token
-
     protected
 
       def storage_class
@@ -321,7 +321,7 @@ end
 
 #### Other source types
 
-If you do _not_ use ActiveRecord to store data, or if you have very esoteric read-write requirements, you can subclass [`Scimigar::ResourcesController`](https://www.rubydoc.info/gems/scimitar/Scimitar/ResourcesController) in a manner similar to this:
+If you do _not_ use ActiveRecord to store data, or if you have very esoteric read-write requirements, you can subclass [`Scimitar::ResourcesController`](https://www.rubydoc.info/gems/scimitar/Scimitar/ResourcesController) in a manner similar to this:
 
 ```ruby
 class UsersController < Scimitar::ResourcesController
@@ -457,7 +457,9 @@ You can extend schema with custom data by defining an extension class and callin
 * Must call `super` in `def initialize`, providing data as shown in the example below
 * Must define class methods for `::id` and `::scim_attributes`
 
-The `::id` class method defines a unique schema ID that is used to namespace payloads or paths in JSON responses describing extended resources, JSON payloads creating them or PATCH paths modifying them. The SCIM RFCs would refer to this as the URN. For example, we might choose to use the [RFC-defined User extension schema](https://tools.ietf.org/html/rfc7643#section-4.3) to define a couple of extra fields our User model happens to support:
+The `::id` class method defines a unique schema ID that is used to namespace payloads or paths in JSON responses describing extended resources, JSON payloads creating them or PATCH paths modifying them. The RFCs require this to be a URN ([see RFC 2141](https://tools.ietf.org/html/rfc2141)). Your extension's ID URN must be globally unique. Depending on your expected use case, you should review the [IANA registration considerations that RFC 7643 describes](https://tools.ietf.org//html/rfc7643#section-10) and definitely review the [syntactic structure declaration therein](https://tools.ietf.org/html/rfc7643#section-10.2.1) (`urn:ietf:params:scim:{type}:{name}{:other}`).
+
+For example, we might choose to use the [RFC-defined User extension schema](https://tools.ietf.org/html/rfc7643#section-4.3) to define a couple of extra fields our User model happens to support:
 
 ```ruby
 class UserEnterpriseExtension < Scimitar::Schema::Base
@@ -542,6 +544,8 @@ Whatever you provide in the `::id` method in your extension class will be used a
 }
 ```
 
+**IMPORTANT: Attribute names must be unique** across your entire combined schema, regardless of URNs used. This is because of a limitation in Scimitar's implementation. [This GitHub issue](https://github.com/RIPAGlobal/scimitar/issues/130) explains more. If this is a problem for you, please comment on the GitHub issue to help the maintainers understand the level of demand for remediation.
+
 Resource extensions can provide any fields you choose, under any ID/URN you choose, to either RFC-described resources or entirely custom SCIM resources. There are no hard-coded assumptions or other "magic" that might require you to only extend RFC-described resources with RFC-described extensions. Of course, if you use custom resources or custom extensions that are not described by the SCIM RFCs, then the SCIM API you provide may only work with custom-written API callers that are aware of your bespoke resources and/or extensions.
 
 Extensions can also contain complex attributes such as groups. For instance, if you want the ability to write to groups from the User resource perspective (since 'groups' collection in a SCIM User resource is read-only), you can add one attribute to your extension like this:
@@ -580,6 +584,23 @@ And write to it like this:
 }
 ```
 
+### Helping with auto-discovery
+
+If you have an API consumer entity querying your Scimitar-based SCIM API provider endpoint and want to enable a degree of auto-discovery for that entity, then depending on your implementation, there may be customisations you wish to make.
+
+#### Default resources
+
+By default, Scimitar advertises (via things like [the `/Schemas` endpoint](https://tools.ietf.org/html/rfc7644#section-4)) support for both a `User` and `Group` resource, but if you (say) only support a `User` concept, you override the default using code such as this in your `config/initializers/scimitar.rb` file:
+
+```ruby
+Rails.application.config.to_prepare do
+  Scimitar::Engine.set_default_resources([Scimitar::Resources::User])
+  # ...other Scimitar configuration / initialisation code...
+end
+```
+
+
+
 ## Security
 
 One vital feature of SCIM is its authorisation and security model. The best resource I've found to describe this in any detail is [section 2 of the protocol RFC, 7644](https://tools.ietf.org/html/rfc7644#section-2).
@@ -598,8 +619,6 @@ Often, you'll find that bearer tokens are in use by SCIM API consumers, but the
 
 ### Specification versus implementation
 
-* The `name` complex type of a User has `givenName` and `familyName` fields which [the RFC 7643 core schema](https://tools.ietf.org/html/rfc7643#section-8.7.1) describes as optional. Scimitar marks these as required, in the belief that most user synchronisation scenarios between clients and a Scimitar-based provider would require at least those names for basic user management on the provider side, in conjunction with the in-spec-required `userName` field. That's only if the whole `name` type is given at all - at the top level, this itself remains optional per spec, but if you're going to bother specifying names at all, Scimitar wants at least those two pieces of data.
-
 * Several complex types for User contain the same set of `value`, `display`, `type` and `primary` fields, all used in synonymous ways.
 
   - The `value` field - which is e.g. an e-mail address or phone number - is described as optional by [the RFC 7643 core schema](https://tools.ietf.org/html/rfc7643#section-8.7.1), also using "SHOULD" rather than "MUST" in field descriptions elsewhere. Scimitar marks this as required by default, since there's not much point being sent (say) an e-mail section which has entries that don't provide the e-mail address. Some services might send `null` values here regardless so, if you need to be able to accept such data, you can set [engine configuration option `optional_value_fields_required`](https://github.com/RIPAGlobal/scimitar/blob/main/config/initializers/scimitar.rb) to `false`.
@@ -618,6 +637,8 @@ Often, you'll find that bearer tokens are in use by SCIM API consumers, but the
 
 * [RFC 7644 indicates](https://tools.ietf.org/html/rfc7644#page-35) that a resource might only return its core schema in the `schemas` attribute if it was created without any extension fields used. Only if e.g. a subsequent `PATCH` operation added data provided by extension schema, would that extension also appear in `schemas`. This behaviour is extremely difficult to implement and Scimitar does not try - it will always return a resource's core schema and any/all defined extension schemas in the `schemas` array at all times.
 
+* As noted earlier, extension schema attribute names must be unique across your entire combined schema, regardless of schema IDs (URNs) used.
+
 If you believe choices made in this section may be incorrect, please [create a GitHub issue](https://github.com/RIPAGlobal/scimitar/issues/new) describing the problem.
 
 ### Omissions
@@ -630,20 +651,6 @@ If you believe choices made in this section may be incorrect, please [create a G
 
   It's very strange just specifying `emails co...`, since this is an Array which contains complex types. Is the filter there meant to try and match every attribute of the nested types in all array entries? I.e. if `type` happened to contain `example.com`, is that meant to match? It's strongly implied, because the next part of the filter specifically says `emails.value`. Again, we have to reach a little and assume that `emails.value` means "in _any_ of the objects in the `emails` Array, match all things where `value` contains `example.org`. It seems likely that this is a specification error and both of the specifiers should be `emails.value`.
 
-  Adding even more complexity - the specification shows filters _which include filters within them_. In the same way that PATCH operations use paths to identify attributes not just by name, but by filter matches within collections - e.g. `emails[type eq "work"]`, for all e-mail objects inside the `emails` array with a `type` attribute that has a value of `work`) - so also can a filter _contain a filter_, which isn't supported. So, this [example from the RFC](https://tools.ietf.org/html/rfc7644#page-23) is not supported by Scimitar:
-
-  - `filter=userType eq "Employee" and emails[type eq "work" and value co "@example.com"]`
-
-  Another filter shows a potential workaround:
-
-  - `filter=userType eq "Employee" and (emails.type eq "work")`
-
-  ...which is just a match on `emails.type`, so if you have a queryable attribute mapping defined for `emails.type`, that would become queryable. Likewise, you could rewrite the more complex prior example thus:
-
-  - `filter=userType eq "Employee" and emails.type eq "work" and emails.value co "@example.com"`
-
-  ...so adding a mapping for `emails.value` would then allow a database query to be constructed.
-
 * Currently filtering for lists is always matched case-insensitive regardless of schema declarations that might indicate otherwise, for `eq`, `ne`, `co`, `sw` and `ew` operators; for greater/less-thank style filters, case is maintained with simple `>`, `<` etc. database operations in use. The standard Group and User schema have `caseExact` set to `false` for just about anything readily queryable, so this hopefully would only ever potentially be an issue for custom schema.
 
 * As an exception to the above, attributes `id`, `externalId` and `meta.*` are matched case-sensitive. Filters that use `eq` on such attributes will end up a comparison using `=` rather than e.g. `ILIKE` (arising from https://github.com/RIPAGlobal/scimitar/issues/36).

data/app/controllers/scimitar/active_record_backed_resources_controller.rb

@@ -1,5 +1,3 @@
-require_dependency "scimitar/application_controller"
-
 module Scimitar
 
   # An ActiveRecord-centric subclass of Scimitar::ResourcesController. See that
@@ -19,7 +17,7 @@ module Scimitar
   #
   class ActiveRecordBackedResourcesController < ResourcesController
 
-    rescue_from ActiveRecord::RecordNotFound, with: :handle_resource_not_found # See Scimitar::ApplicationController
+    rescue_from 'ActiveRecord::RecordNotFound', with: :handle_resource_not_found # See Scimitar::ApplicationController
 
     before_action :obtain_id_column_name_from_attribute_map
 
@@ -174,7 +172,10 @@ module Scimitar
       # 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)))
+        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

data/app/controllers/scimitar/application_controller.rb

@@ -9,10 +9,6 @@ module Scimitar
     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
     # =========================================================================
@@ -153,5 +149,8 @@ module Scimitar
         return result
       end
 
+    if Scimitar.engine_configuration.application_controller_mixin
+      include Scimitar.engine_configuration.application_controller_mixin
+    end
   end
 end

data/app/controllers/scimitar/resource_types_controller.rb

@@ -1,5 +1,3 @@
-require_dependency "scimitar/application_controller"
-
 module Scimitar
   class ResourceTypesController < ApplicationController
     def index
@@ -7,7 +5,13 @@ module Scimitar
         resource.resource_type(scim_resource_type_url(name: resource.resource_type_id))
       end
 
-      render json: resource_types
+      render json: {
+        schemas: [
+            'urn:ietf:params:scim:api:messages:2.0:ListResponse'
+        ],
+        totalResults: resource_types.size,
+        Resources:    resource_types
+      }
     end
 
     def show

data/app/controllers/scimitar/resources_controller.rb

@@ -1,5 +1,3 @@
-require_dependency "scimitar/application_controller"
-
 module Scimitar
 
   # A Rails controller which is mostly idiomatic, with #index, #show, #create

data/app/controllers/scimitar/schemas_controller.rb

@@ -1,5 +1,3 @@
-require_dependency "scimitar/application_controller"
-
 module Scimitar
   class SchemasController < ApplicationController
     def index
@@ -14,8 +12,368 @@ module Scimitar
         hash
       end
 
-      render json: schemas_by_id[params[:name]] || schemas
+      list = if params.key?(:name)
+        [ schemas_by_id[params[:name]] ]
+      else
+        schemas
+      end
+
+      # Now we either have a simple render method, or a complex one.
+      #
+      schemas_to_render = if Scimitar.engine_configuration.schema_list_from_attribute_mappings.empty?
+        list
+      else
+        self.redraw_schema_list_using_mappings(list)
+      end
+
+      render(json: {
+        schemas: [
+            'urn:ietf:params:scim:api:messages:2.0:ListResponse'
+        ],
+        totalResults: schemas_to_render.size,
+        startIndex:   1,
+        itemsPerPage: schemas_to_render.size,
+        Resources:    schemas_to_render
+      })
     end
 
+    # =========================================================================
+    # PRIVATE INSTANCE METHODS
+    # =========================================================================
+    #
+    private
+
+      # Given a list of schema *instances*, find all Scimitar::Resources::Mixin
+      # inclusions to obtain classes with a ::scim_resource_type implementation
+      # that is invoked to get at the associated Scimitar resource class; each
+      # resource class then describes the schema it uses; the list is filtered
+      # to include only those found schemas. Then, for each, use the discovered
+      # class' attribute maps to walk the schema attribute tree alongside the
+      # map and render only mapped attributes. This is done via calling down to
+      # ::redraw_schema_using_mappings for each remaining schema in the list.
+      #
+      # An array of new schema data is returned.
+      #
+      # +list+:: Array of schema instances to examine.
+      #
+      def redraw_schema_list_using_mappings(list)
+
+        # Iterate over the configured model classes to build a mapping from
+        # Scimitar schema class to an array of one or more model classes that
+        # seem to use it. This is to detect the error condition wherein some
+        # schema gets used more than once, leading to multiple possible
+        # attribute map choices.
+        #
+        classes_using_scimitar_mixin = Scimitar.engine_configuration.schema_list_from_attribute_mappings
+        schema_to_resource_map       = {}
+
+        classes_using_scimitar_mixin.each do | model_class |
+          resource_class = model_class.scim_resource_type()
+          schemas        = resource_class.extended_schemas + [resource_class.schema]
+
+          schemas.each do | schema_class |
+            schema_to_resource_map[schema_class] ||= []
+            schema_to_resource_map[schema_class] <<  model_class
+          end
+        end
+
+        # Take the schema list and map to rewritten versions based on finding
+        # out which of the above resource classes use a given schema and then
+        # walking this schema's attribute tree while comparing against the
+        # resource class's attribute map. Unmapped attributes are removed. The
+        # reality of resource class attribute mutability might give different
+        # answers for the corresponding schema attribute's mutability; for any
+        # custom schema we'd expect a match, but for core schema where local
+        # resources don't quite work to spec, at least the /Schemas endpoint
+        # can try to reflect reality and aid auto-discovery.
+        #
+        redrawn_list = list.map do | schema_instance |
+          resource_classes_using_schema = schema_to_resource_map[schema_instance.class]
+
+          if resource_classes_using_schema.nil?
+            next # NOTE EARLY LOOP RESTART (schema not used by a resource)
+          elsif resource_classes_using_schema.size > 1
+            raise "Cannot infer attribute map for engine configuration 'schema_list_from_attribute_mappings: true' because multiple resource classes use schema '#{schema_instance.class.name}': #{resource_classes_using_schema.map(&:name).join(', ')}"
+          end
+
+          found_class = classes_using_scimitar_mixin.find do | class_using_scimitar_mixin |
+            resource_class = class_using_scimitar_mixin.scim_resource_type()
+
+            resource_class.schema == schema_instance.class ||
+            resource_class.extended_schemas.include?(schema_instance.class)
+          end
+
+          rebuilt_schema_instance = if found_class
+            redraw_schema_using_mappings(
+              original_schema_instance: schema_instance,
+              instance_including_mixin: found_class.new
+            )
+          else
+            nil
+          end
+
+          rebuilt_schema_instance
+        end
+
+        redrawn_list.compact!
+        redrawn_list
+      end
+
+      # "Redraw" a schema, by walking its attribute tree alongside a related
+      # resource class's attribute map. Only mapped attributes are included.
+      # The mapped model is checked for a read accessor and write ability is
+      # determined via Scimitar::Resources::Mixin#scim_mutable_attributes. This
+      # gives the actual read/write ability of the mapped attribute; if the
+      # schema's declared mutability differs, the *most restrictive* is chosen.
+      # For example, if the schema says read-write but the mapped model only
+      # has read ability, then "readOnly" is used. Conversely, if the schema
+      # says read-only but the mapped model has read-write, the schema's
+      # "readOnly" is chosen instead as the source of truth.
+      #
+      # See the implementation's comments for a table describing exactly how
+      # all mutability conflict cases are resolved.
+      #
+      # The returned schema instance may be a full or partial duplicate of the
+      # one given on input - some or all attributes and/or sub-attributes may
+      # have been duplicated due to e.g. mutability differences. Do not assume
+      # or rely upon this as a caller.
+      #
+      # Mandatory named parameters for external callers are:
+      #
+      # +original_schema_instance+::   The Scimitar::Schema::Base subclass
+      #                                schema *instance* that is to be examined
+      #                                and possibly "redrawn".
+      #
+      # +instance_including_mixin+::   Instance of the model class including
+      #                                Scimitar::Resources::Mixin, providing
+      #                                the attribute map to be examined.
+      #
+      # Named parameters used internally for recursive calls are:
+      #
+      # +scim_attributes_map+::        The fragment of the attribute map found
+      #                                from +instance_including_mixin+'s class
+      #                                initially, which is relevant to the
+      #                                current recursion level. E.g. it might
+      #                                be the sub-attributes map of "name",
+      #                                for things like a "familyName" mapping.
+      #
+      # +schema_attributes+::          An array of schema attributes for the
+      #                                current recursion level, corresponding
+      #                                to +scim_attributes_map+.
+      #
+      # +rebuilt_attribute_array+::    Redrawn schema attributes are collected
+      #                                into this array, which is altered in
+      #                                place. It is usually a 'subAttributes'
+      #                                property of a schema attribute that's
+      #                                provoked recursion in order to examine
+      #                                and rebuild its sub-attributes directly.
+      #
+      def redraw_schema_using_mappings(
+        original_schema_instance:,
+        instance_including_mixin:,
+
+        scim_attributes_map:     nil,
+        schema_attributes:       nil,
+        rebuilt_attribute_array: nil
+      )
+        schema_attributes   ||= original_schema_instance.scim_attributes
+        scim_attributes_map ||= instance_including_mixin
+          .class
+          .scim_attributes_map()
+          .with_indifferent_case_insensitive_access()
+
+        rebuilt_schema_instance = nil
+
+        if rebuilt_attribute_array.nil?
+          rebuilt_schema_instance                 = self.duplicate_attribute(original_schema_instance)
+          rebuilt_schema_instance.scim_attributes = []
+          rebuilt_attribute_array                 = rebuilt_schema_instance.scim_attributes
+        end
+
+        schema_attributes.each do | schema_attribute |
+          if schema_attribute.multiValued && schema_attribute.subAttributes&.any?
+            mapped_multivalue_attribute = scim_attributes_map[schema_attribute.name]
+
+            # We expect either an array in the attribute map to correspond with
+            # a multivalued schema attribute, or nothing. If we get some other
+            # non-Array, not-nil thing, it's just ignored.
+            #
+            if mapped_multivalue_attribute.is_a?(Array)
+
+              # A single-entry array with "list using" semantics, for a
+              # collection of an artbirary number of same-class items - e.g.
+              # Groups to which a User belongs.
+              #
+              # If this is an up-to-date mapping, there's a "class" entry that
+              # tells us what the collection is compromised of. If not, then we
+              # check for ActiveRecord collections as a fallback and if that is
+              # the case here, can use reflection to try and find the class. If
+              # all else fails, we drop to generic schema for the collection.
+              #
+              if mapped_multivalue_attribute.first&.dig(:list)
+                associated_resource_class = mapped_multivalue_attribute.first[:class]
+
+                if (
+                  associated_resource_class.nil? &&
+                  instance_including_mixin.is_a?(ActiveRecord::Base)
+                )
+                  associated_resource_class = instance_including_mixin
+                    .class
+                    .reflect_on_association(mapped_multivalue_attribute.first[:list])
+                    &.klass
+                end
+
+                if associated_resource_class.nil? || ! associated_resource_class.include?(Scimitar::Resources::Mixin)
+                  rebuilt_attribute_array << schema_attribute
+                else
+                  rebuilt_schema_attribute = self.duplicate_attribute(schema_attribute)
+                  rebuilt_schema_attribute.subAttributes = []
+                  rebuilt_attribute_array << rebuilt_schema_attribute
+
+                  redraw_schema_using_mappings(
+                    original_schema_instance: original_schema_instance,
+                    instance_including_mixin: associated_resource_class.new,
+                    scim_attributes_map:      mapped_multivalue_attribute.first[:using],
+                    schema_attributes:        schema_attribute.subAttributes,
+                    rebuilt_attribute_array:  rebuilt_schema_attribute.subAttributes
+                  )
+                end
+
+              # A one-or-more entry array with "match with" semantics, to match
+              # discrete mapped items with a particular value in a particular
+              # field - e.g. an e-mail of type "work" mapping the SCIM "value"
+              # to a local attribute of "work_email_address".
+              #
+              # Mutability or supported attributes here might vary per matched
+              # type. There's no way for SCIM schema to represent that so we
+              # just merge all the "using" mappings together, in order of array
+              # appearance, and have that combined attribute map treated as the
+              # data the schema response will use.
+              #
+              elsif mapped_multivalue_attribute.first&.dig(:match)
+                union_of_mappings = {}
+
+                mapped_multivalue_attribute.each do | mapped_multivalue_attribute_description |
+                  union_of_mappings.merge!(mapped_multivalue_attribute_description[:using])
+                end
+
+                rebuilt_schema_attribute = self.duplicate_attribute(schema_attribute)
+                rebuilt_schema_attribute.subAttributes = []
+                rebuilt_attribute_array << rebuilt_schema_attribute
+
+                redraw_schema_using_mappings(
+                  original_schema_instance: original_schema_instance,
+                  instance_including_mixin: instance_including_mixin,
+                  scim_attributes_map:      union_of_mappings,
+                  schema_attributes:        schema_attribute.subAttributes,
+                  rebuilt_attribute_array:  rebuilt_schema_attribute.subAttributes
+                )
+              end
+            end
+
+          elsif schema_attribute.subAttributes&.any?
+            mapped_subattributes = scim_attributes_map[schema_attribute.name]
+
+            if mapped_subattributes.is_a?(Hash)
+              rebuilt_schema_attribute = self.duplicate_attribute(schema_attribute)
+              rebuilt_schema_attribute.subAttributes = []
+              rebuilt_attribute_array << rebuilt_schema_attribute
+
+              redraw_schema_using_mappings(
+                original_schema_instance: original_schema_instance,
+                instance_including_mixin: instance_including_mixin,
+                scim_attributes_map:      mapped_subattributes,
+                schema_attributes:        schema_attribute.subAttributes,
+                rebuilt_attribute_array:  rebuilt_schema_attribute.subAttributes
+              )
+            end
+
+          else
+            mapped_attribute = scim_attributes_map[schema_attribute.name]
+
+            unless mapped_attribute.nil?
+              rebuilt_schema_attribute = self.duplicate_attribute(schema_attribute)
+              has_mapped_reader        = true
+              has_mapped_writer        = false
+
+              if mapped_attribute.is_a?(String) || mapped_attribute.is_a?(Symbol)
+                has_mapped_reader = instance_including_mixin.respond_to?(mapped_attribute)
+                has_mapped_writer = instance_including_mixin.scim_mutable_attributes().include?(mapped_attribute.to_sym)
+              end
+
+              # The schema is taken as the primary source of truth, leading to
+              # a matrix of "do we override it or not?" based on who is the
+              # more limited. When both have the same mutability there is no
+              # more work to do, so we just need to consider differences:
+              #
+              # Actual class support   Schema says   Result
+              # =============================================================
+              # readWrite              readOnly      readOnly  (schema wins)
+              # readWrite              writeOnly     writeOnly (schema wins)
+              # readOnly               readWrite     readOnly  (class wins)
+              # writeOnly              readWrite     writeOnly (class wins)
+              #
+              # Those cases are easy. But there are gnarly cases too, where we
+              # have no good answer and the class's mapped implementation is in
+              # essence broken compared to the schema. Since it is not useful
+              # to insist on the schema's not-reality version, the class wins.
+              #
+              # Actual class support   Schema says   Result
+              # ====================== =======================================
+              # readOnly               writeOnly     readOnly  (class "wins")
+              # writeOnly              readOnly      writeOnly (class "wins")
+
+              schema_attribute_mutability = schema_attribute.mutability.downcase
+
+              if has_mapped_reader && has_mapped_writer
+                #
+                # Read-write Nothing to do. Schema always "wins" by matching or
+                # being more restrictive than the class's actual abilities.
+
+              elsif has_mapped_reader && ! has_mapped_writer
+                #
+                # Read-only. Class is more restrictive if schema is 'readWrite'
+                # or if there's the broken clash of schema 'writeOnly'.
+                #
+                if schema_attribute_mutability == 'readwrite' || schema_attribute_mutability == 'writeonly'
+                  rebuilt_schema_attribute.mutability = 'readOnly'
+                end
+
+              elsif has_mapped_writer && ! has_mapped_reader
+                #
+                # Opposite to the above case.
+                #
+                if schema_attribute_mutability == 'readwrite' || schema_attribute_mutability == 'readonly'
+                  rebuilt_schema_attribute.mutability = 'writeOnly'
+                end
+
+                # ...else we cannot fathom how this class works - it appears to
+                # have no read or write accessor for the mapped attribute. Keep
+                # the schema's declaration as-is.
+                #
+              end
+
+              rebuilt_attribute_array << rebuilt_schema_attribute
+            end
+          end
+        end
+
+        return rebuilt_schema_instance # (meaningless except for topmost call)
+      end
+
+      # Small helper that duplicates Scimitar::Schema::Attribute instances, but
+      # then removes their 'errors' collection which otherwise gets initialised
+      # to an empty value and is rendered as if part of the schema (which isn't
+      # a valid entry in a SCIM schema representation).
+      #
+      # +schema_attribute+:: Scimitar::Schema::Attribute to be duplicated.
+      #                      A renderable duplicate is returned.
+      #
+      def duplicate_attribute(schema_attribute)
+        duplicated_schema_attribute = schema_attribute.dup()
+        duplicated_schema_attribute.remove_instance_variable('@errors')
+        duplicated_schema_attribute
+      end
+
   end
 end

data/app/controllers/scimitar/service_provider_configurations_controller.rb

@@ -1,4 +1,3 @@
-require_dependency "scimitar/application_controller"
 module Scimitar
   class ServiceProviderConfigurationsController < ApplicationController
     def show

data/app/models/scimitar/engine_configuration.rb

@@ -14,6 +14,7 @@ module Scimitar
       :application_controller_mixin,
       :exception_reporter,
       :optional_value_fields_required,
+      :schema_list_from_attribute_mappings,
     )
 
     def initialize(attributes = {})
@@ -22,7 +23,8 @@ module Scimitar
       # Set defaults that may be overridden by the initializer.
       #
       defaults = {
-        optional_value_fields_required: true
+        optional_value_fields_required:      true,
+        schema_list_from_attribute_mappings: []
       }
 
       super(defaults.merge(attributes))