README.md
# ApiAuthenticator
[](https://codeclimate.com/github/Spokeo/api_authenticator)
[](https://travis-ci.org/Spokeo/api_authenticator)
This gem will authenticate API requests using a slightly modified version HMAC-SHA1
## Installation
Add this line to your application's Gemfile:
gem 'api_authenticator'
And then execute:
$ bundle
Or install it yourself as:
$ gem install api_authenticator
## Authentication
This gem assumes headers being pass into the request.
The two headers are:
- API-Time
- API-Token
### API-Time
The API-Time is a String UTC representation of the current time of request.
For example:
```ruby
=> "2014-10-16 18:55:48 UTC"
```
### API-Token
The token passed in is a SHA256 of the time AND the request URL. The shared_secret_key is used as the encyrption key.
```ruby
digest = OpenSSL::Digest.new('sha256')
env['API-Token'] = OpenSSL::HMAC.hexdigest(digest, shared_secret_key, "#{DateTime.now.new_offset(0)}#{request.original_url}")
```
## Configuration
```ruby
ApiAuthenticator.configure do |config|
config.shared_secret_keys = ["my_shared_token", "my_shared_token2"]
config.time_threshold = 2.hours
config.request_type = :path # :url by default if nothing is set
config.logger = Rails.logger
config.report_unauthenticated_requests = true
end
```
- shared_secret_keys: An Array of approved shared secret keys between the client and the server.
- time_threshold: The time threshold to allow requests. So for example the entry above will only allow requests from 2 hours before now and 2 hours in the future.
- request_type: 2 options: :url or :path. By default it's :url which uses the full URL has as the hashing mechanism. :path only uses the path for the hashing mechanism.
- logger: Your logger
- report_unauthenticated_requests: will throw some basic information into your logger.warn.
## Usage
There is a before_filter that is included in the gem. If not authenticated it will automatically render a status 401.
```ruby
class ApiController
include ApiAuthenticator
before_filter :api_authenticator
end
```
Or you can use it without the before_filter.
Note here is that right now, if the request is not authenticated the gem with throw an exception. All exceptions inherit from ApiAuthentiactor::BaseError
```ruby
class ApiController
def people
# Takes a Rails request object
begin
ApiAuthentiactor.authenticated_request?(request)
rescue ApiAuthenticator::InvalidTimeError => e
logger.error(e)
rescue ApiAuthenticator::InvalidTokenError => e
logger.error(e)
end
end
end
```
## TODO:
- Set time intervals instead of explicity passing in the time.
## Running The Specs
Just run rake:
```
rake
```
## Upggrading from 0.1.0 to 0.2.0
The big change here is ApiAuthenticator now takes a list of shared secret keys. So where there was
```ruby
ApiAuthenticator.shared_secret_key = 'key1'
```
it now takes an array
```ruby
ApiAuthenticator.shared_secret_keys = ['key1', 'key2']
```
## Contributing
1. Fork it ( https://github.com/[my-github-username]/api_authenticator/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