Fridge

Token validation for distributed resource servers.

Installation

Add the following line to your application's Gemfile.

gem 'fridge'

And then run bundle install.

Usage

Configuration

Parameter	Description	Possible Values
`private_key`	Private token signing key	A PEM-formatted key
`public_key`	Public token verification key (the private key's complement)	A PEM-formatted key
`signing_algorithm`	Algorithm to use for sigining and verification	`RS512`, `RS256`
`validator`	A lambda used to perform custom validation of tokens	Any `Proc`

Resource servers must configure a public key corresponding to an authorization server, in order to verify tokens issued by that server. Authorization servers must configure a private key.

By default, public key-verified tokens are considered valid if and only iff they have not expired (i.e., expires_at > Time.now). However, some applications may want to perform additional validations. (For example, an authorization server may allow online revocation of tokens before their natural expiration, and need to check the current ). This is possible by configuring a custom validator:

Fridge.configure do |config|
  config.validator = lambda do |access_token|
    token = Token.find_by(id: access_token.id)
    token && !token.revoked?
  end
end

The validator will be called with a single argument, the Fridge::AccessToken instance.

Integrating with Fridge from a resource server

From any of your controllers, you may access the following methods:

current_token: The Fridge::AccessToken passed via Authorization header.
token_subject: The subject (:sub) of the current token.
token_scope: The scope (:scope) of the current token.
session_token: The Fridge::AccessToken stored in the user agent's cookies.
session_subject: The subject (:sub) of the current session token.

Integrating with Fridge from an authorization server

A Fridge access token may be constructed a la the following example:

access_token = Fridge::AccessToken.new(
  id: '0f1aa5ce-6e93-4812-b3fc-3b7f7b685991',
  subject: 'https://auth.aptible.com/users/e600a449-b308-4162-ac28-8a2769ad3f05',
  expires_at: 1.hour.from_now
)

The only required hash parameters are :subject and :expires_at. Additionally, you may specify :id, :scope and issuer. To set this token in a cookie that's readable across your entire domain, you may invoke the following command from any Rails controller:

store_session_cookie(access_token)

Contributing

Fork the project.
Commit your changes, with specs.
Ensure that your code passes specs (rake spec) and meets Aptible's Ruby style guide (rake rubocop).
Create a new pull request on GitHub.

Copyright and License

MIT License, see LICENSE for details.

aptible / fridge

readme