jwt 2.4.1 → 2.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e7f3474ee58d51ca5646f48ca28bf669b40a4b7676cbe7211597ca6ae69f672
-  data.tar.gz: 570e6930c9094afea40ea8e8a6a7c9b3293890b121893f5148914b0a8e7d11f8
+  metadata.gz: af3792b982f014801d3ff7ae3410be6bd1e0b27f199c500942eb86267bb2b764
+  data.tar.gz: c37fc4b72cf3819210b15164548eff44579de1e8f8c48d9ce35864a84f007d9a
 SHA512:
-  metadata.gz: 3249529ec6bacc8e655e2830949af61c10e235a569f9dc67d3880335d5939b8afc56c180145d3e02dd09744288d50c31547338e105cf55ae4e0fbe237eb2a0e8
-  data.tar.gz: dd415314a7bd048d8b2b5b630d5b7011128932bf207dc785ac6154748aff68836a1c39e766dc176e225c643fc406fe9fdc5c510b36dc939e36722e327d8fe92f
+  metadata.gz: 3f61fd13a1d56c657691abb4bfde3671a7d93b5c853785b804c0d119d27f4641685828eb9c65a8e4856487782530e791ecbce5f1a5f1cb61c883daff97a44367
+  data.tar.gz: ef36aa81991e28cb9d3df65f1ebbeb6599eb99dee8e1953aff1a6231e91c6a3f9633e3afd22fbbc6c09f6318c4e516ee7a908428eee303f3952fed890395b267

data/CHANGELOG.md

@@ -1,31 +1,119 @@
 # Changelog
