omniauth-auth0 2.2.0 → 2.4.2

data/lib/omniauth-auth0/version.rb

@@ -1,5 +1,5 @@
 module OmniAuth
   module Auth0
-    VERSION = '2.2.0'.freeze
+    VERSION = '2.4.2'.freeze
   end
 end

data/lib/omniauth/auth0/errors.rb

@@ -0,0 +1,11 @@
+module OmniAuth
+  module Auth0
+    class TokenValidationError < StandardError
+      attr_reader :error_reason
+      def initialize(msg)
+        @error_reason = msg
+        super(msg)
+      end
+    end
+  end
+end

data/lib/omniauth/auth0/jwt_validator.rb

@@ -2,6 +2,7 @@ require 'base64'
 require 'uri'
 require 'json'
 require 'omniauth'
+require 'omniauth/auth0/errors'
 
 module OmniAuth
   module Auth0
@@ -15,7 +16,8 @@ module OmniAuth
       #   options.issuer - Application issuer (optional).
       #   options.client_id - Application Client ID.
       #   options.client_secret - Application Client Secret.
-      def initialize(options)
+
+      def initialize(options, authorize_params = {})
         @domain = uri_string(options.domain)
 
         # Use custom issuer if provided, otherwise use domain
@@ -26,23 +28,45 @@ module OmniAuth
         @client_secret = options.client_secret
       end
 
-      # Decode a JWT.
-      # @param jwt string - JWT to decode.
-      # @return hash - The decoded token, if there were no exceptions.
-      # @see https://github.com/jwt/ruby-jwt
-      def decode(jwt)
+      # Verify a token's signature. Only tokens signed with the RS256 or HS256 signatures are supported.
+      # @return array - The token's key and signing algorithm
+      def verify_signature(jwt)
         head = token_head(jwt)
 
         # Make sure the algorithm is supported and get the decode key.
-        decode_key = @client_secret
         if head[:alg] == 'RS256'
-          decode_key = rs256_decode_key(head[:kid])
-        elsif head[:alg] != 'HS256'
-          raise JWT::VerificationError, :id_token_alg_unsupported
+          key, alg = [rs256_decode_key(head[:kid]), head[:alg]]
+        elsif head[:alg] == 'HS256'
+          key, alg = [@client_secret, head[:alg]]
+        else
+          raise OmniAuth::Auth0::TokenValidationError.new("Signature algorithm of #{head[:alg]} is not supported. Expected the ID token to be signed with RS256 or HS256")
+        end
+
+        # Call decode to verify the signature
+        JWT.decode(jwt, key, true, decode_opts(alg))
+
+        return key, alg
+      end
+
+      # Verify a JWT.
+      # @param jwt string - JWT to verify.
+      # @param authorize_params hash - Authorization params to verify on the JWT
+      # @return hash - The verified token, if there were no exceptions.
+      def verify(jwt, authorize_params = {})
+        if !jwt
+          raise OmniAuth::Auth0::TokenValidationError.new('ID token is required but missing')
+        end
+
+        parts = jwt.split('.')
+        if parts.length != 3
+          raise OmniAuth::Auth0::TokenValidationError.new('ID token could not be decoded')
         end
 
-        # Docs: https://github.com/jwt/ruby-jwt#algorithms-and-usage
-        JWT.decode(jwt, decode_key, true, decode_opts(head[:alg]))
+        key, alg = verify_signature(jwt)
+        id_token, header = JWT.decode(jwt, key, false)
+        verify_claims(id_token, authorize_params)
+
+        return id_token
       end
 
       # Get the decoded head segment from a JWT.
@@ -76,26 +100,28 @@ module OmniAuth
       end
 
       private
