From 8c506e3575e207dd19da25d238dd86481b99d3a3 Mon Sep 17 00:00:00 2001
From: Ritikesh <ritikeshsisodiya@gmail.com>
Date: Tue, 22 Jun 2021 12:29:37 +0530
Subject: [PATCH] Add documentation for find_key

---
 README.md                                | 22 ++++++++++++++++++++++
 spec/integration/readme_examples_spec.rb | 15 +++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/README.md b/README.md
index 55287e52..9334a3ac 100644
--- a/README.md
+++ b/README.md
@@ -460,6 +460,28 @@ rescue JWT::InvalidSubError
 end
 ```
 
+### Finding a Key
+
+To dynamically find the key for verifying the JWT signature, pass a block to the decode block. The block receives headers and the original payload as parameters. It should return with the key to verify the signature that was used to sign the JWT.
+
+```ruby
+issuers = %w[My_Awesome_Company1 My_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 manipulated
+  decoded_token = JWT.decode(token, nil, true, { iss: issuers, verify_iss: true, algorithm: 'HS256' }) do |_headers, payload|
+    secrets[payload['iss']]
+  end
+rescue JWT::InvalidIssuerError
+  # Handle invalid token, e.g. logout user or deny access
+end
+```
+
 ### JSON Web Key (JWK)
 
 JWK is a JSON structure representing a cryptographic key. Currently only supports RSA public keys.
diff --git a/spec/integration/readme_examples_spec.rb b/spec/integration/readme_examples_spec.rb
index 7b50a0d8..e424a0d4 100644
--- a/spec/integration/readme_examples_spec.rb
+++ b/spec/integration/readme_examples_spec.rb
@@ -226,6 +226,21 @@
       end.not_to raise_error
     end
 
+    it 'find_key' do
+      issuers = %w[My_Awesome_Company1 My_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'
+
+      expect do
+        # Add iss to the validation to check if the token has been manipulated
+        JWT.decode(token, nil, true, { iss: issuers, verify_iss: true, algorithm: 'HS256' }) do |_headers, payload|
+          secrets[payload['iss']]
+        end
+      end.not_to raise_error
+    end
 
     it 'JWK' do
       jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048))