Monk ID Ruby
Integrate Monk ID authentication and single sign-on for apps and websites on the server-side.
Add the gem to your
Gemfile if using Bundler:
gem 'monk-id', '~> 1.0'
Or install manually:
$ gem install monk-id
Configuration is done in an external YAML file. There's a sample file in this
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:
Remember, replace the sample values with your own, and keep the file safe as it contains your app secret.
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:
The encoded payload can also be passed directly, which is useful if you're sending it in a GET/POST request instead:
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
Once the payload is loaded, you can ask whether the user is signed in:
Or for their ID and email:
nil is returned if the user isn't signed in or the payload can't be decoded
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 development dependencies:
This requires all subsequent commands be prepended with
bundle exec, which has
been ommitted for conciseness going forward.
Rake is setup to run the tests and check code quality by default:
Guard takes it a step further and automatically runs the appropriate tasks on file change:
It's recommended to run Guard during development.
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 v1.9.3, v2.0, v2.1, and v2.2. (Circle CI is also setup to run the tests against Ruby v1.9.3, but is backup for now until multiple versions can easily be specified.) The SimpleCov results are sent to Coveralls during CI for tracking over time. Badges for both are dispayed at the top of this README.
While the test suite is complete, it's not a bad idea to also test changes manually in real-world integrations.
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
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
Or require the library directly:
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
$ rake quality
Code Climate is setup to perform continuous code quality inspection. The quality badge is displayed at the top of this README.
gem-release is used to
- bump the version in
- tag and push the release to GitHub,
- 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.
After releasing a new version, the documentation must be manually built and
published to the