cerner-oauth1a 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 253284a714a5a69821159cef402c2e228c7d747a15f31dc4d8842bb7e44ee6fe
-  data.tar.gz: da348e1e5cfa763a78afd32e3bd252719670c3feb7bce4cad7995023cee384c4
+  metadata.gz: d923d6f574a554d2995de4c00c3a97924a3750f424f1b141accd4eb239401e70
+  data.tar.gz: 9f72e25bc46201b3a071b1b34e8450d40fd9db0e29ac02c1ab6153742357cdf9
 SHA512:
-  metadata.gz: 28473811816dc086d4eacdd3eff65d0fe5455087f5e1e5c3fb0bfb3e04ba38a819707536e40968ad157c9efe1e8756bbd8f3f87cd620c796fd3da750a247efa7
-  data.tar.gz: ae958bbf7456257dbef524a1e6073d3f9ce0c7988516f24c18f7011b689d769e86d0340fdbca7de44daf0c1b0bdbcf14768112ab13fd6f3b8573846fe284e63f
+  metadata.gz: d752ee31d28626e1bdf135e20347f240b9658025cfffdb46d4e2b409aaba7ec2222ba30263b0aeedce0491168af8ea65dfc267b45f1345e77c6773cbbf767c7b
+  data.tar.gz: 848a69c486be5a55861fce17cc8cc9da4102ddda4b9540c37eb19ada65b83628a28c8d9571bdf2ef7b7ed0d0e545b294da4ecd92aed891daeb9221172adf05de

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 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

data/README.md

@@ -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

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,7 +1,9 @@
 # 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
@@ -38,6 +40,7 @@ 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: params[:oauth_nonce],
           timestamp: params[:oauth_timestamp],
@@ -48,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, but may be nil, 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, but may be nil, 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,7 +92,7 @@ module Cerner
       #                                 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.
@@ -109,53 +115,122 @@ module Cerner
         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 = timestamp ? convert_to_time(timestamp) : nil
+        @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 = {}
-        tuples[:realm] = @realm if @realm
-        tuples[:oauth_version] = '1.0'
-        tuples[:oauth_signature_method] = @signature_method
-        tuples[:oauth_signature] = sig
-        tuples[:oauth_consumer_key] = @consumer_key
-        tuples[:oauth_nonce] = @nonce if @nonce
-        tuples[:oauth_timestamp] = @timestamp.tv_sec if @timestamp
-        tuples[: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
@@ -166,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)
@@ -182,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)
@@ -200,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")
 
@@ -222,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
 
@@ -274,43 +365,19 @@ 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)
+        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)
@@ -330,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
@@ -368,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 @signature == expected_signature
+
+        raise OAuthError.new('signature is not valid', nil, 'signature_invalid', nil, @realm)
       end
     end
   end

data/lib/cerner/oauth1a/access_token_agent.rb

@@ -5,10 +5,12 @@ require 'cerner/oauth1a/access_token'
 require 'cerner/oauth1a/keys'
 require 'cerner/oauth1a/oauth_error'
 require 'cerner/oauth1a/cache'
+require 'cerner/oauth1a/internal'
 require 'cerner/oauth1a/protocol'
+require 'cerner/oauth1a/signature'
 require 'cerner/oauth1a/version'
 require 'json'
-require 'net/https'
+require 'net/http'
 require 'securerandom'
 require 'uri'
 
@@ -70,9 +72,11 @@ module Cerner
       #                                    realm that's extracted from :access_token_url. If nil,
       #                                    this will be initalized with the DEFAULT_REALM_ALIASES.
       #                                    (optional, default: nil)
+      #             :signature_method    - A String to set the signature method to use. MUST be
+      #                                    PLAINTEXT or HMAC-SHA1. (optional, default: 'PLAINTEXT')
       #
       # Raises ArgumentError if access_token_url, consumer_key or consumer_key is nil; if