-
-      # Get the JWT decode options
-      # Docs: https://github.com/jwt/ruby-jwt#add-custom-header-fields
+      # Get the JWT decode options. We disable the claim checks since we perform our claim validation logic
+      # Docs: https://github.com/jwt/ruby-jwt
       # @return hash
       def decode_opts(alg)
         {
           algorithm: alg,
-          leeway: 30,
-          verify_expiration: true,
-          verify_iss: true,
-          iss: @issuer,
-          verify_aud: true,
-          aud: @client_id,
-          verify_not_before: true
+          verify_expiration: false,
+          verify_iat: false,
+          verify_iss: false,
+          verify_aud: false,
+          verify_jti: false,
+          verify_subj: false,
+          verify_not_before: false
         }
       end
 
       def rs256_decode_key(kid)
         jwks_x5c = jwks_key(:x5c, kid)
-        raise JWT::VerificationError, :jwks_missing_x5c if jwks_x5c.nil?
+
+        if jwks_x5c.nil?
+          raise OmniAuth::Auth0::TokenValidationError.new("Could not find a public key for Key ID (kid) '#{kid}'")
+        end
 
         jwks_public_cert(jwks_x5c.first)
       end
@@ -129,6 +155,97 @@ module OmniAuth
         temp_domain = URI("https://#{uri}") unless temp_domain.scheme
         "#{temp_domain}/"
       end
+
+      def verify_claims(id_token, authorize_params)
+        leeway = authorize_params[:leeway] || 60
+        max_age = authorize_params[:max_age]
+        nonce = authorize_params[:nonce]
+
+        verify_iss(id_token)
+        verify_sub(id_token)
+        verify_aud(id_token)
+        verify_expiration(id_token, leeway)
+        verify_iat(id_token)
+        verify_nonce(id_token, nonce)
+        verify_azp(id_token)
+        verify_auth_time(id_token, leeway, max_age)
+      end
+
+      def verify_iss(id_token)
+        issuer = id_token['iss']
+        if !issuer
+          raise OmniAuth::Auth0::TokenValidationError.new("Issuer (iss) claim must be a string present in the ID token")
+        elsif @issuer != issuer
+          raise OmniAuth::Auth0::TokenValidationError.new("Issuer (iss) claim mismatch in the ID token, expected (#{@issuer}), found (#{id_token['iss']})")
+        end
+      end
+
+      def verify_sub(id_token)
+        subject = id_token['sub']
+        if !subject || !subject.is_a?(String) || subject.empty?
+          raise OmniAuth::Auth0::TokenValidationError.new('Subject (sub) claim must be a string present in the ID token')
+        end
+      end
+
+      def verify_aud(id_token)
+        audience = id_token['aud']
+        if !audience || !(audience.is_a?(String) || audience.is_a?(Array))
+          raise OmniAuth::Auth0::TokenValidationError.new("Audience (aud) claim must be a string or array of strings present in the ID token")
+        elsif audience.is_a?(Array) && !audience.include?(@client_id)
+          raise OmniAuth::Auth0::TokenValidationError.new("Audience (aud) claim mismatch in the ID token; expected #{@client_id} but was not one of #{audience.join(', ')}")
+        elsif audience.is_a?(String) && audience != @client_id
+          raise OmniAuth::Auth0::TokenValidationError.new("Audience (aud) claim mismatch in the ID token; expected #{@client_id} but found #{audience}")
+        end
+      end
+
+      def verify_expiration(id_token, leeway)
+        expiration = id_token['exp']
+        if !expiration || !expiration.is_a?(Integer)
+          raise OmniAuth::Auth0::TokenValidationError.new("Expiration time (exp) claim must be a number present in the ID token")
+        elsif expiration <= Time.now.to_i - leeway
+          raise OmniAuth::Auth0::TokenValidationError.new("Expiration time (exp) claim error in the ID token; current time (#{Time.now}) is after expiration time (#{Time.at(expiration + leeway)})")
+        end
+      end
+
+      def verify_iat(id_token)
+        if !id_token['iat']
+          raise OmniAuth::Auth0::TokenValidationError.new("Issued At (iat) claim must be a number present in the ID token")
+        end
+      end
+
+      def verify_nonce(id_token, nonce)
+        if nonce
+          received_nonce = id_token['nonce']
+          if !received_nonce
+            raise OmniAuth::Auth0::TokenValidationError.new("Nonce (nonce) claim must be a string present in the ID token")
+          elsif nonce != received_nonce
+            raise OmniAuth::Auth0::TokenValidationError.new("Nonce (nonce) claim value mismatch in the ID token; expected (#{nonce}), found (#{received_nonce})")
+          end
+        end
+      end
+
+      def verify_azp(id_token)
+        audience = id_token['aud']
+        if audience.is_a?(Array) && audience.length > 1
+          azp = id_token['azp']
+          if !azp || !azp.is_a?(String)
+            raise OmniAuth::Auth0::TokenValidationError.new("Authorized Party (azp) claim must be a string present in the ID token when Audience (aud) claim has multiple values")
+          elsif azp != @client_id
+            raise OmniAuth::Auth0::TokenValidationError.new("Authorized Party (azp) claim mismatch in the ID token; expected (#{@client_id}), found (#{azp})")
+          end
+        end
+      end
+
+      def verify_auth_time(id_token, leeway, max_age)
+        if max_age
+          auth_time = id_token['auth_time']
+          if !auth_time || !auth_time.is_a?(Integer)
+            raise OmniAuth::Auth0::TokenValidationError.new("Authentication Time (auth_time) claim must be a number present in the ID token when Max Age (max_age) is specified")
+          elsif Time.now.to_i >  auth_time + max_age + leeway;
+            raise OmniAuth::Auth0::TokenValidationError.new("Authentication Time (auth_time) claim in the ID token indicates that too much time has passed since the last end-user authentication. Current time (#{Time.now}) is after last auth time (#{Time.at(auth_time + max_age + leeway)})")
+          end
+        end
+      end
     end
   end
 end

