Gris::TokoOhno

Gris::TokoOhno is a simple helper providing token authentication via headers or params in your Gris app's Grape endpoints.

Conveniently, Gris::TokoOhno is tied to Gris.secrets so that you can ensure that requests match values set in your ENV.

---

Installation

Gris::TokoOhno is available as a gem on rubygems, to install it run:

gem install gris-toko_ohno

Otherwise, if your project uses Bundler, add gris-toko_ohno to your Gemfile:

gem 'gris-toko_ohno'

And run:

$ bundle install

---

Usage

Once you have installed or bundled gris-toko_ohno with your Gris app, using it is a two-step process. You must set the Gris.secrets for your permitted tokens as environment variables and then add the token_authenticate! helper in your endpoints.

Set the ENV value

By default, Gris::TokoOhno will verify inbound requests against values set in Gris.secrets.permitted_tokens. To set a value for permitted_tokens, simply add it to your Gris config/secrets.yml file.

default: &default
  service_name: my_secure_service
  permitted_tokens: <%= ENV['PERMITTED_TOKENS'] %>
  base_url: <%= ENV['BASE_URL'] || 'http://localhost:9292' %>

The value set in your environment should be a string and may be separated by comma(s).

You can also use custom secret names (if you wanted to provide multiple checks with different tokens over different endpoints, for example) by simply defining a different secret value.

default: &default
  service_name: my_secure_service
  other_tokens: <%= ENV['OTHER_TOKENS'] %>
  base_url: <%= ENV['BASE_URL'] || 'http://localhost:9292' %>

You would then have to specify the custom secret when you call token_authenticate! per the instructions below.

Add token_authenticate! to your endpoints

To authenticate a particular endpoint:

class ApplicationEndpoint < Grape::API
  # Authenticated
  get do
    token_authentication!
    present self, with: RootPresenter
  end

  # Not authenticated
  get '/hello' do
    present self, with: RootPresenter
  end
end

You can also authenticate all endpoints in an API using Grape helpers.

class ApplicationEndpoint < Grape::API
  before do
    token_authentication!
  end

  # Authenticated
  get do
    present self, with: RootPresenter
  end

  # Authenticated
  get '/hello' do
    present self, with: RootPresenter
  end
end

The helper will check against Gris.secrets.permitted_tokens by default, but you can also choose to specify a custom Gris.secrets value.

To verify that a request provides token or header credentials that match Gris.secrets.other_tokens (for example):

class ApplicationEndpoint < Grape::API
  get do
    token_authentication! :other_tokens
    present self, with: RootPresenter
  end
end

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/dylanfareed/gris-toko_ohno. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Context