-      #                      access_token_url is an invalid URI.
+      #                      access_token_url is an invalid URI; if signature_method is invalid.
       def initialize(
         access_token_url:,
         consumer_key:,
@@ -81,7 +85,8 @@ module Cerner
         read_timeout: 5,
         cache_keys: true,
         cache_access_tokens: true,
-        realm_aliases: nil
+        realm_aliases: nil,
+        signature_method: 'PLAINTEXT'
       )
         raise ArgumentError, 'consumer_key is nil' unless consumer_key
         raise ArgumentError, 'consumer_secret is nil' unless consumer_secret
@@ -89,7 +94,7 @@ module Cerner
         @consumer_key = consumer_key
         @consumer_secret = consumer_secret
 
-        @access_token_url = convert_to_http_uri(access_token_url)
+        @access_token_url = Internal.convert_to_http_uri(url: access_token_url, name: 'access_token_url')
         @realm = Protocol.realm_for(@access_token_url)
         @realm_aliases = realm_aliases
         @realm_aliases ||= DEFAULT_REALM_ALIASES[@realm]
@@ -99,6 +104,9 @@ module Cerner
 
         @keys_cache = cache_keys ? Cache.instance : nil
         @access_token_cache = cache_access_tokens ? Cache.instance : nil
+
+        @signature_method = signature_method || 'PLAINTEXT'
+        raise ArgumentError, 'signature_method is invalid' unless Signature::METHODS.include?(@signature_method)
       end
 
       # Public: Retrieves the service provider keys from the configured Access Token service endpoint
@@ -107,7 +115,7 @@ module Cerner
       #
       # keys_version - The version identifier of the keys to retrieve. This corresponds to the
       #                KeysVersion parameter of the oauth_token.
-      # keywords     - The additional, optional keyword arguments for this method
+      # keywords     - The keyword arguments:
       #               :ignore_cache - A flag for indicating that the cache should be ignored and a
       #                               new Access Token should be retrieved.
       #
@@ -135,7 +143,7 @@ module Cerner
       # This method will use the #generate_accessor_secret, #generate_nonce and #generate_timestamp methods to
       # interact with the service, which can be overridden via a sub-class, if desired.
       #
-      # keywords - The additional, optional keyword arguments for this method
+      # keywords - The keyword arguments:
       #            :principal    - An optional principal identifier, which is passed via the
       #                            xoauth_principal protocol parameter.
       #            :ignore_cache - A flag for indicating that the cache should be ignored and a new
@@ -147,19 +155,20 @@ module Cerner
       # Raises StandardError sub-classes for any issues interacting with the service, such as networking issues.
       def retrieve(principal: nil, ignore_cache: false)
         cache_key = "#{@consumer_key}&#{principal}"
+
         if @access_token_cache && !ignore_cache
           cache_entry = @access_token_cache.get('cerner-oauth1a/access-tokens', cache_key)
           return cache_entry.value if cache_entry
         end
 
         # generate token request info
-        nonce = generate_nonce
         timestamp = generate_timestamp
         accessor_secret = generate_accessor_secret
 
-        request = retrieve_prepare_request(timestamp, nonce, accessor_secret, principal)
+        request = retrieve_prepare_request(timestamp: timestamp, accessor_secret: accessor_secret, principal: principal)
         response = http_client.request(request)
-        access_token = retrieve_handle_response(response, timestamp, nonce, accessor_secret)
+        access_token =
+          retrieve_handle_response(response: response, timestamp: timestamp, accessor_secret: accessor_secret)
         @access_token_cache&.put('cerner-oauth1a/access-tokens', cache_key, Cache::AccessTokenEntry.new(access_token))
         access_token
       end
@@ -175,14 +184,14 @@ module Cerner
       #
       # Returns a String containing the nonce.
       def generate_nonce
-        SecureRandom.hex
+        Internal.generate_nonce
       end
 
       # Public: Generate a Timestamp for invocations of the Access Token service.
       #
       # Returns an Integer representing the number of seconds since the epoch.
       def generate_timestamp
-        Time.now.to_i
+        Internal.generate_timestamp
       end
 
       # Public: Determines if the passed realm is equivalent to the configured
