Idsimple::Rack

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

You can find a simple Rails demo here.

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:

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

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

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

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:

-> (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.

idsimple-rack

Runtime

Idsimple::Rack

Overview

Installation

Ruby on Rails

Rack

Configuration

Configuration Options

app_id

api_key

signing_secret

get_access_token

set_access_token

remove_access_token

authenticate_path

after_authenticated_path

skip_on

logger

enabled

unauthorized_response

redirect_to_authenticate