cerner-oauth1a 2.3.0 → 2.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97551b442a5cf8e81197726dd7a076fd49ed7e33c5fd2bbf87e27e6368abea4b
-  data.tar.gz: de3ec59f5a000715440492c550bebe4f9d3490ce53fd9d88490a08f7539d7208
+  metadata.gz: a554af1b8a4a44ff14a05c9fb71517046cdb1a5bf677b5a4792eaa7d01423b83
+  data.tar.gz: 3f16a0c5584bae17e6edfcecb277c92d04da581fcc883f687b91719089543b8e
 SHA512:
-  metadata.gz: a98454061208707ddab9eb7a79b867f8acbcd88fa2d42c9e68411a04fa645004e20d282e39efec0f9e91a7a57d88551588324c933e76b8336313a38c24747964
-  data.tar.gz: 6573bfbd3c6ff73b83b957b9b6e784486079b194c9d09c1c4803b16f0336b51376d39ddab369ffdfe5d13ffaa129ecb727256c27f4683169250f7c01fa9498bd
+  metadata.gz: 6b501e8559461f9a2a24aa9515403f6ee3d071786005f56eb1e466560b5b53a78f4992fc8c4b8ae9c17a819263c401b7474b732a21b261bb7890902e88a69f05
+  data.tar.gz: 0ee901ddfa558db983229086f6f5e4cd20de2c9575c20a6457e09862b5e2d1eeadd662e856de1851e6528b834a0a5dcfe714f01a8b521d542a2927e14aac4552

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+# v2.5.3
+Use a constant time compare algorithm for checking a signature
+
+# v2.5.2
+Adjust `Cerner::OAuth1a::Protocol.parse_www_authenticate_header` to handle parameters
+that are either tokens or quoted strings.
+
+# v2.5.1
+Address `instance variable @cache_instance not initialized` warning
+
+# v2.5.0
+Add Consumer and Provider support for HMAC-SHA1 signatures.
+
+Added a Cerner::OAuth1a::Protocol.percent_encode method.
+
+Correctly percent encodes PLAINTEXT signature parts (client shared secret and token
+shared secret) before constructing PLAINTEXT signature.
+
+# v2.4.0
+Handle nonce and timestamp as optional fields Per
+https://tools.ietf.org/html/rfc5849#section-3.1, the oauth_timestamp and oauth_nonce
+fields may be omitted when PLAINTEXT signatures are used. This commit make the APIs
+related to those two fields treat the data as optional.
+
 # v2.3.0
 Added Protection Realm Equivalence feature to Cerner::OAuth1a::AccessTokenAgent,
 which is used by Cerner::OAuth1a::AccessToken#authenticate when comparing realms.

data/NOTICE