@@ -224,46 +233,41 @@ module Cerner
         http
       end
 
-      # Internal: Convert an Access Token URL into a URI with some verification checks
-      #
-      # access_token_url - A String URL or a URI instance
-      # Returns a URI::HTTP or URI::HTTPS
-      #
-      # Raises ArgumentError if access_token_url is nil, invalid or not an HTTP/HTTPS URI
-      def convert_to_http_uri(access_token_url)
-        raise ArgumentError, 'access_token_url is nil' unless access_token_url
-
-        if access_token_url.is_a?(URI)
-          uri = access_token_url
-        else
-          begin
-            uri = URI(access_token_url)
-          rescue URI::InvalidURIError
-            # raise argument error with cause
-            raise ArgumentError, 'access_token_url is invalid'
-          end
-        end
-
-        raise ArgumentError, 'access_token_url must be an HTTP or HTTPS URI' unless uri.is_a?(URI::HTTP)
-
-        uri
-      end
-
       # Internal: Prepare a request for #retrieve
-      def retrieve_prepare_request(timestamp, nonce, accessor_secret, principal)
+      def retrieve_prepare_request(accessor_secret:, timestamp:, principal: nil)
         # construct a POST request
         request = Net::HTTP::Post.new(@access_token_url)
         # setup the data to construct the POST's message
-        params = [
-          [:oauth_consumer_key, @consumer_key],
-          [:oauth_signature_method, 'PLAINTEXT'],
-          [:oauth_version, '1.0'],
-          [:oauth_timestamp, timestamp],
-          [:oauth_nonce, nonce],
-          [:oauth_signature, "#{@consumer_secret}&"],
-          [:oauth_accessor_secret, accessor_secret]
-        ]
-        params << [:xoauth_principal, principal.to_s] if principal
+        params = {
+          oauth_consumer_key: Protocol.percent_encode(@consumer_key),
+          oauth_signature_method: @signature_method,
+          oauth_version: '1.0',
+          oauth_accessor_secret: accessor_secret
+        }
+        params[:xoauth_principal] = principal.to_s if principal
+
+        if @signature_method == 'PLAINTEXT'
+          sig = Signature.sign_via_plaintext(client_shared_secret: @consumer_secret, token_shared_secret: '')
+        elsif @signature_method == 'HMAC-SHA1'
+          params[:oauth_timestamp] = timestamp
+          params[:oauth_nonce] = generate_nonce
+          signature_base_string =
+            Signature.build_signature_base_string(
+              http_method: 'POST', fully_qualified_url: @access_token_url, params: params
+            )
+          sig =
+            Signature.sign_via_hmacsha1(
+              client_shared_secret: @consumer_secret,
+              token_shared_secret: '',
+              signature_base_string: signature_base_string
+            )
+        else
+          raise OAuthError.new('signature_method is invalid', nil, 'signature_method_rejected', nil, @realm)
+        end
+
+        params[:oauth_signature] = sig
+
+        params = params.map { |n, v| [n, v] }
         # set the POST's body as a URL form-encoded string
         request.set_form(params, MIME_WWW_FORM_URL_ENCODED, charset: 'UTF-8')
         request['Accept'] = MIME_WWW_FORM_URL_ENCODED
@@ -273,22 +277,22 @@ module Cerner
       end
 
       # Internal: Handle a response for #retrieve
-      def retrieve_handle_response(response, timestamp, nonce, accessor_secret)
+      def retrieve_handle_response(response:, timestamp:, accessor_secret:)
         case response
         when Net::HTTPSuccess
           # Parse the HTTP response and convert it into a Symbol-keyed Hash
           tuples = Protocol.parse_url_query_string(response.body)
           # Use the parsed response to construct the AccessToken
