scimaenaga 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dea244dd3c4735fe8f156571c07c630dbae4cee67cf46c53757aa77d74afb135
+  data.tar.gz: 52cd9e9e2459231d3b415083f28bbac20beac60952d4e2dc6531412ee419492a
+SHA512:
+  metadata.gz: e48ad1a2a9108a211f9bb5d15a258292212556281f30403d0d6d5e19a2a3b3dda882f635e11bbde0260fb16bfde43b926e79ae77faac713e7c494189928609eb
+  data.tar.gz: 9d737fe588c932bae532792c141f54a67f5d952874ea7e32151c17d01cc1d6abf3ef4dd25a8639e029be0781b721c23d70cf468a9945d1e33f84a627552acb1d

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2018 Lessonly
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,314 @@
+[![Tests](https://github.com/StudistCorporation/scim_rails/actions/workflows/test.yaml/badge.svg)](https://github.com/StudistCorporation/scim_rails/actions/workflows/test.yaml)
+[![Inline docs](http://inch-ci.org/github/lessonly/scim_rails.svg?branch=master)](http://inch-ci.org/github/lessonly/scim_rails)
+[![Maintainability](https://api.codeclimate.com/v1/badges/ddfb6a891d2f0d1122ae/maintainability)](https://codeclimate.com/github/lessonly/scim_rails/maintainability)
+
+# ScimRails
+
+NOTE: This Gem is not yet fully SCIM complaint. It was developed with the main function of interfacing with Okta. There are features of SCIM that this Gem does not implement as described in the SCIM documentation or that have been left out completely.
+
+#### What is SCIM?
+
+SCIM stands for System for Cross-domain Identity Management. At its core, it is a set of rules defining how apps should interact for the purpose of creating, updating, and deprovisioning users. SCIM requests and responses can be sent in XML or JSON and this Gem uses JSON for ease of readability.
+
+To learn more about SCIM 2.0 you can read the documentation at [RFC 7643](https://tools.ietf.org/html/rfc7643) and [RFC 7644](https://tools.ietf.org/html/rfc7644).
+
+The goal of the Gem is to offer a relatively painless way of adding SCIM 2.0 to your app. This Gem should be fully compatible with Okta's SCIM implementation. This project is ongoing and will hopefully be fully SCIM compliant in time. Pull requests that assist in meeting that goal are welcome!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'scim_rails'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install scim_rails
+```
+
+Generate the config file with:
+
+```bash
+$ rails generate scim_rails config
+```
+
+The config file will be located at:
+
+```
+config/initializers/scim_rails_config.rb
+```
+
+Please update the config file with the models and attributes of your app.
+
+Mount the gem in your routes file:
+
+```ruby
+Application.routes.draw do
+  mount ScimRails::Engine => "/"
+end
+```
+
+This will enable the following routes for the Gem to use:
+
+| Request | Route               |
+|:-------:|:-------------------:|
+| get     | 'scim/v2/Users'     |
+| post    | 'scim/v2/Users'     |
+| get     | 'scim/v2/Users/:id' |
+| put     | 'scim/v2/Users/:id' |
+| patch   | 'scim/v2/Users/:id' |
+
+Note: This Gem can be mounted to any path. For example:
+
+```
+https://scim.example.com/scim/v2/Users
+https://www.example.com/scim/v2/Users
+https://example.com/example/scim/v2/Users
+```
+
+## Usage
+
+#### Content-Type
+
+When sending requests to the server the `Content-Type` should be set to `application/scim+json` but will also respond to `application/json`.
+
+All responses will be sent with a `Content-Type` of `application/scim+json`.
+
+#### Authentication
+
+This gem supports both basic and OAuth bearer authentication.
+
+##### Basic Auth
+###### Username
+The config setting `basic_auth_model_searchable_attribute` is the model attribute used to authenticate as the `username`. It defaults to `:subdomain`.
+
+Ensure it is unique to the model records.
+
+###### Password
+The config setting `basic_auth_model_authenticatable_attribute` is the model attribute used to authenticate as `password`. Defaults to `:api_token`.
+
+Assuming the attribute is `:api_token`, generate the password using:
+```ruby
+token = ScimRails::Encoder.encode(company)
+# use the token as password for requests
+company.api_token = token # required
+company.save! # don't forget to persist the company record
+```
+
+This is necessary irrespective of your authentication choice(s) - basic auth, oauth bearer or both.
+
+###### Sample Request
+
+```bash
+$ curl -X GET 'http://username:password@localhost:3000/scim/v2/Users'
+```
+
+##### OAuth Bearer
+
+###### Signing Algorithm
+In the config settings, ensure you set `signing_algorithm` to a valid JWT signing algorithm, e.g "HS256". Defaults to `"none"` when not set.
+
+###### Signing Secret
+In the config settings, ensure you set `signing_secret` to a secret key that will be used to encode and decode tokens. Defaults to `nil` when not set.
+
+If you have already generated the `api_token` in the "Basic Auth" section, then use that as your bearer token and ignore the steps below:
+```ruby
+token = ScimRails::Encoder.encode(company)
+# use the token as bearer token for requests
+company.api_token = token #required
+company.save! # don't forget to persist the company record
+```
+
+##### Sample Request
+
+```bash
+$ curl -H 'Authorization: Bearer xxxxxxx.xxxxxx' -X GET 'http://localhost:3000/scim/v2/Users'
+```
+
+### List
+
+##### All
+
+Sample request:
+
+```bash
+$ curl -X GET 'http://username:password@localhost:3000/scim/v2/Users'
+```
+
+##### Pagination
+
+This Gem provides two pagination filters; `startIndex` and `count`.
+
+`startIndex` is the positional number you would like to start at. This parameter can accept any integer but anything less than 1 will be interpreted as 1. If you visualize an array with all your user records in the array, `startIndex` is basically what element you would like to start at. If you are familiar with SQL this parameter is directly correlated to the query offset. **The default value for this filter is 1.**
+
+`count` is the number of records you would like present in the response. **The default value for this filter is 100.**
+
+Sample request:
+
+```bash
+$ curl -X GET 'http://username:password@localhost:3000/scim/v2/Users?startIndex=38&count=44'
+```
+
+Pagination only really works with a determinate order. What that means is, every time you call the database you need to get the results in the exact same order. So the 4th record is _always_ the 4th record and never appears in a different position. If there is no order then records might show up on multiple pages. **The default order is by id** but this can be configured with `scim_users_list_order`.
+
+The pagination filters may be used on their own or in addition to the query filters listed in the next section.
+
+##### Querying
+
+Currently the only filter supported is a single level `eq`. More operators can be added fairly easily in future releases. The SCIM RFC documents nested querying which is something we would like to implement in the future.
+
+**Queryable attributes can be mapped in the configuration file.**
+
+Supported filters:
+
+```
+filter=email eq test@example.com
+fitler=userName eq test@example.com
+filter=formattedName eq Test User
+filter=id eq 1
+```
+
+Unsupported filter:
+
+```
+filter=(email eq test@example.com) or (userName eq test@example.com)
+```
+
+Sample request:
+
+```bash
+$ curl -X GET 'http://username:password@localhost:3000/scim/v2/Users?filter=formattedName%20eq%20%22Test%20User%22'
+```
+
+### Show
+
+This response can be modified in the configuration file. The `user_schema` configuration supports any JSON structure and will transform any values by calling symbols against the user model. A sample SCIM compliant response looks like:
+
+```
+{
+  schemas: ["urn:ietf:params:scim:schemas:core:2.0:User"],
+  id: "1",
+  userName: "test@example.com",
+  name: {
+    givenName: "Test",
+    familyName: "User"
+  },
+  emails: [
+    {
+      value: "test@example.com"
+    },
+  ],
+  active: "true"
+}
+```
+
+Sample request:
+
+```bash
+$ curl -X GET 'http://username:password@localhost:3000/scim/v2/Users/1'
+```
+
+### Create
+
+The create request can receive any SCIM compliant JSON but can only be parsed with the configuration schema provided. What that means is that if your app receives a request to modify an attribute that is not listed in your `mutable_user_attributes` configuration it will ignore the parameter. In addition to needing to be included in the mutable attributes it also requires `mutable_user_attributes_schema` which defines where the Gem should look for a given attribute.
+
+**Do not include attributes that you do not want modified** such as `id`. Any attributes can be provided in the `user_schema` configuration to be returned as part of the response but if they are not part of the `mutable_user_attributes_schema` then they cannot be modified.
+
+Sample request:
+
+```bash
+$ curl -X POST 'http://username:password@localhost:3000/scim/v2/Users/' -d '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"userName":"test@example.com","name":{"givenName":"Test","familyName":"User"},"emails":[{"primary":true,"value":"test@example.com","type":"work"}],"displayName":"Test User","active":true}' -H 'Content-Type: application/scim+json'
+```
+
+### Update
+
+Update requests follow the same guidelines as create requests. The request is parsed for the mutable attributes provided in the configuration file and sent to the user model to update those attributes. This request expects a full representation of the object and any missing mutable attributes will send `nil` to the user model. If the attribute cannot be blank and sends a validation error, that error will be rescued and the response will be an appropriate SCIM error.
+
+Sample request:
+
+```bash
+$ curl -X PUT 'http://username:password@localhost:3000/scim/v2/Users/1' -d '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"userName":"test@example.com","name":{"givenName":"Test","familyName":"User"},"emails":[{"primary":true,"value":"test@example.com","type":"work"}],"displayName":"Test User","active":true}' -H 'Content-Type: application/scim+json'
+```
+
+### Deprovision / Reprovision
+
+The PATCH request was implemented to work with Okta. Okta updates profiles with PUT and deprovisions / reprovisions with PATCH. This implementation of PATCH is not SCIM compliant as it does not update a single attribute on the user profile but instead only sends a status update request to the record.
+
+We would like to implement PATCH to be fully SCIM compliant in future releases.
+
+Sample request:
+
+```bash
+$ curl -X PATCH 'http://username:password@localhost:3000/scim/v2/Users/1' -d '{"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{"op": "replace", "value": { "active": false }}]}' -H 'Content-Type: application/scim+json'
+```
+
+### Error Handling
+
+By default, scim_rails will output any unhandled exceptions to your configured rails logs.
+
+If you would like, you can supply a custom handler for exceptions in the initializer. The only requirement is that the value you supply responds to `#call`.
+
+For example, you might want to notify Honeybadger:
+
+```ruby
+ScimRails.configure do |config|
+  config.on_error = ->(e) { Honeybadger.notify(e) }
+end
+```
+
+## Contributing
+
+### [Code of Conduct](https://github.com/lessonly/scim_rails/blob/master/CODE_OF_CONDUCT.md)
+
+### Pull Requests
+
+Pull requests are welcome and encouraged! Please follow the default template format.
+
+[How to create a pull request from a fork.](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)
+
+### Getting Started
+
+Clone (or fork) the project.
+
+Navigate to the top level of the project directory in your console and run `bundle install`.
+
+Proceed to setting up the dummy app.
+
+#### Dummy App
+
+This Gem contains a fully functional Rails application that lives in `/spec/dummy`.
+
+In the console, navigate to the dummy app at `/spec/dummy`.
+
+Next run `bin/setup` to setup the app. This will set up the gems and build the databases. The databases are local to the project.
+
+Last run `bundle exec rails server`.
+
+If you wish you may send CURL requests to the dummy server or send requests to it via Postman.
+
+### Specs
+
+Specs can be run with `rspec` at the top level of the project (if you run `rspec` and it shows zero specs try running `rspec` from a different directory).
+
+All specs should be passing. (The dummy app will need to be setup first.)
+
+## Current Maintainers
+
+Maintainers:
+- Are active contributors
+- Help set project direction
+- Merge contributions from contributors
+
+- [@wernull](https://github.com/wernull)
+- [@rreinhardt9](https://github.com/rreinhardt9)
+
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ScimRails'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+load 'rails/tasks/statistics.rake'
+
+
+Bundler::GemHelper.install_tasks
+
+Dir[File.join(File.dirname(__FILE__), 'tasks/**/*.rake')].each {|f| load f }
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+
+task :default => :spec

data/app/controllers/concerns/scim_rails/exception_handler.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module ScimRails
+  module ExceptionHandler
+    extend ActiveSupport::Concern
+
+    class InvalidCredentials < StandardError
+    end
+
+    class InvalidQuery < StandardError
+    end
+
+    class UnsupportedPatchRequest < StandardError
+    end
+
+    class UnsupportedDeleteRequest < StandardError
+    end
+
+    included do
+      if Rails.env.production?
+        rescue_from StandardError do |exception|
+          on_error = ScimRails.config.on_error
+          if on_error.respond_to?(:call)
+            on_error.call(exception)
+          else
+            Rails.logger.error(exception.inspect)
+          end
+
+          json_response(
+            {
+              schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+              status: "500"
+            },
+            :internal_server_error
+          )
+        end
+      end
+
+      rescue_from ScimRails::ExceptionHandler::InvalidCredentials do
+        json_response(
+          {
+            schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+            detail: "Authorization failure. The authorization header is invalid or missing.",
+            status: "401"
+          },
+          :unauthorized
+        )
+      end
+
+      rescue_from ScimRails::ExceptionHandler::InvalidQuery do
+        json_response(
+          {
+            schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+            scimType: "invalidFilter",
+            detail: "The specified filter syntax was invalid, or the specified attribute and filter comparison combination is not supported.",
+            status: "400"
+          },
+          :bad_request
+        )
+      end
+
+      rescue_from ScimRails::ExceptionHandler::UnsupportedPatchRequest do
+        json_response(
+          {
+            schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+            detail: "Invalid PATCH request. This PATCH endpoint only supports deprovisioning and reprovisioning records.",
+            status: "422"
+          },
+          :unprocessable_entity
+        )
+      end
+
+      rescue_from ScimRails::ExceptionHandler::UnsupportedDeleteRequest do
+        json_response(
+          {
+            schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+            detail: "Delete operation is disabled for the requested resource.",
+            status: "501"
+          },
+          :not_implemented
+        )
+      end
+
+      rescue_from ActiveRecord::RecordNotFound do |e|
+        json_response(
+          {
+            schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+            detail: "Resource #{e.id} not found.",
+            status: "404"
+          },
+          :not_found
+        )
+      end
+
+      rescue_from ActiveRecord::RecordInvalid do |e|
+        case e.message
+        when /has already been taken/
+          json_response(
+            {
+              schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+              detail: e.message,
+              status: "409"
+            },
+            :conflict
+          )
+        else
+          json_response(
+            {
+              schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+              detail: e.message,
+              status: "422"
+            },
+            :unprocessable_entity
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/concerns/scim_rails/response.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ScimRails
+  module Response
+    CONTENT_TYPE = "application/scim+json"
+
+    def json_response(object, status = :ok)
+      render \
+        json: object,
+        status: status,
+        content_type: CONTENT_TYPE
+    end
+
+    def json_scim_response(object:, status: :ok, counts: nil)
+      case params[:action]
+      when "index"
+        render \
+          json: list_response(object, counts),
+          status: status,
+          content_type: CONTENT_TYPE
+      when "show", "create", "put_update", "patch_update"
+        render \
+          json: object_response(object),
+          status: status,
+          content_type: CONTENT_TYPE
+      end
+    end
+
+    private
+
+    def list_response(object, counts)
+      object = object
+        .order(:id)
+        .offset(counts.offset)
+        .limit(counts.limit)
+      {
+        schemas: [
+          "urn:ietf:params:scim:api:messages:2.0:ListResponse"
+        ],
+        totalResults: counts.total,
+        startIndex: counts.start_index,
+        itemsPerPage: counts.limit,
+        Resources: list_objects(object)
+      }
+    end
+
+    def list_objects(objects)
+      objects.map do |object|
+        object_response(object)
+      end
+    end
+
+    def object_response(object)
+      schema = case object
+               when ScimRails.config.scim_users_model
+                 ScimRails.config.user_schema
+               when ScimRails.config.scim_groups_model
+                 ScimRails.config.group_schema
+               else
+                 raise ScimRails::ExceptionHandler::InvalidQuery,
+                       "Unknown model: #{object}"
+               end
+      find_value(object, schema)
+    end
+
+    # `find_value` is a recursive method that takes a "user" and a
+    # "user schema" and replaces any symbols in the schema with the
+    # corresponding value from the user. Given a schema with symbols,
+    # `find_value` will search through the object for the symbols,
+    # send those symbols to the model, and replace the symbol with
+    # the return value.
+
+    def find_value(object, schema)
+      case schema
+      when Hash
+        schema.each.with_object({}) do |(key, value), hash|
+          hash[key] = find_value(object, value)
+        end
+      when Array, ActiveRecord::Associations::CollectionProxy
+        schema.map do |value|
+          find_value(object, value)
+        end
+      when ScimRails.config.scim_users_model
+        find_value(schema, ScimRails.config.user_abbreviated_schema)
+      when ScimRails.config.scim_groups_model
+        find_value(schema, ScimRails.config.group_abbreviated_schema)
+      when Symbol
+        find_value(object, object.public_send(schema))
+      else
+        schema
+      end
+    end
+  end
+end

data/app/controllers/scim_rails/application_controller.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ScimRails
+  class ApplicationController < ActionController::API
+    include ActionController::HttpAuthentication::Basic::ControllerMethods
+    include ExceptionHandler
+    include Response
+
+    before_action :authorize_request
+
+    private
+
+    def authorize_request
+      send(authentication_strategy) do |searchable_attribute, authentication_attribute|
+        authorization = AuthorizeApiRequest.new(
+          searchable_attribute: searchable_attribute,
+          authentication_attribute: authentication_attribute
+        )
+        @company = authorization.company
+      end
+      raise ScimRails::ExceptionHandler::InvalidCredentials if @company.blank?
+    end
+
+    def authentication_strategy
+      if request.headers["Authorization"]&.include?("Bearer")
+        :authenticate_with_oauth_bearer
+      else
+        :authenticate_with_http_basic
+      end
+    end
+
+    def authenticate_with_oauth_bearer
+      authentication_attribute = request.headers["Authorization"].split.last
+      payload = ScimRails::Encoder.decode(authentication_attribute).with_indifferent_access
+      searchable_attribute = payload[ScimRails.config.basic_auth_model_searchable_attribute]
+
+      yield searchable_attribute, authentication_attribute
+    end
+
+    def find_value_for(attribute)
+      params.dig(*path_for(attribute))
+    end
+
+    # `path_for` is a recursive method used to find the "path" for
+    # `.dig` to take when looking for a given attribute in the
+    # params.
+    #
+    # Example: `path_for(:name)` should return an array that looks
+    # like [:names, 0, :givenName]. `.dig` can then use that path
+    # against the params to translate the :name attribute to "John".
+
+    def path_for(attribute, object = controller_schema, path = [])
+      at_path = path.empty? ? object : object.dig(*path)
+      return path if at_path == attribute
+
+      case at_path
+      when Hash
+        at_path.each do |key, _value|
+          found_path = path_for(attribute, object, [*path, key])
+          return found_path if found_path
+        end
+        nil
+      when Array
+        at_path.each_with_index do |_value, index|
+          found_path = path_for(attribute, object, [*path, index])
+          return found_path if found_path
+        end
+        nil
+      end
+    end
+  end
+end