Sponsors

Installing

Using Rubygems

gem install jwt

Using Bundler

gem'jwt'

require'jwt'

Algorithms and Usage

NONE

payload={data:'test'}token=JWT.encode(payload,nil,'none')# => "eyJhbGciOiJub25lIn0.eyJkYXRhIjoidGVzdCJ9."decoded_token=JWT.decode(token,nil,true,{algorithm:'none'})#  => [#       {"data"=>"test"}, # payload#       {"alg"=>"none"} # header#     ]

HMAC

payload={data:'test'}hmac_secret='my$ecretK3y'token=JWT.encode(payload,hmac_secret,'HS256')# => "eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.pNIWIL34Jo13LViZAJACzK6Yf0qnvT_BuwOxiMCPE-Y"decoded_token=JWT.decode(token,hmac_secret,true,{algorithm:'HS256'})# => [#      {"data"=>"test"}, # payload#      {"alg"=>"HS256"} # header#    ]

RSA

payload={data:'test'}rsa_private=OpenSSL::PKey::RSA.generate(2048)rsa_public=rsa_private.public_keytoken=JWT.encode(payload,rsa_private,'RS256')# => "eyJhbGciOiJSUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.CCkO35qFPijW8Gwhbt8a80PB9fc9FJ19hCMnXSgoDF6Mlvlt0A4G-ah..."decoded_token=JWT.decode(token,rsa_public,true,{algorithm:'RS256'})# => [#      {"data"=>"test"}, # payload#      {"alg"=>"RS256"} # header#    ]

ECDSA

payload={data:'test'}ecdsa_key=OpenSSL::PKey::EC.generate('prime256v1')token=JWT.encode(payload,ecdsa_key,'ES256')# => "eyJhbGciOiJFUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.AlLW--kaF7EX1NMX9WJRuIW8NeRJbn2BLXHns7Q5TZr7Hy3lF6MOpMlp7GoxBFRLISQ6KrD0CJOrR8aogEsPeg"decoded_token=JWT.decode(token,ecdsa_key,true,{algorithm:'ES256'})# => [#      {"test"=>"data"}, # payload#      {"alg"=>"ES256"} # header#    ]

EdDSA

RSASSA-PSS

payload={data:'test'}rsa_private=OpenSSL::PKey::RSA.generate(2048)rsa_public=rsa_private.public_keytoken=JWT.encode(payload,rsa_private,'PS256')# => "eyJhbGciOiJQUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.BRWizdUjD5zAWw-EDBcrl3dDpQDAePz9Ol3XKC43SggU47G8OWwveA_..."decoded_token=JWT.decode(token,rsa_public,true,{algorithm:'PS256'})# => [#      {"data"=>"test"}, # payload#      {"alg"=>"PS256"} # header#    ]

Custom algorithms

moduleCustomHS512AlgorithmextendJWT::JWA::SigningAlgorithmdefself.alg'HS512'enddefself.sign(data:,signing_key:)OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha512'),signing_key,data)enddefself.verify(data:,signature:,verification_key:)    ::OpenSSL.secure_compare(sign(data:data,signing_key:verification_key),signature)endendpayload={data:'test'}token=JWT.encode(payload,'secret',CustomHS512Algorithm)# => "eyJhbGciOiJIUzUxMiJ9.eyJkYXRhIjoidGVzdCJ9.aBNoejLEM2WMF3TxzRDKlehYdG2ATvFpGNauTI4GSD2VJseS_sC8covrVMlgslf0aJM4SKb3EIeORJBFPtZ33w"decoded_token=JWT.decode(token,'secret',true,algorithm:CustomHS512Algorithm)# => [#      {"data"=>"test"}, # payload#      {"alg"=>"HS512"} # header#    ]

Add custom header fields

payload={data:'test'}token=JWT.encode(payload,nil,'none',{typ:'JWT'})# => "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJkYXRhIjoidGVzdCJ9."decoded_token=JWT.decode(token,nil,true,{algorithm:'none'})#  => [#       {"data"=>"test"}, # payload#       {"typ"=>"JWT", "alg"=>"none"} # header#     ]

JWT::Token andJWT::EncodedToken

Signing and encoding a token

payload={exp:Time.now.to_i +60,jti:'1234',sub:"my-subject"}header={kid:'hmac'}token=JWT::Token.new(payload:payload,header:header)token.sign!(algorithm:'HS256',key:"secret")token.jwt# => "eyJraWQiOiJobWFjIiwiYWxnIjoiSFMyNTYifQ.eyJleHAiOjE3NTAwMDU0NzksImp0aSI6IjEyMzQiLCJzdWIiOiJteS1zdWJqZWN0In0.NRLcK6fYr3IdNfmncJePMWLQ34M4n14EgqSYrQIjL9w"