-          access_token = AccessToken.new(
-            accessor_secret: accessor_secret,
-            consumer_key: @consumer_key,
-            expires_at: timestamp + tuples[:oauth_expires_in].to_i,
-            nonce: nonce,
-            timestamp: timestamp,
-            token: tuples[:oauth_token],
-            token_secret: tuples[:oauth_token_secret],
-            realm: @realm
-          )
+          access_token =
+            AccessToken.new(
+              accessor_secret: accessor_secret,
+              consumer_key: @consumer_key,
+              expires_at: timestamp + tuples[:oauth_expires_in].to_i,
+              token: tuples[:oauth_token],
+              token_secret: tuples[:oauth_token_secret],
+              signature_method: @signature_method,
+              realm: @realm
+            )
           access_token
         else
           # Extract any OAuth Problems reported in the response
@@ -300,10 +304,11 @@ module Cerner
 
       # Internal: Prepare a request for #retrieve_keys
       def retrieve_keys_prepare_request(keys_version)
-        request = Net::HTTP::Get.new(URI("#{@access_token_url}/keys/#{keys_version}"))
+        keys_url = URI("#{@access_token_url}/keys/#{keys_version}")
+        request = Net::HTTP::Get.new(keys_url)
         request['Accept'] = 'application/json'
         request['User-Agent'] = user_agent_string
-        request['Authorization'] = retrieve.authorization_header
+        request['Authorization'] = retrieve.authorization_header(fully_qualified_url: keys_url)
         request
       end
 
@@ -319,9 +324,7 @@ module Cerner
           raise OAuthError.new('RSA public key retrieved was invalid', nil, nil, nil, @realm) unless rsa_key
 
           Keys.new(
-            version: keys_version,
-            aes_secret_key: Base64.decode64(aes_key),
-            rsa_public_key: Base64.decode64(rsa_key)
+            version: keys_version, aes_secret_key: Base64.decode64(aes_key), rsa_public_key: Base64.decode64(rsa_key)
           )
         else
           # Extract any OAuth Problems reported in the response

data/lib/cerner/oauth1a/cache.rb

@@ -6,14 +6,14 @@ module Cerner
     class Cache
       @cache_instance_lock = Mutex.new
 
+      # Internal: Sets the singleton instance.
       def self.instance=(cache_impl)
         raise ArgumentError, 'cache_impl must not be nil' unless cache_impl
 
-        @cache_instance_lock.synchronize do
-          @cache_instance = cache_impl
-        end
+        @cache_instance_lock.synchronize { @cache_instance = cache_impl }
       end
 
+      # Internal: Gets the singleton instance.
       def self.instance
         @cache_instance_lock.synchronize do
           return @cache_instance if @cache_instance
@@ -27,12 +27,14 @@ module Cerner
         attr_reader :value
         attr_reader :expires_in
 
+        # Internal: Constructs an instance.
         def initialize(keys, expires_in)
           @value = keys
           @expires_in = expires_in
           @expires_at = Time.now.utc.to_i + @expires_in
         end
 
+        # Internal: Check if the entry is expired.
         def expired?(now)
           @expires_at <= now
         end
@@ -42,25 +44,29 @@ module Cerner
       class AccessTokenEntry
         attr_reader :value
 
+        # Internal: Constructs an instance.
         def initialize(access_token)
           @value = access_token
         end
 
+        # Internal: Returns the number of seconds until the entry expires.
         def expires_in
           @value.expires_at.to_i - Time.now.utc.to_i
         end
 
+        # Internal: Check if the entry is expired.
         def expired?(now)
           @value.expired?(now: now)
         end
       end
 
-      ONE_HOUR = 3600
+      ONE_HOUR = 3_600
       TWENTY_FOUR_HOURS = 24 * ONE_HOUR
 
       # Internal: The default implementation of the Cerner::OAuth1a::Cache interface.
       # This implementation just maintains a capped list of entries in memory.
       class DefaultCache < Cerner::OAuth1a::Cache
+        # Internal: Constructs an instance.
         def initialize(max:)
           super()
           @max = max
@@ -68,6 +74,7 @@ module Cerner
           @entries = {}
         end
 
+        # Internal: Puts an entry into the cache.
         def put(namespace, key, entry)
           @lock.synchronize do
             now = Time.now.utc.to_i
