Idsimple::Rack

Gem Version

Overview

Idsimple works with all Rack-based applications. This includes:

All you need is the idsimple-rack gem. idsimple-rack includes a Rack app, Idsimple::Rack::AuthenticatorApp, for authenticating users and initiating sessions and a Rack middleware, Idsimple::Rack::ValidatorMiddleware, for validating access tokens and sessions.

Installation

Add this line to your application's Gemfile:

gem "idsimple-rack"

And then execute:

bundle install

Or install it yourself as:

gem install idsimple-rack

Ruby on Rails

idsimple-rack hooks in to Rails automatically using Rails::Railtie. All you need to do is add an initializer with your configuration options:

# config/initializers/idsimple_rack.rb

Idsimple::Rack.configure do |config|
  config.app_id = ENV["IDSIMPLE_APP_ID"]
  config.api_key = ENV["IDSIMPLE_API_KEY"]
  config.signing_secret = ENV["IDSIMPLE_SIGNING_SECRET"]
end

Rack

To add idsimple-rack to a Rack application, you need to run Idsimple::Rack::AuthenticatorApp, at Idsimple::Rack.configuration.authenticate_path, use Idsimple::Rack::ValidatorMiddleware in your stack, and set your configuration options.

# config.ru

class Application
  def call(_)
    status  = 200
    headers = { "Content-Type" => "text/html" }
    body    = ["<html><body>yay!!!</body></html>"]

    [status, headers, body]
  end
end

Idsimple::Rack.configure do |config|
  config.app_id = ENV["IDSIMPLE_APP_ID"]
  config.api_key = ENV["IDSIMPLE_API_KEY"]
  config.signing_secret = ENV["IDSIMPLE_SIGNING_SECRET"]
end

App = Rack::Builder.new do
  use Rack::Reloader, 0

  map Idsimple::Rack.configuration.authenticate_path do
    run Idsimple::Rack::AuthenticatorApp
  end

  use Idsimple::Rack::ValidatorMiddleware

  run Application.new
end.to_app

run App

You can see a working example of this in the idsimple-rack repo.

Configuration

idsimple-rack can be configured by calling Idsimple::Rack.configure with a block like so:

Idsimple::Rack.configure do |config|
  config.app_id = ENV["IDSIMPLE_APP_ID"]
  config.api_key = ENV["IDSIMPLE_API_KEY"]
  config.signing_secret = ENV["IDSIMPLE_SIGNING_SECRET"]
end

Configuration Options

app_id

The idsimple App ID. This can be found in the "Keys & Secrets" tab for your app in idsimple.

  • Type: String
  • Optional: No

api_key

The idsimple App Session API Key. This is generated and shown when you create an idsimple app. You can view the prefix of the App Session API Key in the "Keys & Secrets" tab for your app in idsimple.

  • Type: String
  • Optional: No

signing_secret

The idsimple App signing secret. This is generated and shown when you create an idsimple app. You can view the prefix of the signing secret in the "Keys & Secrets" tab for your app in idsimple.

  • Type: String
  • Optional: No

get_access_token

Function for retrieving the access token from a store. By default, the access token is retrieved from an HTTP cookie.

  • Type: Lambda
  • Optional: Yes
  • Default: ruby -> (req) { req.cookies[DEFAULT_COOKIE_NAME] }

set_access_token

Function for setting the access token in a store. By default, the access token is stored in an HTTP cookie.

  • Type: Lambda
  • Optional: Yes
  • Default: ruby -> (req, res, access_token, decoded_access_token) { res.set_cookie(DEFAULT_COOKIE_NAME, { value: access_token, expires: Time.at(decoded_access_token[0]["exp"]), httponly: true, path: "/" }) }

remove_access_token

Function for removing the access token from a store.

  • Type: Lambda
  • Optional: Yes
  • Default: ruby -> (req, res) { res.delete_cookie(DEFAULT_COOKIE_NAME) }

authenticate_path

Path to initiate a new session with an access token. This is the location to which idsimple will redirect the user once a new access token is generated. Idsimple::Rack::AuthenticatorApp should be mounted at this path.

  • Type: String
  • Optional: Yes
  • Default: /idsimple/session

after_authenticated_path

Path to redirect the user after they've been authenticated.

  • Type: String
  • Optional: Yes
  • Default: /

skip_on

Function used to conditionally skip validation by the middleware. By returning true, Idsimple::Rack::ValidatorMiddleware will skip validation for that request.

  • Type: Lambda
  • Optional: Yes
  • Default: nil

Example:

-> (req) {
  req.path == "/webhooks"
}

logger

The logger option allows you to set your own custom logger.

  • Type: Logger
  • Optional: yes
  • Default: ruby logger = Logger.new(STDOUT) logger.level = Logger::INFO default_formatter = Logger::Formatter.new logger.formatter = proc do |severity, datetime, progname, msg| "Idsimple::Rack #{default_formatter.call(severity, datetime, progname, msg)}" end

enabled

Boolean indicating whether the idsimple middleware should be enabled.

  • Type: Boolean
  • Optional: true
  • Default: true

unauthorized_response

Function for customizing the unauthorized response sent by the middleware.

  • Type: Lambda
  • Optional: Yes
  • Default: ruby -> (req, res) { res.status = 401 res.content_type = "text/html" res.body = ["UNAUTHORIZED"] }

redirect_to_authenticate

Boolean indicating whether the middleware should redirect users to app.idsimple.io to authenticate. If set to false, unauthorized users will receive a 401 UNAUTHORIZED response when visiting your app instead of being redirected to app.idsimple.io.

  • Type: Boolean
  • Optional: Yes
  • Default: true

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/idsimple/idsimple-rack. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

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

Code of Conduct

Everyone interacting in the Idsimple::Rack project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.