hookercookerman / rack-jwt

Rack middleware that provides authentication based on JSON Web Tokens

Rack::JWT

About

This gem provides JSON Web Token (JWT) based authentication.

Requirements

• Ruby 2.3.8 or greater

Installation

Add this line to your application's Gemfile:

gem 'rack-jwt'

And then execute:

$ bundle install

Or install it directly with:

$ gem install rack-jwt

Usage

Rack::JWT::Auth accepts several configuration options. All options are passed in a single Ruby Hash:

• secret : required : String || OpenSSL::PKey::RSA || OpenSSL::PKey::EC : A cryptographically secure String (for HMAC algorithms) or a public key object of an appropriate type for public key algorithms. Set to nil if you are using the 'none' algorithm.

• verify : optional : Boolean : Determines whether JWT will verify tokens keys for mismatch key types when decoded. Default is true. Set to false if you are using the 'none' algorithm.

• options : optional : Hash : A hash of options that are passed through to JWT to configure supported claims and algorithms. See the ruby-jwt docs for much more info on the available options and how they work. These options are passed through without change to the underlying ruby-jwt gem. By default only expiration (exp) and Not Before (nbf) claims are verified. Pass in an algorithm choice like { algorithm: 'HS256' }.

• exclude : optional : Array : An Array of path strings representing paths that should not be checked for the presence of a valid JWT token. Excludes sub-paths as of specified paths as well (e.g. %w(/docs) excludes /docs/some/thing.html also). Each path should start with a /. If a path matches the current request path this entire middleware is skipped and no authentication or verification of tokens takes place.

Example Server-Side Config

Where my_args is a Hash containing valid keys. See spec/example_spec.rb for a more complete example of the valid arguments for creating and verifying tokens.

Sinatra

use Rack::JWT::Auth, my_args

Cuba

Cuba.use Rack::JWT::Auth, my_args

Rails

Rails.application.config.middleware.use Rack::JWT::Auth, my_args

Generating tokens

You can generate JSON Web Tokens for your users using the Rack::JWT::Token#encode method which takes payload, secret, and algorithm params.

The secret will be either a cryptographically strong random string, or the secret key component of a public/private keypair of an accepted type depending on the algorithm you choose. You can see examples of using the various key types at the ruby-jwt gem repo

The algorithm is an optional String and can be one of the following (default HMAC 'HS256'):

%w(none HS256 HS384 HS512 RS256 RS384 RS512 ES256 ES384 ES512)

HS256 is the default

Here is a sample payload with illustrative data. You don't have to use all, or even most, of these.

secret = 'your_secret_token_or_key'

my_payload = {
  data: 'data',
  exp: Time.now.to_i + 4 * 3600,
  nbf: Time.now.to_i - 3600,
  iss: 'https://my.awesome.website/',
  aud: 'audience',
  jti: Digest::MD5.hexdigest([hmac_secret, iat].join(':').to_s),
  iat: Time.now.to_i,
  sub: 'subject'
}

alg = 'HS256'

Rack::JWT::Token.encode(my_payload, secret, alg)

Contributing

1. Fork it ( https://github.com/eparreno/rack-jwt/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