Verifying and decoding a token

encoded_token=JWT::EncodedToken.new(token.jwt)encoded_token.verify_signature!(algorithm:'HS256',key:"secret")encoded_token.verify_signature!(algorithm:'HS256',key:"wrong_secret")# raises JWT::VerificationErrorencoded_token.verify_claims!(:exp,:jti)encoded_token.verify_claims!(sub:["not-my-subject"])# raises JWT::InvalidSubErrorencoded_token.claim_errors(sub:["not-my-subject"]).map(&:message)# => ["Invalid subject. Expected [\"not-my-subject\"], received my-subject"]encoded_token.payload# => { 'exp'=>1234, 'jti'=>'1234", 'sub'=>'my-subject' }encoded_token.header# {'kid'=>'hmac', 'alg'=>'HS256'}

encoded_token=JWT::EncodedToken.new(token.jwt)encoded_token.verify!(signature:{algorithm:'HS256',key:"secret"})encoded_token.payload# => { 'exp'=>1234, 'jti'=>'1234", 'sub'=>'my-subject' }encoded_token.header# {'kid'=>'hmac', 'alg'=>'HS256'}

jwk_json='{ "kty": "oct", "k": "c2VjcmV0", "alg": "HS256", "kid": "hmac"}'jwk=JWT::JWK.import(JSON.parse(jwk_json))token=JWT::Token.new(payload:payload,header:header)token.sign!(key:jwk,algorithm:'HS256')encoded_token=JWT::EncodedToken.new(token.jwt)encoded_token.verify!(signature:{algorithm:["HS256","HS512"],key:jwk})

Using a keyfinder

# Create and sign a tokenjwk=JWT::JWK.new(OpenSSL::PKey::RSA.generate(2048))token=JWT::Token.new(payload:{pay:'load'},header:{kid:jwk.kid})token.sign!(algorithm:'RS256',key:jwk.signing_key)# Create keyfinder object, verify and decode tokenkey_finder=JWT::JWK::KeyFinder.new(jwks:JWT::JWK::Set.new(jwk))encoded_token=JWT::EncodedToken.new(token.jwt)encoded_token.verify!(signature:{algorithm:'RS256',key_finder:key_finder})encoded_token.payload# => { 'pay' => 'load' }

# Create and sign a tokenkey=OpenSSL::PKey::RSA.generate(2048)token=JWT::Token.new(payload:{pay:'load'})token.sign!(algorithm:'RS256',key:key)# Verify and decode tokenencoded_token=JWT::EncodedToken.new(token.jwt)encoded_token.verify!(signature:{algorithm:'RS256',key_finder:->(_token){key.public_key}})encoded_token.payload# => { 'pay' => 'load' }

Detached payload

token=JWT::Token.new(payload:{pay:'load'})token.sign!(algorithm:'HS256',key:"secret")token.detach_payload!token.jwt# => "eyJhbGciOiJIUzI1NiJ9..UEhDY1Qlj29ammxuVRA_-gBah4qTy5FngIWg0yEAlC0"token.encoded_payload# => "eyJwYXkiOiJsb2FkIn0"

encoded_token=JWT::EncodedToken.new(token.jwt)encoded_token.encoded_payload="eyJwYXkiOiJsb2FkIn0"encoded_token.verify_signature!(algorithm:'HS256',key:"secret")encoded_token.payload# => {"pay"=>"load"}

Claims

Expiration Time Claim

exp=Time.now.to_i +4 *3600exp_payload={data:'data',exp:exp}token=JWT.encode(exp_payload,hmac_secret,'HS256')begindecoded_token=JWT.decode(token,hmac_secret,true,{algorithm:'HS256'})rescueJWT::ExpiredSignature# Handle expired token, e.g. logout user or deny accessend

# Decode token without raising JWT::ExpiredSignature errorJWT.decode(token,hmac_secret,true,{verify_expiration:false,algorithm:'HS256'})

exp=Time.now.to_i -10leeway=30# secondsexp_payload={data:'data',exp:exp}# build expired tokentoken=JWT.encode(exp_payload,hmac_secret,'HS256')begin# add leeway to ensure the token is still accepteddecoded_token=JWT.decode(token,hmac_secret,true,{exp_leeway:leeway,algorithm:'HS256'})rescueJWT::ExpiredSignature# Handle expired token, e.g. logout user or deny accessend

Not Before Time Claim

nbf=Time.now.to_i -3600nbf_payload={data:'data',nbf:nbf}token=JWT.encode(nbf_payload,hmac_secret,'HS256')begindecoded_token=JWT.decode(token,hmac_secret,true,{algorithm:'HS256'})rescueJWT::ImmatureSignature# Handle invalid token, e.g. logout user or deny accessend

