Monk ID Ruby

Integrate Monk ID authentication and single sign-on for apps and websites on the server-side.

• Documentation

Overview

Monk ID authentication and single sign-on works in the browser by integrating Monk ID JS. Only being able to check whether a user is logged in on the client-side is limiting, however, which is where this library is helpful. It takes a payload from the client-side JavaScript and decodes it for access in your Ruby code. There is no Monk ID API that can be accessed on the server-side, so this library depends on client-side integration.

Install

Add the gem to your Gemfile if using Bundler:

gem 'monk-id', '~> 1.0'

$ bundle

Or install manually:

$ gem install monk-id

Configure

Configuration is done in an external YAML file. There's a sample file in this repository: config/monk_id.sample.yml.

Rails and Sinatra apps need only copy this file to config/monk_id.yml for it to be loaded automatically.

All other apps need to load the file explicitly:

Monk::Id.load_config('/path/to/monk_id.yml', 'development')

Remember, replace the sample values with your own, and keep the file safe as it contains your app secret.

Access

If you have Monk ID JS configured to store the payload automatically in a cookie (the default), simply pass a hash-like cookies object to load the payload from:

Monk::Id.load_payload(cookies)

The encoded payload can also be passed directly, which is useful if you're sending it in a GET/POST request instead:

Monk::Id.load_payload(params[:monk_id_payload])

Loading the payload must be done before trying to access any values stored in the payload. In Rails, this usually means placing it in a before_action in your ApplicationController.

Once the payload is loaded, you can ask whether the user is logged in:

Monk::Id.logged_in?

Or for their ID and email:

Monk::Id.user_id
Monk::Id.user_email

nil is returned if the user isn't logged in or the payload can't be decoded and verified.

Development

Bundler is used heavily for development, so be sure to have it installed along with a version of Ruby.

Once those are installed and working, install the dependencies:

$ bundle

This requires all subsequent commands be prepended with bundle exec, which has been ommitted for conciseness going forward.

Rake is used for task running. The tests are run and code quality is checked by default:

$ rake

Tests

Testing is done with RSpec. To run the tests:

$ rake spec

SimpleCov automatically generates a code coverage report to the coverage directory on every run of the test suite.

Continuous integration is setup through Travis CI to run the tests against Ruby v2.3 and v2.4. (Circle CI is also setup to run the tests against Ruby v2.3, but is backup for now until multiple versions can easily be specified.) The code coverage results are sent to Codecov during CI for tracking over time. Badges for both are dispayed at the top of this README.

Manual

While the test suite is complete, it's not a bad idea to also test changes manually in real-world integrations.

With Bundler

Not to be confused with the fact that Bundler is used for development of this library, if Bundler is used in the test app or website, you can either specify a path to the library locally:

gem 'monk-id', path: '/path/to/monk-id-ruby'

Or configure Bundler to use a local repository instead of the GitHub repository (more details in the documentation):

gem 'monk-id', github: 'MonkDev/monk-id-ruby', branch: 'master'

$ bundle config local.monk-id /path/to/monk-id-ruby

Without Bundler

If Bundler is not used, you can either build and install the gem as a system gem (this must be done for every change):

$ rake install

require 'monk/id'

Or require the library directly:

require '/path/to/monk-id-ruby/lib/monk/id'

Documentation

YARD is used for code documentation. During development, you can preview as you document by starting the YARD server:

$ yard server --reload

This hosts the documentation at http://localhost:8808 and automatically watches for changes on page refresh.

The documentation can also be built to the doc directory (that is ignored by git):

$ yard

Quality

RuboCop is configured to enforce the Ruby Style Guide. To run:

$ rake quality

Code Climate is setup to perform continuous code quality inspection. The quality badge is displayed at the top of this README.

Deployment

gem-release is used to

1. bump the version in lib/monk/id/version.rb,
2. tag and push the release to GitHub,
3. and release to RubyGems.

These steps can be executed individually, but it's easiest to do all at once:

$ gem bump --version major|minor|patch --tag --release

Be sure to choose the correct version by following Semantic Versioning.

Publish Documentation

After releasing a new version, the documentation must be manually built and published to the gh-pages branch.