simple-api-auth

This gem provides a very basic token based authentication to use for API. This is meant to be used as a lightweight authentication solution when OAuth2 is too much.

Installation

Add this line to your application's Gemfile:

gem 'simple-api-auth'

And then execute:

$ bundle

Or install it yourself as:

$ gem install simple-api-auth

Usage

This gem works out of the box with ActiveRecord and can be used stand alone with a little more work.

ActiveRecord usage

Just include acts_as_api_authenticable in your model.

class User < ActiveRecord::Base
  acts_as_api_authenticable
end

you will need to have saa_key and saa_secret defined as strings in your database for this to work. If you want to change the columns name, you can pass them in option.

class User < ActiveRecord::Base
  acts_as_api_authenticable saa_key: :resource_key_field, saa_secret: :secret_token
end

If you want the keys to be generated when you create a new instance of the model, you can pass :auto_generate with either true, or the field you want to generate.

class User < ActiveRecord::Base
  # this will generate a after_initialize to assign `saa_key`
  acts_as_api_authenticable auto_generate: :saa_key
  # this will generate a after_initialize for both `saa_key` and `saa_secret`
  # not that this will only work for new records
  acts_as_api_authenticable auto_generate: true
end

Note that the keys for autogenerate should be :saa_key and :saa_secret even if you change the key column name.

You can then use

User.authenticate(request)

this will return the user if the request is valid, or nil otherwise.

Standalone usage

This gem can easily used without ActiveRecord.

saa_key = SimpleApiAuth.extract_key(request)
secret_key = your_logic_to_get_secret_key(saa_key)
valid = SimpleApiAuth.valid_signature?(request, secret_key)

Configuration

The library accepts the following configurations

SimpleApiAuth.configure do |config|
    # class used to transform headers key to :underscored_symbols and back
    # the provided normalizer works for Rack requests
    # override for other types of requests
    request_normalizer = SimpleApiAuth::Helpers::RequestNormalizer

    # values used as default with `acts_as_api_authenticable`
    config.model_defaults = { saa_key: :saa_key, saa_secret: :saa_secret, auto_generate: false }

    # the normalized keys for the HTTP headers
    config.header_keys = { key: :x_saa_key, time: :x_saa_auth_time, authorization: :authorization
      }

    # the methods name for the HTTP request used
    config.request_fields = {
      headers: :headers,
      http_verb: :method,
      uri: :path,
      query_string: :query_string,
      body: :body
    }

    # the allowed HTTP methods
    config.allowed_methods = [:get, :post, :put, :patch, :delete]

    # the required headers for the HTTP request
    config.required_headers = config.header_keys.values

    # the class to use to hash requests
    # it must contain a `hmac` and a `hash` method
    config.hasher = SimpleApiAuth::Hasher::SHA1

    # the class to use to sign requests
    # it must contain a `sign` method
    config.signer = SimpleApiAuth::Signer
    config.request_timeout = 5
    config.logger = nil
end

Supported frameworks

This library should be configurable enough to work with more or less any framework. It will work out of the box for Rails, and will just need a little setup to work with request objects with a different API.

For example, to work with Sinatra request, the following can be passed

SimpleApiAuth.configure do |config|
  config.request_fields.merge! {
    headers: :env,
    http_verb: :request_method,
    uri: :path_info
  }
end

Note that body should return something with a read method, and query_string should contain the URI encoded query string.

Clients

This library can also be used as a client. You can compute the request signature with

signature = SimpleApiAuth.compute_signature(request, secret_key)

or directly sign the request with

SimpleApiAuth.sign!(request, secret_key)

With ActiveRecord, it can also be used the following way.

my_model.saa_sign!(request)

A JS client, with an AngularJS module intregrated with the $http service is in progress and should be available soon (with a few weeks).

Contributions are very welcome for other clients.

Contributing

1. Fork it ( https://github.com/claudetech/simple-api-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 a new Pull Request