data/lib/omniauth/strategies/auth0.rb

@@ -2,9 +2,11 @@
 
 require 'base64'
 require 'uri'
+require 'securerandom'
 require 'omniauth-oauth2'
 require 'omniauth/auth0/jwt_validator'
 require 'omniauth/auth0/telemetry'
+require 'omniauth/auth0/errors'
 
 module OmniAuth
   module Strategies
@@ -48,10 +50,16 @@ module OmniAuth
           )
         end
 
-        # Make sure the ID token can be verified and decoded.
-        auth0_jwt = OmniAuth::Auth0::JWTValidator.new(options)
-        jwt_decoded = auth0_jwt.decode(credentials['id_token'])
-        fail!(:invalid_id_token) unless jwt_decoded.length
+        # Retrieve and remove authorization params from the session
+        session_authorize_params = session['authorize_params'] || {}
+        session.delete('authorize_params')
+
+        auth_scope = session_authorize_params[:scope]
+        if auth_scope.respond_to?(:include?) && auth_scope.include?('openid')
+          # Make sure the ID token can be verified and decoded.
+          auth0_jwt = OmniAuth::Auth0::JWTValidator.new(options)
+          auth0_jwt.verify(credentials['id_token'], session_authorize_params)
+        end
 
         credentials
       end
@@ -78,8 +86,18 @@ module OmniAuth
       def authorize_params
         params = super
         parsed_query = Rack::Utils.parse_query(request.query_string)
-        params['connection'] = parsed_query['connection']
-        params['prompt'] = parsed_query['prompt']
+        %w[connection connection_scope prompt screen_hint].each do |key|
+          params[key] = parsed_query[key] if parsed_query.key?(key)
+        end
+
+        # Generate nonce
+        params[:nonce] = SecureRandom.hex
+        # Generate leeway if none exists
+        params[:leeway] = 60 unless params[:leeway]
+
+        # Store authorize params in the session for token verification
+        session['authorize_params'] = params
+
         params
       end
 