@@ -77,6 +84,7 @@ module Cerner
           end
         end
 
+        # Internal: Gets an entry from the cache.
         def get(namespace, key)
           @lock.synchronize do
             prune_expired(Time.now.utc.to_i)

data/lib/cerner/oauth1a/cache_rails.rb

@@ -28,13 +28,7 @@ module Cerner
       # key       - The key for the cache entries, which is qualified by namespace.
       # entry     - The entry to be stored in the cache.
       def put(namespace, key, entry)
-        @cache.write(
-          key,
-          entry,
-          namespace: namespace,
-          expires_in: entry.expires_in,
-          race_condition_ttl: 5
-        )
+        @cache.write(key, entry, namespace: namespace, expires_in: entry.expires_in, race_condition_ttl: 5)
       end
 
       # Internal: Retrieves the entry, if available, from the cache store.

data/lib/cerner/oauth1a/internal.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'uri'
+
+module Cerner
+  module OAuth1a
+    # Internal: Internal utility methods
+    module Internal
+      # Internal: Convert a time value into a Time instance.
+      #
+      # keywords - The keyword arguments:
+      #            :time - Time or any object with a #to_i that returns an Integer.
+      #            :name - The parameter name of the data for invoking methods.
+      #
+      # Returns a Time instance in the UTC time zone.
+      def self.convert_to_time(time:, name: 'time')
+        raise ArgumentError, "#{name} is nil" unless time
+
+        time.is_a?(Time) ? time.utc : Time.at(time.to_i).utc
+      end
+
+      # Internal: Convert an fully qualified URL String into a URI with some verification checks
+      #
+      # keywords - The keyword arguments:
+      #            :url  - A String or a URI instance to convert to a URI instance.
+      #            :name - The parameter name of the URL for invoking methods.
+      #
+      # Returns a URI::HTTP or URI::HTTPS
+      #
+      # Raises ArgumentError if url is nil, invalid or not an HTTP/HTTPS URI
+      def self.convert_to_http_uri(url:, name: 'url')
+        raise ArgumentError, "#{name} is nil" unless url
+
+        if url.is_a?(URI)
+          uri = url
+        else
+          begin
+            uri = URI(url)
+          rescue URI::InvalidURIError
+            # raise argument error with cause
+            raise ArgumentError, "#{name} is invalid"
+          end
+        end
+
+        raise ArgumentError, "#{name} must be an HTTP or HTTPS URI" unless uri.is_a?(URI::HTTP)
+
+        uri
+      end
+
+      # Internal: Generate a Nonce for invocations of the Access Token service.
+      #
+      # Returns a String containing the nonce.
+      def self.generate_nonce
+        SecureRandom.hex
+      end
+
+      # Internal: Generate a Timestamp for invocations of the Access Token service.
+      #
+      # Returns an Integer representing the number of seconds since the epoch.
+      def self.generate_timestamp
+        Time.now.to_i
+      end
+    end
+  end
+end

data/lib/cerner/oauth1a/protocol.rb

@@ -6,6 +6,18 @@ module Cerner
   module OAuth1a
     # Public: OAuth 1.0a protocol utilities.
     module Protocol
+      # Public: Encodes the passed text using the percent encoding variant described in the OAuth
+      # 1.0a specification.
+      #
+      # Reference: https://tools.ietf.org/html/rfc5849#section-3.6
+      #
+      # text - A String containing the text to encode.
+      #
+      # Returns a String that has been encoded.
+      def self.percent_encode(text)
+        URI.encode_www_form_component(text).gsub('+', '%20')
+      end
+
       # Public: Parses a URL-encoded query string into a Hash with symbolized keys.
       #
       # query - String containing a URL-encoded query string to parse.
@@ -73,17 +85,12 @@ module Cerner
       #
       # Returns the String containing the generated value or nil if params is nil or empty.
       def self.generate_authorization_header(params)
