No commit activity in last 3 years
No release in over 3 years
There's a lot of open issues
Ruby implementation of the JSON Web Token (JWT) standard, RFC 7519
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.15
~> 12.0
~> 3.6
~> 0.14
~> 1.3
~> 0.9

Runtime

~> 2.1
 Project Readme

JSON Web Token travis yard docs code climate

A JSON Web Token (JWT) implementation for Ruby

Description

A Ruby implementation of the JSON Web Token standard RFC 7519

Installation

gem install json_web_token

Philosophy & Design Goals

  • Minimal API surface area
  • Clear separation and conformance to underlying standards
    • JSON Web Signature (JWS) Standards Track RFC 7515
    • JSON Web Algorithms (JWA) Standards Track RFC 7518
  • Thorough test coverage
  • Modularity for comprehension and extensibility
  • Fail fast and hard, with maximally strict validation
  • Implement only the REQUIRED elements of the JWT standard (initially)

Intended Audience

Token authentication of API requests to Rails via these prominent gems:

Secure Cross-Origin Resource Sharing (CORS) using the rack-cors gem

Support for JWT Registered Claims

Support for the standard registered claims documented in RFC 7519 can be found in the companion gem jwt_claims.

jwt_claims is a wrapper around json_web_token and provides support for the full set of registered claims.

https://github.com/garyf/jwt_claims

Usage

JsonWebToken.sign(claims, options)

Returns a JSON Web Token string

claims (required) string or hash

options (required) hash

  • alg (optional, default: HS256)
  • key (required unless alg is 'none')

Example

require 'json_web_token'

# Sign with the default algorithm, HMAC SHA256
jwt = JsonWebToken.sign({foo: 'bar'}, key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C')
#=> "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmb28iOiJiYXIifQ.vpaYTGkypBmxDi3KZYcvpqLx9xqhRD-DSXONGrUbf5Q"

# Sign with RSA SHA256 algorithm
opts = {
  alg: 'RSA256',
  key: < RSA private key >
}

jwt = JsonWebToken.sign({foo: 'bar'}, opts)

# Create an unsecured token (algorithm is 'none')
jwt = JsonWebToken.sign({foo: 'bar'}, alg: 'none')

JsonWebToken.verify(jwt, options)

Returns a hash:

  • {ok: < JWT claims set >}, if the Message Authentication Code (MAC), or signature, is verified
  • {error: 'invalid'}, otherwise

jwt (required) is a JSON web token string

options (required) hash

  • alg (optional, default: HS256)
  • key (required unless alg is 'none')

Example

require 'json_web_token'

jwt = JsonWebToken.sign({foo: 'bar'}, key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C')
#=> "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmb28iOiJiYXIifQ.vpaYTGkypBmxDi3KZYcvpqLx9xqhRD-DSXONGrUbf5Q"

# Verify with default algorithm, HMAC SHA256
# Returns a hash of `{:ok, verified_claims}`
JsonWebToken.verify(jwt, key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C')
#=> {:ok=>{:foo=>"bar"}}

# verify with RSA SHA256 algorithm
opts = {
  alg: 'RSA256',
  key: < RSA public key >
}

{ok: claims} = JsonWebToken.verify(jwt, opts)

# Unsecured token (algorithm is 'none')
jwt = JsonWebToken.sign({foo: 'bar'}, alg: 'none')
#=> "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJmb28iOiJiYXIifQ."

JsonWebToken.verify(jwt, alg: 'none')
#=> {:ok=>{:foo=>"bar"}}

Supported encryption algorithms

alg Param Value Digital Signature or MAC Algorithm
HS256 HMAC using SHA-256 per RFC 2104
HS384 HMAC using SHA-384
HS512 HMAC using SHA-512
RS256 RSASSA-PKCS-v1_5 using SHA-256 per RFC3447
RS384 RSASSA-PKCS-v1_5 using SHA-384
RS512 RSASSA-PKCS-v1_5 using SHA-512
ES256 ECDSA using P-256 and SHA-256 per DSS
ES384 ECDSA using P-384 and SHA-384
ES512 ECDSA using P-521 and SHA-512
none No digital signature or MAC performed (unsecured)

Supported Ruby Versions

Ruby 2.2 and up

Limitations

Future implementation may include these features:

  • processing of OPTIONAL JWT registered claim names (e.g. 'exp')
  • representation of a JWT as a JSON Web Encryption (JWE) RFC 7516
  • OPTIONAL nested JWTs