JWT::Rack

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

• Ruby 2.3.8 or greater

Add this line to your application's Gemfile:

gem 'jwt-rack'

And then execute:

$ bundle install

Or install it directly with:

$ gem install jwt-rack

JWT::Rack::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 more information of the algorithms and their requirements as well as more information on the supported claims. 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.

• on_error : optional : Callable : An object which responds to call method with single error parameter. error parameter is one of JWT::Rack::Auth::ERRORS_TO_RESCUE. on_error callable object will be called if one of JWT::Rack::Auth::ERRORS_TO_RESCUE raised. For default handler check JWT::Rack::Auth#default_on_error.

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.

use JWT::Rack::Auth, my_args

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

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

You can generate JSON Web Tokens for your users using the JWT::Rack::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 ED25519 ES256 ES384 ES512)

HS256 is the default

Note that ED25519 support depends on the rbnacl which is not already included by the rack-jwt gem. If you wish to use the ED25519 algorith, you must also manually require rbnacl gem in addition to rack-jwt.

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'

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

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