-## [v2.4.1](https://github.com/jwt/ruby-jwt/tree/v2.4.1) (2022-06-07)
+
+## [v2.8.1](https://github.com/jwt/ruby-jwt/tree/v2.8.1) (2024-02-29)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.8.0...v2.8.1)
+
+**Features:**
+
+- Configurable base64 decode behaviour [#589](https://github.com/jwt/ruby-jwt/pull/589) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Output deprecation warnings once [#589](https://github.com/jwt/ruby-jwt/pull/589) ([@anakinj](https://github.com/anakinj))
+
+## [v2.8.0](https://github.com/jwt/ruby-jwt/tree/v2.8.0) (2024-02-17)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.7.1...v2.8.0)
+
+**Features:**
+
+- Updated rubocop to 1.56 [#573](https://github.com/jwt/ruby-jwt/pull/573) ([@anakinj](https://github.com/anakinj))
+- Run CI on Ruby 3.3 [#577](https://github.com/jwt/ruby-jwt/pull/577) ([@anakinj](https://github.com/anakinj))
+- Deprecation warning added for the HMAC algorithm HS512256 (HMAC-SHA-512 truncated to 256-bits) [#575](https://github.com/jwt/ruby-jwt/pull/575) ([@anakinj](https://github.com/anakinj))
+- Stop using RbNaCl for standard HMAC algorithms [#575](https://github.com/jwt/ruby-jwt/pull/575) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Fix signature has expired error if payload is a string [#555](https://github.com/jwt/ruby-jwt/pull/555) ([@GobinathAL](https://github.com/GobinathAL))
+- Fix key base equality and spaceship operators [#569](https://github.com/jwt/ruby-jwt/pull/569) ([@magneland](https://github.com/magneland))
+- Remove explicit base64 require from x5c_key_finder [#580](https://github.com/jwt/ruby-jwt/pull/580) ([@anakinj](https://github.com/anakinj))
+- Performance improvements and cleanup of tests [#581](https://github.com/jwt/ruby-jwt/pull/581) ([@anakinj](https://github.com/anakinj))
+- Repair EC x/y coordinates when importing JWK [#585](https://github.com/jwt/ruby-jwt/pull/585) ([@julik](https://github.com/julik))
+- Explicit dependency to the base64 gem [#582](https://github.com/jwt/ruby-jwt/pull/582) ([@anakinj](https://github.com/anakinj))
+- Deprecation warning for decoding content not compliant with RFC 4648 [#582](https://github.com/jwt/ruby-jwt/pull/582) ([@anakinj](https://github.com/anakinj))
+- Algorithms moved under the `::JWT::JWA` module ([@anakinj](https://github.com/anakinj))
+
+## [v2.7.1](https://github.com/jwt/ruby-jwt/tree/v2.8.0) (2023-06-09)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.7.0...v2.7.1)
 
 **Fixes and enhancements:**
-- Raise JWT::DecodeError on invalid signature [\#484](https://github.com/jwt/ruby-jwt/pull/484) ([@freakyfelt!](https://github.com/freakyfelt!)).
+
+- Handle invalid algorithm when decoding JWT [#559](https://github.com/jwt/ruby-jwt/pull/559) ([@nataliastanko](https://github.com/nataliastanko))
+- Do not raise error when verifying bad HMAC signature [#563](https://github.com/jwt/ruby-jwt/pull/563) ([@hieuk09](https://github.com/hieuk09))
+
+## [v2.7.0](https://github.com/jwt/ruby-jwt/tree/v2.7.0) (2023-02-01)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.6.0...v2.7.0)
+
+**Features:**
+
+- Support OKP (Ed25519) keys for JWKs [#540](https://github.com/jwt/ruby-jwt/pull/540) ([@anakinj](https://github.com/anakinj))
+- JWK Sets can now be used for tokens with nil kid [#543](https://github.com/jwt/ruby-jwt/pull/543) ([@bellebaum](https://github.com/bellebaum))
+
+**Fixes and enhancements:**
+
+- Fix issue with multiple keys returned by keyfinder and multiple allowed algorithms [#545](https://github.com/jwt/ruby-jwt/pull/545) ([@mpospelov](https://github.com/mpospelov))
+- Non-string `kid` header values are now rejected [#543](https://github.com/jwt/ruby-jwt/pull/543) ([@bellebaum](https://github.com/bellebaum))
+
+## [v2.6.0](https://github.com/jwt/ruby-jwt/tree/v2.6.0) (2022-12-22)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.5.0...v2.6.0)
+
+**Features:**
+
+- Support custom algorithms by passing algorithm objects [#512](https://github.com/jwt/ruby-jwt/pull/512) ([@anakinj](https://github.com/anakinj))
+- Support descriptive (not key related) JWK parameters [#520](https://github.com/jwt/ruby-jwt/pull/520) ([@bellebaum](https://github.com/bellebaum))
+- Support for JSON Web Key Sets [#525](https://github.com/jwt/ruby-jwt/pull/525) ([@bellebaum](https://github.com/bellebaum))
+- Support HMAC keys over 32 chars when using RbNaCl [#521](https://github.com/jwt/ruby-jwt/pull/521) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Raise descriptive error on empty hmac_secret and OpenSSL 3.0/openssl gem <3.0.1 [#530](https://github.com/jwt/ruby-jwt/pull/530) ([@jonmchan](https://github.com/jonmchan))
+
+## [v2.5.0](https://github.com/jwt/ruby-jwt/tree/v2.5.0) (2022-08-25)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.4.1...v2.5.0)
+
+**Features:**
+
+- Support JWK thumbprints as key ids [#481](https://github.com/jwt/ruby-jwt/pull/481) ([@anakinj](https://github.com/anakinj))
+- Support OpenSSL >= 3.0 [#496](https://github.com/jwt/ruby-jwt/pull/496) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+- Bring back the old Base64 (RFC2045) deocode mechanisms [#488](https://github.com/jwt/ruby-jwt/pull/488) ([@anakinj](https://github.com/anakinj))
+- Rescue RbNaCl exception for EdDSA wrong key [#491](https://github.com/jwt/ruby-jwt/pull/491) ([@n-studio](https://github.com/n-studio))
+- New parameter name for cases when kid is not found using JWK key loader proc [#501](https://github.com/jwt/ruby-jwt/pull/501) ([@anakinj](https://github.com/anakinj))
+- Fix NoMethodError when a 2 segment token is missing 'alg' header [#502](https://github.com/jwt/ruby-jwt/pull/502) ([@cmrd-senya](https://github.com/cmrd-senya))
+
+## [v2.4.1](https://github.com/jwt/ruby-jwt/tree/v2.4.1) (2022-06-07)
 
 [Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.4.0...v2.4.1)
 
+**Fixes and enhancements:**
+- Raise JWT::DecodeError on invalid signature [\#484](https://github.com/jwt/ruby-jwt/pull/484) ([@freakyfelt!](https://github.com/freakyfelt!))
+
 ## [v2.4.0](https://github.com/jwt/ruby-jwt/tree/v2.4.0) (2022-06-06)
 
 [Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.3.0...v2.4.0)
 
 **Features:**
 
-- Dropped support for Ruby 2.5 and older [#453](https://github.com/jwt/ruby-jwt/pull/453) - [@anakinj](https://github.com/anakinj).
-- Use Ruby built-in url-safe base64 methods [#454](https://github.com/jwt/ruby-jwt/pull/454) - [@bdewater](https://github.com/bdewater).
-- Updated rubocop to 1.23.0 [#457](https://github.com/jwt/ruby-jwt/pull/457) - [@anakinj](https://github.com/anakinj).
-- Add x5c header key finder [#338](https://github.com/jwt/ruby-jwt/pull/338) - [@bdewater](https://github.com/bdewater).
-- Author driven changelog process [#463](https://github.com/jwt/ruby-jwt/pull/463) - [@anakinj](https://github.com/anakinj).
-- Allow regular expressions and procs to verify issuer [\#437](https://github.com/jwt/ruby-jwt/pull/437) ([rewritten](https://github.com/rewritten)).
-- Add Support to be able to verify from multiple keys [\#425](https://github.com/jwt/ruby-jwt/pull/425) ([ritikesh](https://github.com/ritikesh)).
+- Dropped support for Ruby 2.5 and older [#453](https://github.com/jwt/ruby-jwt/pull/453) - ([@anakinj](https://github.com/anakinj))
+- Use Ruby built-in url-safe base64 methods [#454](https://github.com/jwt/ruby-jwt/pull/454) - ([@bdewater](https://github.com/bdewater))
+- Updated rubocop to 1.23.0 [#457](https://github.com/jwt/ruby-jwt/pull/457) - ([@anakinj](https://github.com/anakinj))
+- Add x5c header key finder [#338](https://github.com/jwt/ruby-jwt/pull/338) - ([@bdewater](https://github.com/bdewater))
+- Author driven changelog process [#463](https://github.com/jwt/ruby-jwt/pull/463) - ([@anakinj](https://github.com/anakinj))
+- Allow regular expressions and procs to verify issuer [\#437](https://github.com/jwt/ruby-jwt/pull/437) ([rewritten](https://github.com/rewritten))
+- Add Support to be able to verify from multiple keys [\#425](https://github.com/jwt/ruby-jwt/pull/425) ([ritikesh](https://github.com/ritikesh))
 
 **Fixes and enhancements:**
-- Readme: Typo fix re MissingRequiredClaim [\#451](https://github.com/jwt/ruby-jwt/pull/451) ([antonmorant](https://github.com/antonmorant)).
-- Fix RuboCop TODOs [\#476](https://github.com/jwt/ruby-jwt/pull/476) ([typhoon2099](https://github.com/typhoon2099)).
-- Make specific algorithms in README linkable [\#472](https://github.com/jwt/ruby-jwt/pull/472) ([milieu](https://github.com/milieu)).
-- Update note about supported JWK types [\#475](https://github.com/jwt/ruby-jwt/pull/475) ([dpashkevich](https://github.com/dpashkevich)).
-- Create CODE\_OF\_CONDUCT.md [\#449](https://github.com/jwt/ruby-jwt/pull/449) ([loic5](https://github.com/loic5)).
+- Readme: Typo fix re MissingRequiredClaim [\#451](https://github.com/jwt/ruby-jwt/pull/451) ([antonmorant](https://github.com/antonmorant))
+- Fix RuboCop TODOs [\#476](https://github.com/jwt/ruby-jwt/pull/476) ([typhoon2099](https://github.com/typhoon2099))
+- Make specific algorithms in README linkable [\#472](https://github.com/jwt/ruby-jwt/pull/472) ([milieu](https://github.com/milieu))
+- Update note about supported JWK types [\#475](https://github.com/jwt/ruby-jwt/pull/475) ([dpashkevich](https://github.com/dpashkevich))
+- Create CODE\_OF\_CONDUCT.md [\#449](https://github.com/jwt/ruby-jwt/pull/449) ([loic5](https://github.com/loic5))
 
 ## [v2.3.0](https://github.com/jwt/ruby-jwt/tree/v2.3.0) (2021-10-03)
 

data/CONTRIBUTING.md

@@ -12,19 +12,19 @@ git remote add upstream https://github.com/jwt/ruby-jwt
 
 ## Create a branch for your implementation
 
-Make sure you have the latest upstream master branch of the project.
+Make sure you have the latest upstream main branch of the project.
 
 ```
 git fetch --all
-git checkout master
-git rebase upstream/master
-git push origin master
+git checkout main
+git rebase upstream/main
+git push origin main
 git checkout -b fix-a-little-problem
 ```
 
 ## Running the tests and linter
 
-Before you start with your implementation make sure you are able to get a succesful test run with the current revision.
+Before you start with your implementation make sure you are able to get a successful test run with the current revision.
 
 The tests are written with rspec and [Appraisal](https://github.com/thoughtbot/appraisal) is used to ensure compatibility with 3rd party dependencies providing cryptographic features.
 
@@ -78,12 +78,12 @@ A maintainer will review and probably merge you changes when time allows, be pat
 
 ## Keeping your branch up-to-date
 
-It's recommended that you keep your branch up-to-date by rebasing to the upstream master.
+It's recommended that you keep your branch up-to-date by rebasing to the upstream main.
 
 ```
 git fetch upstream
 git checkout fix-a-little-problem
-git rebase upstream/master
+git rebase upstream/main
 git push origin fix-a-little-problem -f
 ```
 

data/README.md

@@ -1,18 +1,17 @@
 # JWT
 
 [![Gem Version](https://badge.fury.io/rb/jwt.svg)](https://badge.fury.io/rb/jwt)
-[![Build Status](https://github.com/jwt/ruby-jwt/workflows/test/badge.svg?branch=master)](https://github.com/jwt/ruby-jwt/actions)
+[![Build Status](https://github.com/jwt/ruby-jwt/workflows/test/badge.svg?branch=main)](https://github.com/jwt/ruby-jwt/actions)
 [![Code Climate](https://codeclimate.com/github/jwt/ruby-jwt/badges/gpa.svg)](https://codeclimate.com/github/jwt/ruby-jwt)
 [![Test Coverage](https://codeclimate.com/github/jwt/ruby-jwt/badges/coverage.svg)](https://codeclimate.com/github/jwt/ruby-jwt/coverage)
 [![Issue Count](https://codeclimate.com/github/jwt/ruby-jwt/badges/issue_count.svg)](https://codeclimate.com/github/jwt/ruby-jwt)
-[![SourceLevel](https://app.sourcelevel.io/github/jwt/-/ruby-jwt.svg)](https://app.sourcelevel.io/github/jwt/-/ruby-jwt)
 
 A ruby implementation of the [RFC 7519 OAuth JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) standard.
 
 If you have further questions related to development or usage, join us: [ruby-jwt google group](https://groups.google.com/forum/#!forum/ruby-jwt).
 
 ## Announcements
-* Ruby 2.4 support is going to be dropped in version 2.4.0
+* Ruby 2.4 support was dropped in version 2.4.0
 * Ruby 1.9.3 support was dropped at December 31st, 2016.
 * Version 1.5.3 yanked. See: [#132](https://github.com/jwt/ruby-jwt/issues/132) and [#133](https://github.com/jwt/ruby-jwt/issues/133)
 
@@ -44,6 +43,23 @@ The JWT spec supports NONE, HMAC, RSASSA, ECDSA and RSASSA-PSS algorithms for cr
 
 See: [ JSON Web Algorithms (JWA) 3.1. "alg" (Algorithm) Header Parameter Values for JWS](https://tools.ietf.org/html/rfc7518#section-3.1)
 
+### Deprecation warnings
+
+Deprecation warnings are logged once (`:once` option) by default to avoid spam in logs. Other options are `:silent` to completely silence warnings and `:warn` to log every time a deprecated path is executed.
+
+```ruby
+  JWT.configuration.deprecation_warnings = :warn # default is :once
+```
+
+### Base64 decoding
+
+In the past the gem has been supporting the Base64 decoding specified in [RFC2045](https://www.rfc-editor.org/rfc/rfc2045) allowing newlines and blanks in the base64 encoded payload. In future versions base64 decoding will be stricter and only comply to [RFC4648](https://www.rfc-editor.org/rfc/rfc4648).
+
+The stricter base64 decoding when processing tokens can be done via the `strict_base64_decoding` configuration accessor.
+```ruby
+  JWT.configuration.strict_base64_decoding = true # default is false
+```
+
 ### **NONE**
 
 * none - unsigned token
@@ -73,12 +89,11 @@ puts decoded_token
 ### **HMAC**
 
 * HS256 - HMAC using SHA-256 hash algorithm
-* HS512256 - HMAC using SHA-512-256 hash algorithm (only available with RbNaCl; see note below)
 * HS384 - HMAC using SHA-384 hash algorithm
 * HS512 - HMAC using SHA-512 hash algorithm
 
 ```ruby
-# The secret must be a string. A JWT::DecodeError will be raised if it isn't provided.
+# The secret must be a string. With OpenSSL 3.0/openssl gem `<3.0.1`, JWT::DecodeError will be raised if it isn't provided.
 hmac_secret = 'my$ecretK3y'
 
 token = JWT.encode payload, hmac_secret, 'HS256'
@@ -96,12 +111,6 @@ decoded_token = JWT.decode token, hmac_secret, true, { algorithm: 'HS256' }
 puts decoded_token
 ```
 
-Note: If [RbNaCl](https://github.com/cryptosphere/rbnacl) is loadable, ruby-jwt will use it for HMAC-SHA256, HMAC-SHA512-256, and HMAC-SHA512. RbNaCl enforces a maximum key size of 32 bytes for these algorithms.
-
-[RbNaCl](https://github.com/cryptosphere/rbnacl) requires
-[libsodium](https://github.com/jedisct1/libsodium), it can be installed
-on MacOS with `brew install libsodium`.
-
 ### **RSA**
 
 * RS256 - RSA using SHA-256 hash algorithm
@@ -135,17 +144,14 @@ puts decoded_token
 * ES256K - ECDSA using P-256K and SHA-256
 
 ```ruby
-ecdsa_key = OpenSSL::PKey::EC.new 'prime256v1'
-ecdsa_key.generate_key
-ecdsa_public = OpenSSL::PKey::EC.new ecdsa_key
-ecdsa_public.private_key = nil
+ecdsa_key = OpenSSL::PKey::EC.generate('prime256v1')
 
 token = JWT.encode payload, ecdsa_key, 'ES256'
 
 # eyJhbGciOiJFUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.AlLW--kaF7EX1NMX9WJRuIW8NeRJbn2BLXHns7Q5TZr7Hy3lF6MOpMlp7GoxBFRLISQ6KrD0CJOrR8aogEsPeg
 puts token
 
-decoded_token = JWT.decode token, ecdsa_public, true, { algorithm: 'ES256' }
+decoded_token = JWT.decode token, ecdsa_key, true, { algorithm: 'ES256' }
 
 # Array
 # [
@@ -163,7 +169,7 @@ In order to use this algorithm you need to add the `RbNaCl` gem to you `Gemfile`
 gem 'rbnacl'
 ```
 
-For more detailed installation instruction check the official [repository](https://github.com/cryptosphere/rbnacl) on GitHub.
+For more detailed installation instruction check the official [repository](https://github.com/RubyCrypto/rbnacl) on GitHub.
 
 * ED25519
 
@@ -186,7 +192,7 @@ decoded_token = JWT.decode token, public_key, true, { algorithm: 'ED25519' }
 
 ### **RSASSA-PSS**
 
-In order to use this algorithm you need to add the `openssl` gem to you `Gemfile` with a version greater or equal to `2.1`.
+In order to use this algorithm you need to add the `openssl` gem to your `Gemfile` with a version greater or equal to `2.1`.
 
 ```ruby
 gem 'openssl', '~> 2.1'
@@ -215,6 +221,33 @@ decoded_token = JWT.decode token, rsa_public, true, { algorithm: 'PS256' }
 puts decoded_token
 ```
 
+### **Custom algorithms**
+
+An object implementing custom signing or verification behaviour can be passed in the `algorithm` option when encoding and decoding. The given object needs to implement the method `valid_alg?` and `verify` and/or `alg` and `sign`, depending if object is used for encoding or decoding.
+
+```ruby
+module CustomHS512Algorithm
+  def self.alg
+    'HS512'
+  end
+
+  def self.valid_alg?(alg_to_validate)
+    alg_to_validate == alg
+  end
+
+  def self.sign(data:, signing_key:)
+    OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha512'), data, signing_key)
+  end
+
+  def self.verify(data:, signature:, verification_key:)
+    ::OpenSSL.secure_compare(sign(data: data, signing_key: verification_key), signature)
+  end
+end
+
+token = ::JWT.encode({'pay' => 'load'}, 'secret', CustomHS512Algorithm)
+payload, header = ::JWT.decode(token, 'secret', true, algorithm: CustomHS512Algorithm)
+```
+
 ## Support for reserved claim names
 JSON Web Token defines some reserved claim names and defines how they should be
 used. JWT supports these reserved claim names:
@@ -538,7 +571,7 @@ crls = crl_uris.map do |uri|
 end
 
 begin
-  JWT.decode(token, nil, true, { x5c: { root_certificates: root_certificates, crls: crls })
+  JWT.decode(token, nil, true, { x5c: { root_certificates: root_certificates, crls: crls } })
 rescue JWT::DecodeError
   # Handle error, e.g. x5c header certificate revoked or expired
 end
@@ -546,22 +579,62 @@ end
 
 ### JSON Web Key (JWK)
 
-JWK is a JSON structure representing a cryptographic key. Currently only supports RSA, EC and HMAC keys.
+JWK is a JSON structure representing a cryptographic key. This gem currently supports RSA, EC, OKP and HMAC keys. OKP support requires [RbNaCl](https://github.com/RubyCrypto/rbnacl) and currently only supports the Ed25519 curve.
+
+To encode a JWT using your JWK:
+
+```ruby
+optional_parameters = { kid: 'my-kid', use: 'sig', alg: 'RS512' }
+jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), optional_parameters)
+
+# Encoding
+payload = { data: 'data' }
+token = JWT.encode(payload, jwk.signing_key, jwk[:alg], kid: jwk[:kid])
+
+# JSON Web Key Set for advertising your signing keys
+jwks_hash = JWT::JWK::Set.new(jwk).export
+```
+
+To decode a JWT using a trusted entity's JSON Web Key Set (JWKS):
 
 ```ruby
-jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), "optional-kid")
-payload, headers = { data: 'data' }, { kid: jwk.kid }
+jwks = JWT::JWK::Set.new(jwks_hash)
+jwks.filter! {|key| key[:use] == 'sig' } # Signing keys only!
+algorithms = jwks.map { |key| key[:alg] }.compact.uniq
+JWT.decode(token, nil, true, algorithms: algorithms, jwks: jwks)
+```
+
+
+The `jwks` option can also be given as a lambda that evaluates every time a kid is resolved.
+This can be used to implement caching of remotely fetched JWK Sets.
 
-token = JWT.encode(payload, jwk.keypair, 'RS512', headers)
+If the requested `kid` is not found from the given set the loader will be called a second time with the `kid_not_found` option set to `true`.
+The application can choose to implement some kind of JWK cache invalidation or other mechanism to handle such cases.
 
-# The jwk loader would fetch the set of JWKs from a trusted source
-jwk_loader = ->(options) do
-  @cached_keys = nil if options[:invalidate] # need to reload the keys
-  @cached_keys ||= { keys: [jwk.export] }
+Tokens without a specified `kid` are rejected by default.
+This behaviour may be overwritten by setting the `allow_nil_kid` option for `decode` to `true`.
+
+```ruby
+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.
+  if options[:kid_not_found] && @cache_last_update < Time.now.to_i - 300
+    logger.info("Invalidating JWK cache. #{options[:kid]} not found from previous cache")
+    @cached_keys = nil
+  end
+  @cached_keys ||= begin
+    @cache_last_update = Time.now.to_i
+    # Replace with your own JWKS fetching routine
+    jwks = JWT::JWK::Set.new(jwks_hash)
+    jwks.select! { |key| key[:use] == 'sig' } # Signing Keys only
+    jwks
+  end
 end
 
 begin
-  JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwk_loader})
+  JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwks_loader })
 rescue JWT::JWKError
   # Handle problems with the provided JWKs
 rescue JWT::DecodeError
@@ -569,26 +642,70 @@ rescue JWT::DecodeError
 end
 ```
 
-or by passing JWK as a simple Hash
+### Importing and exporting JSON Web Keys
 
-```
-jwks = { keys: [{ ... }] } # keys accepts both of string and symbol
-JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwks})
+The ::JWT::JWK class can be used to import both JSON Web Keys and OpenSSL keys
+and export to either format with and without the private key included.
+
+To include the private key in the export pass the `include_private` parameter to the export method.
+
+```ruby
+# 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 JWK
+desc_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.export
+jwk_hash_with_private_key = jwk.export(include_private: true)
+
+# Export as OpenSSL key
+public_key = jwk.verify_key
+private_key = jwk.signing_key if jwk.private?
+
+# You can also import and export entire JSON Web Key Sets
+jwks_hash = { keys: [{ kty: 'oct', k: 'my-secret', kid: 'my-kid' }] }
+jwks = JWT::JWK::Set.new(jwks_hash)
+jwks_hash = jwks.export
 ```
 
-### Importing and exporting JSON Web Keys
+### Key ID (kid) and JWKs
 
-The ::JWT::JWK class can be used to import and export both the public key (default behaviour) and the private key. To include the private key in the export pass the `include_private` parameter to the export method.
+The key id (kid) generation in the gem is a custom algorithm and not based on any standards.
+To use a standardized JWK thumbprint (RFC 7638) as the kid for JWKs a generator type can be specified in the global configuration
+or can be given to the JWK instance on initialization.
 
 ```ruby
-jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048))
+JWT.configuration.jwk.kid_generator_type = :rfc7638_thumbprint
+# OR
+JWT.configuration.jwk.kid_generator = ::JWT::JWK::Thumbprint
+# OR
+jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), nil, kid_generator: ::JWT::JWK::Thumbprint)
 
 jwk_hash = jwk.export
-jwk_hash_with_private_key = jwk.export(include_private: true)
+
+thumbprint_as_the_kid = jwk_hash[:kid]
 ```
 
-## How to contribute
+# Development and Tests
+
+We depend on [Bundler](http://rubygems.org/gems/bundler) for defining gemspec and performing releases to rubygems.org, which can be done with
 
+```bash
+rake release
+```
+
+The tests are written with rspec. [Appraisal](https://github.com/thoughtbot/appraisal) is used to ensure compatibility with 3rd party dependencies providing cryptographic features.
+
+```bash
+bundle install
+bundle exec appraisal rake test
+```
+
+## How to contribute
 See [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Contributors

data/lib/jwt/base64.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module JWT
+  # Base64 encoding and decoding
+  class Base64
+    class << self
+      # Encode a string with URL-safe Base64 complying with RFC 4648 (not padded).
+      def url_encode(str)
+        ::Base64.urlsafe_encode64(str, padding: false)
+      end
+
+      # Decode a string with URL-safe Base64 complying with RFC 4648.
+      # Deprecated support for RFC 2045 remains for now. ("All line breaks or other characters not found in Table 1 must be ignored by decoding software")
+      def url_decode(str)
+        ::Base64.urlsafe_decode64(str)
+      rescue ArgumentError => e
+        raise unless e.message == 'invalid base64'
+        raise Base64DecodeError, 'Invalid base64 encoding' if JWT.configuration.strict_base64_decoding
+
+        loose_urlsafe_decode64(str).tap do
+          Deprecations.warning('Invalid base64 input detected, could be because of invalid padding, trailing whitespaces or newline chars. Graceful handling of invalid input will be dropped in the next major version of ruby-jwt')
+        end
+      end
+
+      def loose_urlsafe_decode64(str)
+        str += '=' * (4 - str.length.modulo(4))
+        ::Base64.decode64(str.tr('-_', '+/'))
+      end
+    end
+  end
+end

data/lib/jwt/claims_validator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative './error'
+require_relative 'error'
 
 module JWT
   class ClaimsValidator

data/lib/jwt/configuration/container.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'decode_configuration'
+require_relative 'jwk_configuration'
+
+module JWT
+  module Configuration
+    class Container
+      attr_accessor :decode, :jwk, :strict_base64_decoding
+      attr_reader :deprecation_warnings
+
+      def initialize
+        reset!
+      end
+
+      def reset!
+        @decode                 = DecodeConfiguration.new
+        @jwk                    = JwkConfiguration.new
+        @strict_base64_decoding = false
+
+        self.deprecation_warnings = :once
+      end
+
+      DEPRECATION_WARNINGS_VALUES = %i[once warn silent].freeze
+      def deprecation_warnings=(value)
+        raise ArgumentError, "Invalid deprecation_warnings value #{value}. Supported values: #{DEPRECATION_WARNINGS_VALUES}" unless DEPRECATION_WARNINGS_VALUES.include?(value)
+
+        @deprecation_warnings = value
+      end
+    end
+  end
+end

data/lib/jwt/configuration/decode_configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module JWT
+  module Configuration
+    class DecodeConfiguration
+      attr_accessor :verify_expiration,
+                    :verify_not_before,
+                    :verify_iss,
+                    :verify_iat,
+                    :verify_jti,
+                    :verify_aud,
+                    :verify_sub,
+                    :leeway,
+                    :algorithms,
+                    :required_claims
+
+      def initialize
+        @verify_expiration = true
+        @verify_not_before = true
+        @verify_iss = false
+        @verify_iat = false
+        @verify_jti = false
+        @verify_aud = false
+        @verify_sub = false
+        @leeway = 0
+        @algorithms = ['HS256']
+        @required_claims = []
+      end
+
+      def to_h
+        {
+          verify_expiration: verify_expiration,
+          verify_not_before: verify_not_before,
+          verify_iss: verify_iss,
+          verify_iat: verify_iat,
+          verify_jti: verify_jti,
+          verify_aud: verify_aud,
+          verify_sub: verify_sub,
+          leeway: leeway,
+          algorithms: algorithms,
+          required_claims: required_claims
+        }
+      end
+    end
+  end
+end

data/lib/jwt/configuration/jwk_configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../jwk/kid_as_key_digest'
+require_relative '../jwk/thumbprint'
+
+module JWT
+  module Configuration
+    class JwkConfiguration
+      def initialize
+        self.kid_generator_type = :key_digest
+      end
+
+      def kid_generator_type=(value)
+        self.kid_generator = case value
+                             when :key_digest
+                               JWT::JWK::KidAsKeyDigest
+                             when :rfc7638_thumbprint
+                               JWT::JWK::Thumbprint
+                             else
+                               raise ArgumentError, "#{value} is not a valid kid generator type."
+        end
+      end
+
+      attr_accessor :kid_generator
+    end
+  end
+end

data/lib/jwt/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'configuration/container'
+
+module JWT
+  module Configuration
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= ::JWT::Configuration::Container.new
+    end
+  end
+end