-        return nil unless params && !params.empty?
+        return unless params && !params.empty?
 
         realm = "realm=\"#{params.delete(:realm)}\"" if params[:realm]
-        realm += ', ' if realm && !params.empty?
-
-        encoded_params =
-          params.map do |k, v|
-            k = URI.encode_www_form_component(k).gsub('+', '%20')
-            v = URI.encode_www_form_component(v).gsub('+', '%20')
-            "#{k}=\"#{v}\""
-          end
+        realm += ',' if realm && !params.empty?
+
+        encoded_params = params.map { |k, v| "#{percent_encode(k)}=\"#{percent_encode(v)}\"" }
 
         "OAuth #{realm}#{encoded_params.join(',')}"
       end

data/lib/cerner/oauth1a/signature.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'cerner/oauth1a/protocol'
+require 'openssl'
+require 'uri'
+
+module Cerner
+  module OAuth1a
+    # Public: OAuth 1.0a signature utilities.
+    module Signature
+      METHODS = ['PLAINTEXT', 'HMAC-SHA1'].freeze
+
+      # Public: Creates a PLAINTEXT signature.
+      #
+      # Reference: https://tools.ietf.org/html/rfc5849#section-3.4.4
+      #
+      # keywords - The keyword arguments:
+      #            :client_shared_secret - Either the Accessor Secret or the Consumer Secret.
+      #            :token_shared_secret  - The Token Secret.
+      #
+      # Returns a String containing the signature.
+      def self.sign_via_plaintext(client_shared_secret:, token_shared_secret:)
+        client_shared_secret = Protocol.percent_encode(client_shared_secret)
+        token_shared_secret = Protocol.percent_encode(token_shared_secret)
+        "#{client_shared_secret}&#{token_shared_secret}"
+      end
+
+      # Public: Creates a HMAC-SHA1 signature.
+      #
+      # Reference: https://tools.ietf.org/html/rfc5849#section-3.4.2
+      #
+      # keywords - The keyword arguments:
+      #            :client_shared_secret  - Either the Accessor Secret or the Consumer Secret.
+      #            :token_shared_secret   - The Token Secret.
+      #            :signature_base_string - The Signature Base String to sign. See
+      #                                     Signature.build_signature_base_string.
+      #
+      # Returns a String containing the signature.
+      def self.sign_via_hmacsha1(client_shared_secret:, token_shared_secret:, signature_base_string:)
+        client_shared_secret = Protocol.percent_encode(client_shared_secret)
+        token_shared_secret = Protocol.percent_encode(token_shared_secret)
+        signature_key = "#{client_shared_secret}&#{token_shared_secret}"
+        signature = OpenSSL::HMAC.digest('sha1', signature_key, signature_base_string)
+        encoded_signature = Base64.strict_encode64(signature)
+        encoded_signature
+      end
+
+      # Public: Normalizes a text value as an HTTP method name for use in constructing a Signature
+      # Base String.
+      #
+      # Reference https://tools.ietf.org/html/rfc5849#section-3.4.1.1
+      #
+      # http_method - A String or Symbol containing an HTTP method name.
+      #
+      # Returns the normalized value as a String.
+      #
+      # Raises ArgumentError if http_method is nil.
+      def self.normalize_http_method(http_method)
+        raise ArgumentError, 'http_method is nil' unless http_method
+
+        # accepts Symbol or String
+        Protocol.percent_encode(http_method.to_s.upcase)
+      end
+
+      # Public: Normalizes a fully qualified URL for use as the Base String URI in constructing a
+      # Signature Base String.
+      #
+      # Reference https://tools.ietf.org/html/rfc5849#section-3.4.1.2
+      #
+      # fully_qualified_url - A String or URI that contains the scheme, host, port (optional) and
+      #                       path of a URL.
+      #
+      # Returns the normalized value as a String.
+      #
+      # Raises ArgumentError if fully_qualified_url is nil.
+      def self.normalize_base_string_uri(fully_qualified_url)
+        raise ArgumentError, 'fully_qualified_url is nil' unless fully_qualified_url
+
+        u = fully_qualified_url.is_a?(URI) ? fully_qualified_url : URI(fully_qualified_url)
+
+        Protocol.percent_encode(URI("#{u.scheme}://#{u.host}:#{u.port}#{u.path}").to_s)
+      end
+
+      # Public: Normalizes the parameters (query string and OAuth parameters) for use as the
+      # request parameters in constructing a Signature Base String.
+      #
+      # Reference: https://tools.ietf.org/html/rfc5849#section-3.4.1.3.2
+      #
+      # params - A Hash of name/value pairs representing the parameters. The keys and values of the
+      #          Hash will be assumed to be represented by the value returned from #to_s.
+      #
+      # Returns the normalized value as a String.
+      #
+      # Raises ArgumentError if params is nil.
+      def self.normalize_parameters(params)
+        raise ArgumentError, 'params is nil' unless params
+
+        encoded_params =
+          params.map do |name, value|
+            result = [Protocol.percent_encode(name.to_s), nil]
+            result[1] =
+              if value.is_a?(Array)
+                value = value.map { |e| Protocol.percent_encode(e.to_s) }
+                value.sort
+              else
+                Protocol.percent_encode(value.to_s)
+              end
+            result
+          end
+
+        sorted_params = encoded_params.sort_by { |name, _| name }
+
+        exploded_params =
+          sorted_params.map do |pair|
+            name = pair[0]
+            value = pair[1]
+            if value.is_a?(Array)
+              value.map { |e| "#{name}=#{e}" }
+            else
+              "#{name}=#{value}"
+            end
+          end
+        exploded_params.flatten!
+
+        joined_params = exploded_params.join('&')
+        Protocol.percent_encode(joined_params)
+      end
+
+      # Public: Builds a Signature Base String.
+      #
+      # keywords - The keyword arguments:
+      #            :http_method         - A String or Symbol containing an HTTP method name.
+      #            :fully_qualified_url - A String or URI that contains the scheme, host, port
+      #                                   (optional) and path of a URL.
+      #            :params              - A Hash of name/value pairs representing the parameters.
+      #                                   The keys and values of the Hash will be assumed to be
+      #                                   represented by the value returned from #to_s.
+      #
+      # Returns the Signature Base String as a String.
+      #
+      # Raises ArgumentError if http_method, fully_qualified_url or params is nil.
+      def self.build_signature_base_string(http_method:, fully_qualified_url:, params:)
+        raise ArgumentError, 'http_method is nil' unless http_method
+        raise ArgumentError, 'fully_qualified_url is nil' unless fully_qualified_url
+        raise ArgumentError, 'params is nil' unless params
+
+        parts = [
+          normalize_http_method(http_method),
+          normalize_base_string_uri(fully_qualified_url),
+          normalize_parameters(params)
+        ]
+        parts.join('&')
+      end
+    end
+  end
+end

data/lib/cerner/oauth1a/version.rb

@@ -2,6 +2,6 @@
 
 module Cerner
   module OAuth1a
-    VERSION = '2.4.0'
+    VERSION = '2.5.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cerner-oauth1a
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.5.0
 platform: ruby
 authors:
 - Nathan Beyer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-12-05 00:00:00.000000000 Z
+date: 2019-12-16 00:00:00.000000000 Z
 dependencies: []
 description: |
   A minimal dependency library for interacting with a Cerner OAuth 1.0a Access
@@ -30,9 +30,11 @@ files:
 - lib/cerner/oauth1a/access_token_agent.rb
 - lib/cerner/oauth1a/cache.rb
 - lib/cerner/oauth1a/cache_rails.rb
+- lib/cerner/oauth1a/internal.rb
 - lib/cerner/oauth1a/keys.rb
 - lib/cerner/oauth1a/oauth_error.rb
 - lib/cerner/oauth1a/protocol.rb
+- lib/cerner/oauth1a/signature.rb
 - lib/cerner/oauth1a/version.rb
 homepage: http://github.com/cerner/cerner-oauth1a
 licenses: