G5 Authenticatable API

A set of helpers for securing Rails or Grape APIs using G5 Auth.

The helpers can be used in conjunction with devise_g5_authenticatable to protect an API for a website, or they may be used to protect a stand-alone service using token-based authentication.

Current Version

1.0.0

Requirements

ruby >= 2.2

At least one of:

rails >= 4.1
grape

Installation

Add this line to your application's Gemfile:

   gem 'g5_authenticatable_api'

And then execute:

   bundle

Configuration

Auth endpoint

The API helpers need to know the endpoint for the G5 auth server to use when validating tokens. This may be configured in one of several ways:

Set the G5_AUTH_ENDPOINT environment variable (typically to either https://dev-auth.g5search.com or https://auth.g5search.com).

Configure the G5AuthenticationClient module directly, perhaps in an initializer:

  G5AuthenticationClient.configure do |config|
    config.endpoint = 'https://dev-auth.g5search.com'
  end

Strict token validation

If your API supports session-based authentication through devise_g5_authenticatable, then you have the option of toggling strict token validation.

If strict token validation is disabled (the default), then token validation will be bypassed if there is already an authenticated user in warden. This is fast, but it means that users with revoked or expired access tokens can still access your API as long as the local session remains active.

G5AuthenticatableApi.strict_token_validation = false

If strict token validation is enabled, then the session user's access token will be periodically re-validated. Access to your API will be limited to users with active access tokens, but there is a performance penalty for this level of security.

G5AuthenticatableApi.strict_token_validation = true

Usage

Rails

To require authentication for all API actions:

class MyResourceController < ApplicationController
  before_action :authenticate_api_user!

  respond_to :json

  # ...
end

To require authentication for some API actions:

class MyResourceController < ApplicationController
  before_action :authenticate_api_user!, only: [:create, :update]

  respond_to :json

  # ...
end

After authenticating an API user, you can retrieve the current token data as a G5AuthenticationClient::TokenInfo using the token_data helper:

class MyResourceController < ApplicationController
  before_action :authenticate_api_user!

  respond_to :json

  def index
    token_expiration = token_data.expires_in_seconds
    # ...
  end
end

You can retrieve the current user data using the current_api_user helper, which will attempt to retrieve the data from warden if possible. Otherwise it will return a G5AuthenticationClient::User:

class MyResourceController < ApplicationController
  before_action :authenticate_api_user!

  respond_to :json

  def index
    user = current_api_user
    # ...
  end
end

Finally, you can retrieve the value of the access token in use for this request by using the access_token helper:

class MyResourceController < ApplicationController
  before_action :authenticate_api_user!

  respond_to :json

  def index
    token = access_token
    # ...
  end
end

Grape

To require authentication for all endpoints exposed by your API:

class MyApi < Grape::API
  helpers G5AuthenticatableApi::Helpers::Grape

  before { authenticate_user! }

  # ...
end

To selectively require authentication for some endpoints but not others:

class MyApi < Grape::API
  helpers G5AuthenticatableApi::Helpers::Grape

  get :secure do
    authenticate_user!
    { secure: 'data' }
  end

  get :open do
    { hello: 'world' }
  end
end

After authenticating an API user, you can retrieve the current token data as a G5AuthenticationClient::TokenInfo using the token_data helper:

class MyApi < Grape::API
  helpers G5AuthenticatableApi::Helpers::Grape

  before { authenticate_user! }

  get :index do
    token_expiration = token_data.expires_in_seconds
    # ...
  end
end

You can retrieve the current user data using the current_user helper, which will attempt to retrieve the data from warden if possible. Otherwise it will return a G5AuthenticationClient::User:

class MyApi < Grape::API
  helpers G5AuthenticatableApi::Helpers::Grape

  before { authenticate_user! }

  get :index do
    user = current_user
    # ...
  end
end

You can retrieve the value of the access token in use for this request with the access_token helper:

class MyApi < Grape::API
  helpers G5AuthenticatableApi::Helpers::Grape

  before { authenticate_user! }

  get :index do
    token = access_token
    # ...
  end
end

Submitting a token

Authenticated requests follow the requirements described by OAuth 2.0 Bearer Token specification. If you are relying on token-based authentication for your API, there are three ways that an OAuth access token may be submitted as part of a request:

In the Authorization HTTP header, with the format "Bearer <access_token>"

  GET /resource HTTP/1.1
  Host: server.example.com
  Authorization: Bearer mF_9.B5f-4.1JqM

As the value of the access_token form-encoded body parameter:

  POST /resource HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded

  access_token=mF_9.B5f-4.1JqM

As the value of the access_token query URI parameter:

  GET /resource?access_token=mF_9.B5f-4.1JqM HTTP/1.1
  Host: server.example.com

Unauthorized response

If there is no logged in user and token authentication fails, secure API methods will return a response with an HTTP status of 401. More detailed information will be available in the WWW-Authenticate response header, as described in the OAuth 2.0 Bearer Token specification.

In brief, WWW-Authenticate header will contain one of the following error codes when token validation fails against G5 Auth:

invalid_request (the default)
invalid_token
insufficent_scope

The header may also have an error description if one is available. For example:

HTTP/1.1 401 Unauthorized
     WWW-Authenticate: Bearer realm="example",
                       error="invalid_token",
                       error_description="The access token expired"

Examples

Securing an Ember application backed by a Grape API

Use devise to protect the controller action that serves your ember application:

class WelcomeController < ApplicationController
  before_action :authenticate_user!

  def index
  end
end

Then protect the API that ember talks to:

class MyApi < Grape::API
  helpers G5AuthenticatableApi::Helpers::Grape

  before { authenticate_user! }

  # Your API endpoints ...
end

That's it! No client-side changes are necessary.

Token-based authentication for a Rails API

Protect your API actions in your controller:

class Api::MyResourcesController < ApplicationController
  before_action :authenticate_api_user!

  respond_to :json

  def show
    # ...
  end
end

To include the token in the authorization header:

curl --header "Authorization: Bearer this-is-where-my-token-goes" https://myhost/api/my_resources/42

To include the token as a param:

curl https://myhost/api/my_resources/42?access_token=this-is-where-my-token-goes

Authors

Maeve Revels / @maeve
Rob Revels / @sleverbor

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Write your code and specs
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

If you find bugs, have feature requests or questions, please file an issue.

Specs

Before running the specs for the first time, you will need to initialize the database for the test Rails application.

$ cp spec/dummy/config/database.yml.sample spec/dummy/config/database.yml
$ (cd spec/dummy; RAILS_ENV=test bundle exec rake db:setup)

To execute the entire test suite:

$ bundle exec rspec spec

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.