Scimaenaga

NOTE: This Gem is not yet fully SCIM complaint. It was developed with the main function of interfacing with Azure AD. 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 and RFC 7644.

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 Azure AD'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:

gem 'scimaenaga'

And then execute:

$ bundle

Or install it yourself as:

$ gem install scimaenaga

Generate the config file with:

$ rails generate scimaenaga config

The config file will be located at:

config/initializers/scimaenaga_config.rb

Please update the config file with the models and attributes of your app.

Mount the gem in your routes file:

Application.routes.draw do
  mount Scimaenaga::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:

token = Scimaenaga::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

$ 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:

token = Scimaenaga::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

$ curl -H 'Authorization: Bearer xxxxxxx.xxxxxx' -X GET 'http://localhost:3000/scim/v2/Users'

List

All

Sample request:

$ 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:

$ 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:

$ 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:

$ 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:

$ 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:

$ 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 Azure AD. Azure AD deprovisions / reprovisions with PATCH.

Sample request:

$ 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", "path": "active", "value": false}]}' -H 'Content-Type: application/scim+json'

Error Handling

By default, scimaenaga 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:

Scimaenaga.configure do |config|
  config.on_error = ->(e) { Honeybadger.notify(e) }
end

Schemas endpoint

If you need Schemas endpoint configure schemas. (Azure AD requires Schemas endpoint when registering to Application Gallery.)

You have to configure schemas as

• corresponding with other configurations. e.g.) When userName is defined in mutable_user_attributes, configure userName as mutability: 'readWrite'.

• corresponding with your model. e.g.) When userName must be specified configure userName as required: true

Sample config (with comment) is written in lib/generators/scimaenaga/templates/initializer.rb. For more details, read Schema Definition, and Schema Representation

Contributing

Code of Conduct

Pull Requests

Pull requests are welcome and encouraged! Please follow the default template format.

How to create 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

• Studist Corporation

License

The gem is available as open source under the terms of the MIT License.