What is Rack::SimpleAuth

Rack::SimpleAuth will contain different Authentication Class Middlewares

Until now only HMAC is implemented…


Add this line to your application's Gemfile:

$ gem 'rack-simple_auth'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rack-simple_auth

Gem Status

Build Status Coverage Status Gem Version Dependency
Status Build Status



To use HMAC Authorization you have to use the Rack::SimpleAuth::HMAC::Middleware for your Rack App

Basic Usage:

require 'rack/lobster'
require 'rack/simple_auth'

request_config = {
  'GET' => 'path',
  'POST' => 'params',
  'DELETE' => 'path',
  'PUT' => 'path',
  'PATCH' => 'path'

use Rack::SimpleAuth::HMAC::Middleware do |options|
  options.tolerance = 1500 # 1500ms -> 1.5s

  options.secret = 'test_secret'
  options.signature = 'test_signature'

  options.logpath = "#{File.expand_path('..', __FILE__)}/logs"
  options.request_config = request_config

run Rack::Lobster.new

In general each request has a message (which is encrypted) in following format:

{ 'method' => @request.request_method, 'date' => date, 'data' => request_data }.to_json

For example accessing GET /test with this configuration represents following message

{ 'method' => 'GET', 'date' => 1398821451494, 'data' => '/test' }.to_json

With the tolerance there is an adjustable amount of messages wich are built (Rack::SimpleAuth::HMAC::Middleware#allowed_messages)

This means a request could have a certain latency (delay) and the request is still authorized

Secure your REST Api:

To secure your REST Api you have to send the HTTP_AUTHORIZATION Header with each request where the HMAC Middleware is used.

For example POST /form with params { name => benny1992 } is secured the following way:

Uncrypted Message:

{ 'method' => 'POST', 'date' => timestamp +- tolerance, 'data' => { 'name' => 'benny1992' } }.to_json

Encryption Mechanism:

OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), @config.secret, message(date, i))

where @config.secret represents your secret which was set in the middleware dsl block and message represents the uncrypted message for the specific timestamp(date) and delay(i)

Therefore you need following encryption mechanism on the client side (pseudocode):
encrypted_message = OpenSSL::HMAC.hexdigest(OpenSSL:Digest.new('sha256'), 'test_secret', message)

HTTP_AUTHORIZATION = encrypted_message:'test_signature'
Time formats

The timestamp and tolerance are in millisecond format:

In Ruby land this means:

(Time.now.to_f * 1000).to_i

For PHP you have to use round() and microtime() :

round(microtime(true) * 1000)
General your timestamp should only contain 13 digits and NO floating part


Examples can be found in examples dir


  1. Fork it ( github.com/benny1992/rack-simple_auth/fork )

  2. Create your feature branch (`git checkout -b my-new-feature`)

  3. Commit your changes (`git commit -am 'Add some feature'`)

  4. Push to the branch (`git push origin my-new-feature`)

  5. Create new Pull Request