# Decode token without raising JWT::ImmatureSignature errorJWT.decode(token,hmac_secret,true,{verify_not_before:false,algorithm:'HS256'})

nbf=Time.now.to_i +10leeway=30nbf_payload={data:'data',nbf:nbf}# build expired tokentoken=JWT.encode(nbf_payload,hmac_secret,'HS256')begin# add leeway to ensure the token is validdecoded_token=JWT.decode(token,hmac_secret,true,{nbf_leeway:leeway,algorithm:'HS256'})rescueJWT::ImmatureSignature# Handle invalid token, e.g. logout user or deny accessend

Issuer Claim

iss='My Awesome Company Inc. or https://my.awesome.website/'iss_payload={data:'data',iss:iss}token=JWT.encode(iss_payload,hmac_secret,'HS256')begin# Add iss to the validation to check if the token has been manipulateddecoded_token=JWT.decode(token,hmac_secret,true,{iss:iss,verify_iss:true,algorithm:'HS256'})rescueJWT::InvalidIssuerError# Handle invalid token, e.g. logout user or deny accessend

JWT.decode(token,hmac_secret,true,iss:%r'https://my.awesome.website/',verify_iss:true,algorithm:'HS256')

JWT.decode(token,hmac_secret,true,iss:->(issuer){issuer.start_with?('My Awesome Company Inc')},verify_iss:true,algorithm:'HS256')

JWT.decode(token,hmac_secret,true,iss:method(:valid_issuer?),verify_iss:true,algorithm:'HS256')# somewhere in the same class:defvalid_issuer?(issuer)# custom validationend

Audience Claim

aud=['Young','Old']aud_payload={data:'data',aud:aud}token=JWT.encode(aud_payload,hmac_secret,'HS256')begin# Add aud to the validation to check if the token has been manipulateddecoded_token=JWT.decode(token,hmac_secret,true,{aud:aud,verify_aud:true,algorithm:'HS256'})rescueJWT::InvalidAudError# Handle invalid token, e.g. logout user or deny accessputs'Audience Error'end

JWT ID Claim

# Use the secret and iat to create a unique key per request to prevent replay attacksjti_raw=[hmac_secret,iat].join(':').to_sjti=Digest::MD5.hexdigest(jti_raw)jti_payload={data:'data',iat:iat,jti:jti}token=JWT.encode(jti_payload,hmac_secret,'HS256')begin# If :verify_jti is true, validation will pass if a JTI is present#decoded_token = JWT.decode(token, hmac_secret, true, { verify_jti: true, algorithm: 'HS256' })# Alternatively, pass a proc with your own code to check if the JTI has already been useddecoded_token=JWT.decode(token,hmac_secret,true,{verify_jti:proc{ |jti|my_validation_method(jti)},algorithm:'HS256'})# ordecoded_token=JWT.decode(token,hmac_secret,true,{verify_jti:proc{ |jti,payload|my_validation_method(jti,payload)},algorithm:'HS256'})rescueJWT::InvalidJtiError# Handle invalid token, e.g. logout user or deny accessputs'Error'end

Issued At Claim

iat=Time.now.to_iiat_payload={data:'data',iat:iat}token=JWT.encode(iat_payload,hmac_secret,'HS256')begin# Add iat to the validation to check if the token has been manipulateddecoded_token=JWT.decode(token,hmac_secret,true,{verify_iat:true,algorithm:'HS256'})rescueJWT::InvalidIatError# Handle invalid token, e.g. logout user or deny accessend

Subject Claim

sub='Subject'sub_payload={data:'data',sub:sub}token=JWT.encode(sub_payload,hmac_secret,'HS256')begin# Add sub to the validation to check if the token has been manipulateddecoded_token=JWT.decode(token,hmac_secret,true,{sub:sub,verify_sub:true,algorithm:'HS256'})rescueJWT::InvalidSubError# Handle invalid token, e.g. logout user or deny accessend

Standalone claim verification

JWT::Claims.verify_payload!({"exp"=>Time.now.to_i +10},:numeric,:exp)JWT::Claims.valid_payload?({"exp"=>Time.now.to_i +10},:exp)# => trueJWT::Claims.payload_errors({"exp"=>Time.now.to_i -10},:exp)# => [#<struct JWT::Claims::Error message="Signature has expired">]JWT::Claims.verify_payload!({"exp"=>Time.now.to_i -10},exp:{leeway:11})JWT::Claims.verify_payload!({"exp"=>Time.now.to_i +10,"sub"=>"subject"},:exp,sub:"subject")

Finding a Key