@@ -105,6 +123,12 @@ module OmniAuth
         end
       end
 
+      def callback_phase
+        super
+      rescue OmniAuth::Auth0::TokenValidationError => e
+        fail!(:token_validation_error, e)
+      end
+
       private
 
       # Parse the raw user info.

data/omniauth-auth0.gemspec

@@ -16,15 +16,13 @@ OmniAuth is a library that standardizes multi-provider authentication for web ap
 omniauth-auth0 is the OmniAuth strategy for Auth0.
 }
 
-  s.rubyforge_project = 'omniauth-auth0'
-
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split('\n').map{ |f| File.basename(f) }
   s.require_paths = ['lib']
 
   s.add_runtime_dependency 'omniauth-oauth2', '~> 1.5'
-
+  s.add_runtime_dependency 'omniauth', '~> 1.9'
   s.add_development_dependency 'bundler', '~> 1.9'
   
   s.license = 'MIT'

data/spec/omniauth/auth0/jwt_validator_spec.rb

@@ -12,17 +12,17 @@ describe OmniAuth::Auth0::JWTValidator do
   let(:domain) { 'samples.auth0.com' }
   let(:future_timecode) { 32_503_680_000 }
   let(:past_timecode) { 303_912_000 }
-  let(:jwks_kid) { 'NkJCQzIyQzRBMEU4NjhGNUU4MzU4RkY0M0ZDQzkwOUQ0Q0VGNUMwQg' }
+  let(:valid_jwks_kid) { 'NkJCQzIyQzRBMEU4NjhGNUU4MzU4RkY0M0ZDQzkwOUQ0Q0VGNUMwQg' }
 
   let(:rsa_private_key) do
     OpenSSL::PKey::RSA.generate 2048
   end
 
-  let(:rsa_token_jwks) do
+  let(:valid_jwks) do
     {
       keys: [
         {
-          kid: jwks_kid,
+          kid: valid_jwks_kid,
           x5c: [Base64.encode64(make_cert(rsa_private_key).to_der)]
         }
       ]
@@ -91,29 +91,29 @@ describe OmniAuth::Auth0::JWTValidator do
     end
   end
 
-  describe 'JWT verifier jwks_key' do
+  describe 'JWT verifier jwks key parsing' do
     let(:jwt_validator) do
       make_jwt_validator
     end
 
     before do
-      stub_jwks
+      stub_complete_jwks
     end
 
     it 'should return a key' do
-      expect(jwt_validator.jwks_key(:alg, jwks_kid)).to eq('RS256')
+      expect(jwt_validator.jwks_key(:alg, valid_jwks_kid)).to eq('RS256')
     end
 
     it 'should return an x5c key' do
-      expect(jwt_validator.jwks_key(:x5c, jwks_kid).length).to eq(1)
+      expect(jwt_validator.jwks_key(:x5c, valid_jwks_kid).length).to eq(1)
     end
 
     it 'should return nil if there is not key' do
-      expect(jwt_validator.jwks_key(:auth0, jwks_kid)).to eq(nil)
+      expect(jwt_validator.jwks_key(:auth0, valid_jwks_kid)).to eq(nil)
     end
 
     it 'should return nil if the key ID is invalid' do
-      expect(jwt_validator.jwks_key(:alg, "#{jwks_kid}_invalid")).to eq(nil)
+      expect(jwt_validator.jwks_key(:alg, "#{valid_jwks_kid}_invalid")).to eq(nil)
     end
   end
 
@@ -147,30 +147,38 @@ describe OmniAuth::Auth0::JWTValidator do
     end
   end
 
-  describe 'JWT verifier decode' do
+  describe 'JWT verifier verify' do
     let(:jwt_validator) do
       make_jwt_validator
     end
 
     before do
-      stub_jwks
-      stub_dummy_jwks
+      stub_complete_jwks
+      stub_expected_jwks
     end
 
-    it 'should fail with passed expiration' do
-      payload = {
-        exp: past_timecode
-      }
-      token = make_hs256_token(payload)
+    it 'should fail when JWT is nil' do
+      expect do
+        jwt_validator.verify(nil)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "ID token is required but missing"
+      }))
+    end
+
+    it 'should fail when JWT is not well-formed' do
       expect do