@@ -1,4 +1,4 @@
-Copyright 2019 Cerner Innovation, Inc.
+Copyright 2020 Cerner Innovation, Inc.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://api.travis-ci.com/cerner/cerner-oauth1a.svg)](https://travis-ci.com/cerner/cerner-oauth1a)
 [![Gem Version](http://img.shields.io/gem/v/cerner-oauth1a.svg)](https://rubygems.org/gems/cerner-oauth1a)
-[![Code Climate](http://img.shields.io/codeclimate/github/cerner/cerner-oauth1a.svg)](https://codeclimate.com/github/cerner/cerner-oauth1a)
+[![AwesomeCode Status](https://awesomecode.io/projects/48ece237-ac9c-49c9-859a-3a825968339b/status)](https://awesomecode.io/repos/cerner/cerner-oauth1a)
 
 A minimal dependency library for interacting with a Cerner OAuth 1.0a Access Token Service for
 invoking Cerner OAuth 1.0a protected services or implementing Cerner OAuth 1.0a authentication.
@@ -38,7 +38,53 @@ for implementing a Ruby-based service.
     # Invoke the API's HTTP endpoint and use the AccessToken to generate an Authorization header
     response = http.request_get(uri.path, Authorization: access_token.authorization_header)
 
+### Consumer HMAC-SHA1 Signature Method
+
+The preferred and default signature method is PLAINTEXT, as all communication SHOULD be via TLS. However, if HMAC-SHA1 signatures are necessary, then this can be achieved by constructing AccessTokenAgent as follows:
+
+    agent = Cerner::OAuth1a::AccessTokenAgent.new(
+      access_token_url: 'https://oauth-api.cerner.com/oauth/access',
+      consumer_key: 'CONSUMER_KEY',
+      consumer_secret: 'CONSUMER_SECRET',
+      signature_method: 'HMAC-SHA1'
+    )
+
+To use the AccessToken requires additional parameters to be passed when constructing the Authorization header. The HTTP method, the URL being invoked and all request parameters. The request parameters should include all parameters passed in the query string and those passed in the body if the Content-Type of the body is `application/x-www-form-urlencoded`. See the specification for more details.
+
+#### Consumer HMAC-SHA1 Signature Method Examples
+
+GET with no request parameters
+
+    uri = URI('https://authz-demo-api.cerner.com/me')
+    # ...
+    authz_header = access_token.authorization_header(fully_qualified_url: uri)
+
+GET with request parameters in URL
+
+    uri = URI('https://authz-demo-api.cerner.com/me?name=value')
+    # ...
+    authz_header = access_token.authorization_header(fully_qualified_url: uri)
+
+POST with request parameters (form post)
+
+    authz_header = access_token.authorization_header(
+      http_method: 'POST'
+      fully_qualified_url: 'https://example/path',
+      request_params: {
+        sort: 'asc',
+        field: ['name', 'desc'] # sending the field multiple times
+      }
+    )
+
+PUT with no request parameters (entity body)
+
+    authz_header = access_token.authorization_header(
+      http_method: 'PUT'
+      fully_qualified_url: 'https://example/path'
+    )
+
 ### Access Token Reuse
+
 Generally, you'll want to use an Access Token more than once. Access Tokens can be reused, but
 they do expire, so you'll need to acquire new tokens after one expires. All of the expiration
 information is contained in the AccessToken class and you can easily determine if a token is
@@ -77,6 +123,21 @@ implement that:
     # (xoauth_principal)
     consumer_principal = access_token.consumer_principal
 
+### Service Provider HMAC-SHA1 Signature Method
+
+The preferred and default signature method is PLAINTEXT, as all communication SHOULD be via TLS. However, if HMAC-SHA1 signatures are necessary, then this can be achieved by passing additional informational to the `authenticate` method.
+
+    begin
+      results = access_token.authenticate(
+        agent,
+        http_method: request.method,
+        fully_qualified_url: request.original_url,
+        request_params: request.parameters
+      )
+    rescue OAuthError => e
+      # respond with a 401
+    end
+
 ## Caching
 
 The AccessTokenAgent class provides built-in memory caching. AccessTokens and Keys are cached
@@ -90,6 +151,7 @@ cache to use an implementation that stores the AccessTokens and Keys within Rail
 
 ## References
 * https://wiki.ucern.com/display/public/reference/Cerner%27s+OAuth+Specification
+  * https://tools.ietf.org/html/rfc5849
   * http://oauth.net/core/1.0a
   * http://oauth.pbwiki.com/ProblemReporting
 * https://wiki.ucern.com/display/public/reference/Accessing+Cerner%27s+Web+Services+Using+OAuth+1.0a
@@ -149,7 +211,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md)
 
 # LICENSE
 
-Copyright 2019 Cerner Innovation, Inc.
+Copyright 2020 Cerner Innovation, Inc.
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
 

data/lib/cerner/oauth1a.rb

@@ -6,4 +6,5 @@ require 'cerner/oauth1a/cache'
 require 'cerner/oauth1a/cache_rails' if defined?(::Rails) && defined?(::Rails.cache)
 require 'cerner/oauth1a/keys'
 require 'cerner/oauth1a/protocol'
+require 'cerner/oauth1a/signature'
 require 'cerner/oauth1a/version'

data/lib/cerner/oauth1a/access_token.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
+require 'cerner/oauth1a/internal'
 require 'cerner/oauth1a/oauth_error'
 require 'cerner/oauth1a/protocol'
+require 'cerner/oauth1a/signature'
 require 'uri'
 
 module Cerner
   module OAuth1a
-
     # Public: A Cerner OAuth 1.0a Access Token and related request parameters for use in Consumer or
     # Service Provider use cases.
     class AccessToken
@@ -29,10 +30,6 @@ module Cerner
         missing_params = []
         consumer_key = params[:oauth_consumer_key]
         missing_params << :oauth_consumer_key if consumer_key.nil? || consumer_key.empty?
-        nonce = params[:oauth_nonce]
-        missing_params << :oauth_nonce if nonce.nil? || nonce.empty?
-        timestamp = params[:oauth_timestamp]
-        missing_params << :oauth_timestamp if timestamp.nil? || timestamp.empty?
         token = params[:oauth_token]
         missing_params << :oauth_token if token.nil? || token.empty?
         signature_method = params[:oauth_signature_method]
@@ -43,9 +40,10 @@ module Cerner
         raise OAuthError.new('', nil, 'parameter_absent', missing_params) unless missing_params.empty?
 
         AccessToken.new(
+          accessor_secret: params[:oauth_accessor_secret],
           consumer_key: consumer_key,
-          nonce: nonce,
-          timestamp: timestamp,
+          nonce: params[:oauth_nonce],
+          timestamp: params[:oauth_timestamp],
           token: token,
           signature_method: signature_method,
           signature: signature,
@@ -53,15 +51,18 @@ module Cerner
         )
       end
 
-      # Returns a String, but may be nil, with the Accessor Secret related to this token.
+      # Returns a String, but may be nil, with the Accessor Secret (oauth_accessor_secret) related
+      # to this token. Note: nil and empty are considered equivalent.
       attr_reader :accessor_secret
       # Returns a String with the Consumer Key (oauth_consumer_key) related to this token.
       attr_reader :consumer_key
       # Returns a Time, but may be nil, which represents the moment when this token expires.
       attr_reader :expires_at
-      # Returns a String with the Nonce (oauth_nonce) related to this token.
+      # Returns a String, but may be nil, with the Nonce (oauth_nonce) related to this token. This
+      # is generally only populated when parsing a token for authentication.
       attr_reader :nonce
-      # Returns a Time, which represents the moment when this token was created (oauth_timestamp).
+      # Returns a Time, but may be nil, with the Timestamp (oauth_timestamp) related to this token.
+      # This is generally only populated when parsing a token for authentication.
       attr_reader :timestamp
       # Returns a String with the Token (oauth_token).
       attr_reader :token
@@ -86,85 +87,150 @@ module Cerner
       #             :expires_at       - An optional Time representing the expiration moment or any
       #                                 object responding to to_i that represents the expiration
       #                                 moment as the number of seconds since the epoch.
-      #             :nonce            - The required String representing the nonce.
-      #             :timestamp        - A required Time representing the creation moment or any
+      #             :nonce            - The optional String representing the nonce.
+      #             :timestamp        - A optional Time representing the creation moment or any
       #                                 object responding to to_i that represents the creation
       #                                 moment as the number of seconds since the epoch.
       #             :token            - The required String representing the token.
-      #             :token_secret     - The required String representing the token secret.
+      #             :token_secret     - The optional String representing the token secret.
       #             :signature_method - The optional String representing the signature method.
       #                                 Defaults to PLAINTEXT.
       #             :signature        - The optional String representing the signature.
-      #                                 Defaults to nil.
       #             :realm            - The optional String representing the protection realm.
-      #                                 Defaults to nil.
       #
-      # Raises ArgumentError if consumer_key, nonce, timestamp, token or signature_method is nil.
+      # Raises ArgumentError if consumer_key or token is nil.
       def initialize(
         accessor_secret: nil,
         consumer_key:,
         expires_at: nil,
-        nonce:,
+        nonce: nil,
         signature: nil,
         signature_method: 'PLAINTEXT',
-        timestamp:,
+        timestamp: nil,
         token:,
         token_secret: nil,
         realm: nil
       )
         raise ArgumentError, 'consumer_key is nil' unless consumer_key
-        raise ArgumentError, 'nonce is nil' unless nonce
-        raise ArgumentError, 'timestamp is nil' unless timestamp
         raise ArgumentError, 'token is nil' unless token
 
         @accessor_secret = accessor_secret || nil
-        @authorization_header = nil
         @consumer_key = consumer_key
         @consumer_principal = nil
-        @expires_at = expires_at ? convert_to_time(expires_at) : nil
+        @expires_at = expires_at ? Internal.convert_to_time(time: expires_at, name: 'expires_at') : nil
         @nonce = nonce
         @signature = signature
         @signature_method = signature_method || 'PLAINTEXT'
-        @timestamp = convert_to_time(timestamp)
+        @timestamp = timestamp ? Internal.convert_to_time(time: timestamp, name: 'timestamp') : nil
         @token = token
         @token_secret = token_secret || nil
         @realm = realm || nil
       end
 
       # Public: Generates a value suitable for use as an HTTP Authorization header. If #signature is
-      # nil, then #accessor_secret and #token_secret will be used to build a signature via the
-      # PLAINTEXT method.
+      # nil, then a signature will be generated based on the #signature_method.
+      #
+      # PLAINTEXT Signature (preferred)
+      #
+      # When using PLAINTEXT signatures, no additional arguments are necessary. If an oauth_nonce
+      # or oauth_timestamp are desired, then the values can be passed via the :nonce and :timestamp
+      # keyword arguments. The actual signature will be constructed from the Accessor Secret
+      # (#accessor_secret) and the Token Secret (#token_secret).
+      #
+      # HMAC-SHA1 Signature
+      #
+      # When using HMAC-SHA1 signatures, access to the HTTP request information is necessary. This
+      # requies that additional information is passed via the keyword arguments. The required
+      # information includes the HTTP method (see :http_method), the host authority & path (see
+      # :fully_qualified_url) and the request parameters (see :fully_qualified_url and
+      # :request_params).
+      #
+      # keywords - The keyword arguments:
+      #            :nonce               - The optional String containing a Nonce to generate the
+      #                                   header with HMAC-SHA1 signatures. When nil, a Nonce will
+      #                                   be generated.
+      #            :timestamp           - The optional Time or #to_i compliant object containing a
+      #                                   Timestamp to generate the header with HMAC-SHA1
+      #                                   signatures. When nil, a Timestamp will be generated.
+      #            :http_method         - The optional String or Symbol containing a HTTP Method for
+      #                                   constructing the HMAC-SHA1 signature. When nil, the value
+      #                                   defualts to 'GET'.
+      #            :fully_qualified_url - The optional String or URI containing the fully qualified
+      #                                   URL of the HTTP API being invoked for constructing the
+      #                                   HMAC-SHA1 signature. If the URL contains a query string,
+      #                                   the parameters will be extracted and used in addition to
+      #                                   the :request_params keyword argument.
+      #            :request_params      - The optional Hash of name/value pairs containing the
+      #                                   request parameters of the HTTP API being invoked for
+      #                                   constructing the HMAC-SHA1 signature. Parameters passed
+      #                                   here will override and augment those passed in the
+      #                                   :fully_qualified_url parameter. The parameter names and
+      #                                   values MUST be unencoded. See
+      #                                   Protocol#parse_url_query_string for help with decoding an
+      #                                   encoded query string.
       #
       # Returns a String representation of the access token.
       #
       # Raises Cerner::OAuth1a::OAuthError if #signature_method is not PLAINTEXT or if a signature
       # can't be determined.
-      def authorization_header
-        return @authorization_header if @authorization_header
-
-        unless @signature_method == 'PLAINTEXT'
-          raise OAuthError.new('signature_method must be PLAINTEXT', nil, 'signature_method_rejected', nil, @realm)
-        end
+      def authorization_header(
+        nonce: nil, timestamp: nil, http_method: 'GET', fully_qualified_url: nil, request_params: nil
+      )
+        oauth_params = {}
+        oauth_params[:oauth_version] = '1.0'
+        oauth_params[:oauth_signature_method] = @signature_method
+        oauth_params[:oauth_consumer_key] = @consumer_key
+        oauth_params[:oauth_nonce] = nonce if nonce
+        oauth_params[:oauth_timestamp] = Internal.convert_to_time(time: timestamp, name: 'timestamp').to_i if timestamp
+        oauth_params[:oauth_token] = @token
 
         if @signature
           sig = @signature
-        elsif @accessor_secret && @token_secret
-          sig = "#{@accessor_secret}&#{@token_secret}"
         else
-          raise OAuthError.new('accessor_secret or token_secret is nil', nil, 'parameter_absent', nil, @realm)
+          # NOTE: @accessor_secret is always used, but an empty value is allowed and project assumes
+          # that nil implies an empty value
+
+          raise OAuthError.new('token_secret is nil', nil, 'parameter_absent', nil, @realm) unless @token_secret
+
+          if @signature_method == 'PLAINTEXT'
+            sig =
+              Signature.sign_via_plaintext(client_shared_secret: @accessor_secret, token_shared_secret: @token_secret)
+          elsif @signature_method == 'HMAC-SHA1'
+            http_method ||= 'GET' # default to HTTP GET
+            request_params ||= {} # default to no request params
+            oauth_params[:oauth_nonce] = Internal.generate_nonce unless oauth_params[:oauth_nonce]
+            oauth_params[:oauth_timestamp] = Internal.generate_timestamp unless oauth_params[:oauth_timestamp]
+
+            begin
+              fully_qualified_url = Internal.convert_to_http_uri(url: fully_qualified_url, name: 'fully_qualified_url')
+            rescue ArgumentError => ae
+              raise OAuthError.new(ae.message, nil, 'parameter_absent', nil, @realm)
+            end
+
+            query_params = fully_qualified_url.query ? Protocol.parse_url_query_string(fully_qualified_url.query) : {}
+            request_params = query_params.merge(request_params)
+
+            params = request_params.merge(oauth_params)
+            signature_base_string =
+              Signature.build_signature_base_string(
+                http_method: http_method, fully_qualified_url: fully_qualified_url, params: params
+              )
+
+            sig =
+              Signature.sign_via_hmacsha1(
+                client_shared_secret: @accessor_secret,
+                token_shared_secret: @token_secret,
+                signature_base_string: signature_base_string
+              )
+          else
+            raise OAuthError.new('signature_method is invalid', nil, 'signature_method_rejected', nil, @realm)
+          end
         end
 
-        tuples = {
-          realm: @realm,
-          oauth_version: '1.0',
-          oauth_signature_method: @signature_method,
-          oauth_signature: sig,
-          oauth_consumer_key: @consumer_key,
-          oauth_nonce: @nonce,
-          oauth_timestamp: @timestamp.tv_sec,
-          oauth_token: @token
-        }
-        @authorization_header = Protocol.generate_authorization_header(tuples)
+        oauth_params[:realm] = @realm if @realm
+        oauth_params[:oauth_signature] = sig
+
+        Protocol.generate_authorization_header(oauth_params)
       end
 
       # Public: Authenticates the #token against the #consumer_key, #signature and side-channel
@@ -175,13 +241,27 @@ module Cerner
       # access_token_agent - An instance of Cerner::OAuth1a::AccessTokenAgent configured with
       #                      appropriate credentials to retrieve secrets via
       #                      Cerner::OAuth1a::AccessTokenAgent#retrieve_keys.
+      # keywords           - The keyword arguments:
+      #                      :http_method         - An optional String or Symbol containing an HTTP
+      #                                             method name. (default: 'GET')
+      #                      :fully_qualified_url - An optional String or URI that contains the
+      #                                             scheme, host, port (optional) and path of a URL.
+      #                      :request_params      - An optional Hash of name/value pairs
+      #                                             representing the request parameters. The keys
+      #                                             and values  of the Hash will be assumed to be
+      #                                             represented by the value returned from #to_s.
       #
       # Returns a Hash (symbolized keys) of any extra parameters within #token (oauth_token),
       # if authentication succeeds. In most scenarios, the Hash will be empty.
       #
       # Raises ArgumentError if access_token_agent is nil
       # Raises Cerner::OAuth1a::OAuthError with an oauth_problem if authentication fails.
-      def authenticate(access_token_agent)
+      def authenticate(
+        access_token_agent,
+        http_method: 'GET',
+        fully_qualified_url: nil,
+        request_params: nil
+      )
         raise ArgumentError, 'access_token_agent is nil' unless access_token_agent
 
         if @realm && !access_token_agent.realm_eql?(@realm)
@@ -191,10 +271,6 @@ module Cerner
         # Set realm to the provider's realm if it's not already set
         @realm ||= access_token_agent.realm
 
-        unless @signature_method == 'PLAINTEXT'
-          raise OAuthError.new('signature_method must be PLAINTEXT', nil, 'signature_method_rejected', nil, @realm)
-        end
-
         tuples = Protocol.parse_url_query_string(@token)
 
         unless @consumer_key == tuples.delete(:ConsumerKey)
@@ -209,7 +285,13 @@ module Cerner
         # RSASHA1 param gets consumed in #verify_token, so remove it too
         tuples.delete(:RSASHA1)
 
-        verify_signature(keys, tuples.delete(:HMACSecrets))
+        verify_signature(
+          keys: keys,
+          hmac_secrets: tuples.delete(:HMACSecrets),
+          http_method: http_method,
+          fully_qualified_url: fully_qualified_url,
+          request_params: request_params
+        )
 
         @consumer_principal = tuples.delete(:"Consumer.Principal")
 
@@ -231,7 +313,7 @@ module Cerner
         # if @expires_at is nil, return true now
         return true unless @expires_at
 
-        now = convert_to_time(now)
+        now = Internal.convert_to_time(time: now, name: 'now')
         now.tv_sec >= @expires_at.tv_sec - fudge_sec
       end
 
@@ -283,59 +365,22 @@ module Cerner
 
       private
 
-      # Internal: Used by #initialize and #expired? to convert data into a Time instance.
-      #
-      # time - Time or any object with a #to_i the returns an Integer.
-      #
-      # Returns a Time instance in the UTC time zone.
-      def convert_to_time(time)
-        raise ArgumentError, 'time is nil' unless time
-
-        if time.is_a? Time
-          time.utc
-        else
-          Time.at(time.to_i).utc
-        end
-      end
-
       # Internal: Used by #authenticate to verify the expiration time.
-      #
-      # expires_on - The ExpiresOn parameter of oauth_token
-      #
-      # Raises OAuthError if the parameter is invalid or expired
       def verify_expiration(expires_on)
         unless expires_on
-          raise OAuthError.new(
-            'token missing ExpiresOn',
-            nil,
-            'oauth_parameters_rejected',
-            'oauth_token',
-            @realm
-          )
+          raise OAuthError.new('token missing ExpiresOn', nil, 'oauth_parameters_rejected', 'oauth_token', @realm)
         end
 
-        expires_on = convert_to_time(expires_on)
-        now = convert_to_time(Time.now)
-        if now.tv_sec >= expires_on.tv_sec
-          raise OAuthError.new(
-            'token has expired',
-            nil,
-            'token_expired',
-            nil,
-            @realm
-          )
-        end
+        expires_on = Internal.convert_to_time(time: expires_on, name: 'expires_on')
+        now = Internal.convert_to_time(time: Time.now)
+
+        raise OAuthError.new('token has expired', nil, 'token_expired', nil, @realm) if now.tv_sec >= expires_on.tv_sec
       end
 
+      # Internal: Used by #authenticate to load the keys
       def load_keys(access_token_agent, keys_version)
         unless keys_version
-          raise OAuthError.new(
-            'token missing KeysVersion',
-            nil,
-            'oauth_parameters_rejected',
-            'oauth_token',
-            @realm
-          )
+          raise OAuthError.new('token missing KeysVersion', nil, 'oauth_parameters_rejected', 'oauth_token', @realm)
         end
 
         begin
@@ -352,24 +397,14 @@ module Cerner
       end
 
       # Internal: Used by #authenticate to verify the oauth_token value.
-      #
-      # keys - The Keys instance that contains the key used to sign the oauth_token
-      #
-      # Raises OAuthError if the parameter is not authentic
       def verify_token(keys)
-        unless keys.verify_rsasha1_signature(@token)
-          raise OAuthError.new('token is not authentic', nil, 'oauth_parameters_rejected', 'oauth_token', @realm)
-        end
+        return if keys.verify_rsasha1_signature(@token)
+
+        raise OAuthError.new('token is not authentic', nil, 'oauth_parameters_rejected', 'oauth_token', @realm)
       end
 
       # Internal: Used by #authenticate to verify the request signature.
-      #
-      # keys         - The Keys instance that contains the key used to encrypt the HMACSecrets
-      # hmac_secrets - The HMACSecrets parameter of oauth_token
-      #
-      # Raises OAuthError if there is no signature, the parameter is invalid or the signature does
-      # not match the secrets
-      def verify_signature(keys, hmac_secrets)
+      def verify_signature(keys:, hmac_secrets:, http_method:, fully_qualified_url:, request_params:)
         unless @signature
           raise OAuthError.new('missing signature', nil, 'oauth_parameters_absent', 'oauth_signature', @realm)
         end
@@ -390,11 +425,58 @@ module Cerner
         end
 
         secrets_parts = Protocol.parse_url_query_string(secrets)
-        expected_signature = "#{secrets_parts[:ConsumerSecret]}&#{secrets_parts[:TokenSecret]}"
 
-        unless @signature == expected_signature
-          raise OAuthError.new('signature is not valid', nil, 'signature_invalid', nil, @realm)
+        if @signature_method == 'PLAINTEXT'
+          expected_signature =
+            Signature.sign_via_plaintext(
+              client_shared_secret: secrets_parts[:ConsumerSecret], token_shared_secret: secrets_parts[:TokenSecret]
+            )
+        elsif @signature_method == 'HMAC-SHA1'
+          http_method ||= 'GET' # default to HTTP GET
+          request_params ||= {} # default to no request params
+          oauth_params = {
+            oauth_version: '1.0', # assumes version is present
+            oauth_signature_method: 'HMAC-SHA1',
+            oauth_consumer_key: @consumer_key,
+            oauth_nonce: @nonce,
+            oauth_timestamp: @timestamp.to_i,
+            oauth_token: @token
+          }
+
+          begin
+            fully_qualified_url = Internal.convert_to_http_uri(url: fully_qualified_url, name: 'fully_qualified_url')
+          rescue ArgumentError => ae
+            raise OAuthError.new(ae.message, nil, 'parameter_absent', nil, @realm)
+          end
+
+          query_params = fully_qualified_url.query ? Protocol.parse_url_query_string(fully_qualified_url.query) : {}
+          request_params = query_params.merge(request_params)
+
+          params = request_params.merge(oauth_params)
+          signature_base_string =
+            Signature.build_signature_base_string(
+              http_method: http_method, fully_qualified_url: fully_qualified_url, params: params
+            )
+
+          expected_signature =
+            Signature.sign_via_hmacsha1(
+              client_shared_secret: secrets_parts[:ConsumerSecret],
+              token_shared_secret: secrets_parts[:TokenSecret],
+              signature_base_string: signature_base_string
+            )
+        else
+          raise OAuthError.new(
+            'signature_method must be PLAINTEXT or HMAC-SHA1',
+            nil,
+            'signature_method_rejected',
+            nil,
+            @realm
+          )
         end
+
+        return if Internal.constant_time_compare(@signature, expected_signature)
+
+        raise OAuthError.new('signature is not valid', nil, 'signature_invalid', nil, @realm)
       end
     end
   end