issuers=%w[My_Awesome_Company1My_Awesome_Company2]iss_payload={data:'data',iss:issuers.first}secrets={issuers.first=>hmac_secret,issuers.last=>'hmac_secret2'}token=JWT.encode(iss_payload,hmac_secret,'HS256')begin# Add iss to the validation to check if the token has been manipulateddecoded_token=JWT.decode(token,nil,true,{iss:issuers,verify_iss:true,algorithm:'HS256'})do |_headers,payload|secrets[payload['iss']]endrescueJWT::InvalidIssuerError# Handle invalid token, e.g. logout user or deny accessend

Required Claims

# Will raise a JWT::MissingRequiredClaim error if the 'exp' claim is absentJWT.decode(token,hmac_secret,true,{required_claims:['exp'],algorithm:'HS256'})

X.509 certificates in x5c header

root_certificates=[]# trusted `OpenSSL::X509::Certificate` objectscrl_uris=root_certificates.map(&:crl_uris)crls=crl_uris.mapdo |uri|# look up cached CRL by `uri` and return it if found, otherwise continuecrl=Net::HTTP.get(uri)crl=OpenSSL::X509::CRL.new(crl)# cache `crl` using `uri` as the key, expiry set to `crl.next_update` timestampendbeginJWT.decode(token,nil,true,{x5c:{root_certificates:root_certificates,crls:crls}})rescueJWT::DecodeError# Handle error, e.g. x5c header certificate revoked or expiredend

JSON Web Key (JWK)

optional_parameters={kid:'my-kid',use:'sig',alg:'RS512'}jwk=JWT::JWK.new(OpenSSL::PKey::RSA.new(2048),optional_parameters)# Encodingpayload={data:'data'}token=JWT.encode(payload,jwk.signing_key,jwk[:alg],kid:jwk[:kid])# JSON Web Key Set for advertising your signing keysjwks_hash=JWT::JWK::Set.new(jwk).export

jwks=JWT::JWK::Set.new(jwks_hash)jwks.filter!{|key|key[:use] =='sig'}# Signing keys only!algorithms=jwks.map{ |key|key[:alg]}.compact.uniqJWT.decode(token,nil,true,algorithms:algorithms,jwks:jwks)

jwks_loader=->(options)do# The jwk loader would fetch the set of JWKs from a trusted source.# To avoid malicious requests triggering cache invalidations there needs to be# some kind of grace time or other logic for determining the validity of the invalidation.# This example only allows cache invalidations every 5 minutes.ifoptions[:kid_not_found] &&@cache_last_update <Time.now.to_i -300logger.info("Invalidating JWK cache.#{options[:kid]} not found from previous cache")@cached_keys=nilend@cached_keys ||=begin@cache_last_update=Time.now.to_i# Replace with your own JWKS fetching routinejwks=JWT::JWK::Set.new(jwks_hash)jwks.select!{ |key|key[:use] =='sig'}# Signing Keys onlyjwksendendbeginJWT.decode(token,nil,true,{algorithms:['RS512'],jwks:jwks_loader})rescueJWT::JWKError# Handle problems with the provided JWKsrescueJWT::DecodeError# Handle other decode related issues e.g. no kid in header, no matching public key found etc.end

Importing and exporting JSON Web Keys

# Import a JWK Hash (showing an HMAC example)jwk=JWT::JWK.new({kty:'oct',k:'my-secret',kid:'my-kid'})# Import an OpenSSL key# You can optionally add descriptive parameters to the JWKdesc_params={kid:'my-kid',use:'sig'}jwk=JWT::JWK.new(OpenSSL::PKey::RSA.new(2048),desc_params)# Export as JWK Hash (public key only by default)jwk_hash=jwk.exportjwk_hash_with_private_key=jwk.export(include_private:true)# Export as OpenSSL keypublic_key=jwk.verify_keyprivate_key=jwk.signing_keyifjwk.private?# You can also import and export entire JSON Web Key Setsjwks_hash={keys:[{kty:'oct',k:'my-secret',kid:'my-kid'}]}jwks=JWT::JWK::Set.new(jwks_hash)jwks_hash=jwks.export

Key ID (kid) and JWKs

JWT.configuration.jwk.kid_generator_type=:rfc7638_thumbprint# ORJWT.configuration.jwk.kid_generator= ::JWT::JWK::Thumbprint# ORjwk=JWT::JWK.new(OpenSSL::PKey::RSA.new(2048),nil,kid_generator: ::JWT::JWK::Thumbprint)jwk_hash=jwk.exportthumbprint_as_the_kid=jwk_hash[:kid]

Development and testing

bundle installbundleexec appraisal raketest

Releasing

rake release:source_control_push

How to contribute

Contributors

License