-        jwt_validator.decode(token)
-      end.to raise_error(JWT::ExpiredSignature)
+        jwt_validator.verify('abc.123')
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "ID token could not be decoded"
+      }))
     end
 
     it 'should fail with missing issuer' do
       expect do
-        jwt_validator.decode(make_hs256_token)
-      end.to raise_error(JWT::InvalidIssuerError)
+        jwt_validator.verify(make_hs256_token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Issuer (iss) claim must be a string present in the ID token"
+      }))
     end
 
     it 'should fail with invalid issuer' do
@@ -179,55 +187,287 @@ describe OmniAuth::Auth0::JWTValidator do
       }
       token = make_hs256_token(payload)
       expect do
-        jwt_validator.decode(token)
-      end.to raise_error(JWT::InvalidIssuerError)
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Issuer (iss) claim mismatch in the ID token, expected (https://samples.auth0.com/), found (https://auth0.com/)"
+      }))
     end
 
-    it 'should fail with a future not before' do
+    it 'should fail when subject is missing' do
       payload = {
-        nbf: future_timecode,
-        iss: "https://#{domain}/"
+        iss: "https://#{domain}/",
+        sub: ''
       }
       token = make_hs256_token(payload)
       expect do
-        jwt_validator.decode(token)
-      end.to raise_error(JWT::ImmatureSignature)
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Subject (sub) claim must be a string present in the ID token"
+      }))
     end
 
     it 'should fail with missing audience' do
       payload = {
-        iss: "https://#{domain}/"
+        iss: "https://#{domain}/",
+        sub: 'sub'
       }
       token = make_hs256_token(payload)
       expect do
-        jwt_validator.decode(token)
-      end.to raise_error(JWT::InvalidAudError)
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Audience (aud) claim must be a string or array of strings present in the ID token"
+      }))
     end
 
     it 'should fail with invalid audience' do
       payload = {
         iss: "https://#{domain}/",
+        sub: 'sub',
         aud: 'Auth0'
       }
       token = make_hs256_token(payload)
       expect do
-        jwt_validator.decode(token)
-      end.to raise_error(JWT::InvalidAudError)
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Audience (aud) claim mismatch in the ID token; expected #{client_id} but found Auth0"
+      }))
+    end
+
+    it 'should fail when missing expiration' do
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: client_id
+      }
+
+      token = make_hs256_token(payload)
+      expect do
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Expiration time (exp) claim must be a number present in the ID token"
+      }))
     end
 
-    it 'should decode a valid HS256 token with multiple audiences' do
+    it 'should fail when past expiration' do
       payload = {
         iss: "https://#{domain}/",
-        aud: [
-          client_id,
-          "https://#{domain}/userinfo"
-        ]
+        sub: 'sub',
+        aud: client_id,
+        exp: past_timecode
       }
+
       token = make_hs256_token(payload)
-      expect(jwt_validator.decode(token).length).to eq(2)
+      expect do
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Expiration time (exp) claim error in the ID token; current time (#{Time.now}) is after expiration time (#{Time.at(past_timecode + 60)})"
+      }))
     end
 
-    it 'should decode a standard HS256 token' do
+    it 'should pass when past expiration but within default leeway' do
+      exp = Time.now.to_i - 59
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: client_id,
+        exp: exp,
+        iat: past_timecode
+      }
+
+      token = make_hs256_token(payload)
+      id_token = jwt_validator.verify(token)
+      expect(id_token['exp']).to eq(exp)
+    end
+
+    it 'should fail when past expiration and outside default leeway' do
+      exp = Time.now.to_i - 61
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: client_id,
+        exp: exp,
+        iat: past_timecode
+      }
+
+      token = make_hs256_token(payload)
+      expect do
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Expiration time (exp) claim error in the ID token; current time (#{Time.now}) is after expiration time (#{Time.at(exp + 60)})"
+      }))
+    end
+
+    it 'should fail when missing iat' do
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: client_id,
+        exp: future_timecode
+      }
+
+      token = make_hs256_token(payload)
+      expect do
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Issued At (iat) claim must be a number present in the ID token"
+      }))
+    end
+
+    it 'should fail when authorize params has nonce but nonce is missing in the token' do
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: client_id,
+        exp: future_timecode,
+        iat: past_timecode
+      }
+
+      token = make_hs256_token(payload)
+      expect do
+        jwt_validator.verify(token, { nonce: 'noncey' })
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Nonce (nonce) claim must be a string present in the ID token"
+      }))
+    end
+
+    it 'should fail when authorize params has nonce but token nonce does not match' do
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: client_id,
+        exp: future_timecode,
+        iat: past_timecode,
+        nonce: 'mismatch'
+      }
+
+      token = make_hs256_token(payload)
+      expect do
+        jwt_validator.verify(token, { nonce: 'noncey' })
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Nonce (nonce) claim value mismatch in the ID token; expected (noncey), found (mismatch)"
+      }))
+    end
+    
+    it 'should fail when “aud” is an array of strings and azp claim is not present' do
+      aud = [
+        client_id,
+        "https://#{domain}/userinfo"
+      ]
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: aud,
+        exp: future_timecode,
+        iat: past_timecode
+      }
+
+      token = make_hs256_token(payload)
+      expect do
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Authorized Party (azp) claim must be a string present in the ID token when Audience (aud) claim has multiple values"
+      }))
+    end
+
+    it 'should fail when "azp" claim doesnt match the expected aud' do
+      aud = [
+        client_id,
+        "https://#{domain}/userinfo"
+      ]
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: aud,
+        exp: future_timecode,
+        iat: past_timecode,
+        azp: 'not_expected'
+      }
+
+      token = make_hs256_token(payload)
+      expect do
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Authorized Party (azp) claim mismatch in the ID token; expected (#{client_id}), found (not_expected)"
+      }))
+    end
+
+    it 'should fail when “max_age” sent on the authentication request and this claim is not present' do
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: client_id,
+        exp: future_timecode,
+        iat: past_timecode
+      }
+
+      token = make_hs256_token(payload)
+      expect do
+        jwt_validator.verify(token, { max_age: 60 })
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Authentication Time (auth_time) claim must be a number present in the ID token when Max Age (max_age) is specified"
+      }))
+    end
+
+    it 'should fail when “max_age” sent on the authentication request and this claim added the “max_age” value doesn’t represent a date in the future' do
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: client_id,
+        exp: future_timecode,
+        iat: past_timecode,
+        auth_time: past_timecode
+      }
+
+      token = make_hs256_token(payload)
+      expect do
+        jwt_validator.verify(token, { max_age: 60 })
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Authentication Time (auth_time) claim in the ID token indicates that too much time has passed since the last end-user authentication. Current time (#{Time.now}) is after last auth time (#{Time.at(past_timecode + 60 + 60)})"
+      }))
+    end
+
+    it 'should fail when “max_age” sent on the authentication request and this claim added the “max_age” value doesn’t represent a date in the future, outside the default leeway' do
+      now = Time.now.to_i
+      auth_time = now - 121
+      max_age = 60
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: client_id,
+        exp: future_timecode,
+        iat: past_timecode,
+        auth_time: auth_time
+      }
+
+      token = make_hs256_token(payload)
+      expect do
+        jwt_validator.verify(token, { max_age: max_age })
+        # Time.at(auth_time + max_age + leeway
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Authentication Time (auth_time) claim in the ID token indicates that too much time has passed since the last end-user authentication. Current time (#{Time.now}) is after last auth time (#{Time.at(auth_time + max_age + 60)})"
+      }))
+    end
+
+    it 'should verify when “max_age” sent on the authentication request and this claim added the “max_age” value doesn’t represent a date in the future, outside the default leeway' do
+      now = Time.now.to_i
+      auth_time = now - 119
+      max_age = 60
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: client_id,
+        exp: future_timecode,
+        iat: past_timecode,
+        auth_time: auth_time
+      }
+
+      token = make_hs256_token(payload)
+      id_token = jwt_validator.verify(token, { max_age: max_age })
+      expect(id_token['auth_time']).to eq(auth_time)
+    end
+
+    it 'should fail for RS256 token when kid is incorrect' do
+      domain = 'example.org'
       sub = 'abc123'
       payload = {
         sub: sub,
@@ -236,12 +476,16 @@ describe OmniAuth::Auth0::JWTValidator do
         iat: past_timecode,
         aud: client_id
       }
-      token = make_hs256_token(payload)
-      decoded_token = jwt_validator.decode(token)
-      expect(decoded_token.first['sub']).to eq(sub)
+      invalid_kid = 'invalid-kid'
+      token = make_rs256_token(payload, invalid_kid)
+      expect do
+        verified_token = make_jwt_validator(opt_domain: domain).verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Could not find a public key for Key ID (kid) 'invalid-kid'"
+      }))
     end
 
-    it 'should decode a standard RS256 token' do
+    it 'should fail when RS256 token has invalid signature' do
       domain = 'example.org'
       sub = 'abc123'
       payload = {
@@ -249,12 +493,124 @@ describe OmniAuth::Auth0::JWTValidator do
         exp: future_timecode,
         iss: "https://#{domain}/",
         iat: past_timecode,
+        aud: client_id
+      }
+      token = make_rs256_token(payload) + 'bad'
+      expect do
+        verified_token = make_jwt_validator(opt_domain: domain).verify(token)
+      end.to raise_error(an_instance_of(JWT::VerificationError).and having_attributes({
+        message: "Signature verification raised"
+      }))
+    end
+
+    it 'should fail when algorithm is not RS256 or HS256' do
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'abc123',
+        aud: client_id,
+        exp: future_timecode,
+        iat: past_timecode
+      }
+      token = JWT.encode payload, 'secret', 'HS384'
+      expect do
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(OmniAuth::Auth0::TokenValidationError).and having_attributes({
+        message: "Signature algorithm of HS384 is not supported. Expected the ID token to be signed with RS256 or HS256"
+      }))
+    end
+
+    it 'should fail when HS256 token has invalid signature' do
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'abc123',
+        aud: client_id,
+        exp: future_timecode,
+        iat: past_timecode
+      }
+      token = make_hs256_token(payload, 'bad_secret')
+      expect do
+        # validator is configured to use "CLIENT_SECRET" by default
+        jwt_validator.verify(token)
+      end.to raise_error(an_instance_of(JWT::VerificationError))
+    end
+
+    it 'should verify a valid HS256 token with multiple audiences' do
+      audience = [
+        client_id,
+        "https://#{domain}/userinfo"
+      ]
+      payload = {
+        iss: "https://#{domain}/",
+        sub: 'sub',
+        aud: audience,
+        exp: future_timecode,
+        iat: past_timecode,
+        azp: client_id
+      }
+      token = make_hs256_token(payload)
+      id_token = jwt_validator.verify(token)
+      expect(id_token['aud']).to eq(audience)
+    end
+
+    it 'should verify a standard HS256 token' do
+      sub = 'abc123'
+      payload = {
+        iss: "https://#{domain}/",
+        sub: sub,
         aud: client_id,
-        kid: jwks_kid
+        exp: future_timecode,
+        iat: past_timecode
+      }
+      token = make_hs256_token(payload)
+      verified_token = jwt_validator.verify(token)
+      expect(verified_token['sub']).to eq(sub)
+    end
+
+    it 'should verify a standard RS256 token' do
+      domain = 'example.org'
+      sub = 'abc123'
+      payload = {
+        sub: sub,
+        exp: future_timecode,
+        iss: "https://#{domain}/",
+        iat: past_timecode,
+        aud: client_id
       }
       token = make_rs256_token(payload)
-      decoded_token = make_jwt_validator(opt_domain: domain).decode(token)
-      expect(decoded_token.first['sub']).to eq(sub)
+      verified_token = make_jwt_validator(opt_domain: domain).verify(token)
+      expect(verified_token['sub']).to eq(sub)
+    end
+
+    it 'should verify a HS256 JWT signature when calling verify signature directly' do
+      sub = 'abc123'
+        payload = {
+          iss: "https://#{domain}/",
+          sub: sub,
+          aud: client_id,
+          exp: future_timecode,
+          iat: past_timecode
+        }
+        token = make_hs256_token(payload)
+        verified_token_signature = jwt_validator.verify_signature(token)
+        expect(verified_token_signature[0]).to eq('CLIENT_SECRET')
+        expect(verified_token_signature[1]).to eq('HS256')
+    end
+
+    it 'should verify a RS256 JWT signature verify signature directly' do
+      domain = 'example.org'
+      sub = 'abc123'
+      payload = {
+        sub: sub,
+        exp: future_timecode,
+        iss: "https://#{domain}/",
+        iat: past_timecode,
+        aud: client_id
+      }
+      token = make_rs256_token(payload)
+      verified_token_signature = make_jwt_validator(opt_domain: domain).verify_signature(token)
+      expect(verified_token_signature.length).to be(2)
+      expect(verified_token_signature[0]).to be_a(OpenSSL::PKey::RSA)
+      expect(verified_token_signature[1]).to eq('RS256')
     end
   end
 
@@ -271,14 +627,16 @@ describe OmniAuth::Auth0::JWTValidator do
     OmniAuth::Auth0::JWTValidator.new(opts)
   end
 
-  def make_hs256_token(payload = nil)
+  def make_hs256_token(payload = nil, secret = nil)
     payload = { sub: 'abc123' } if payload.nil?
-    JWT.encode payload, client_secret, 'HS256'
+    secret = client_secret if secret.nil?
+    JWT.encode payload, secret, 'HS256'
   end
 
-  def make_rs256_token(payload = nil)
+  def make_rs256_token(payload = nil, kid = nil)
     payload = { sub: 'abc123' } if payload.nil?
-    JWT.encode payload, rsa_private_key, 'RS256', kid: jwks_kid
+    kid = valid_jwks_kid if kid.nil?
+    JWT.encode payload, rsa_private_key, 'RS256', kid: kid
   end
 
   def make_cert(private_key)
@@ -306,7 +664,7 @@ describe OmniAuth::Auth0::JWTValidator do
     cert.sign private_key, OpenSSL::Digest::SHA1.new
   end
 
-  def stub_jwks
+  def stub_complete_jwks
     stub_request(:get, 'https://samples.auth0.com/.well-known/jwks.json')
       .to_return(
         headers: { 'Content-Type' => 'application/json' },
@@ -315,18 +673,11 @@ describe OmniAuth::Auth0::JWTValidator do
       )
   end
 
-  def stub_bad_jwks
-    stub_request(:get, 'https://samples.auth0.com/.well-known/jwks-bad.json')
-      .to_return(
-        status: 404
-      )
-  end
-
-  def stub_dummy_jwks
+  def stub_expected_jwks
     stub_request(:get, 'https://example.org/.well-known/jwks.json')
       .to_return(
         headers: { 'Content-Type' => 'application/json' },
-        body: rsa_token_jwks,
+        body: valid_jwks,
         status: 200
       )
   end