oauth2 1.4.0 → 2.0.3

data/lib/oauth2/access_token.rb

@@ -1,30 +1,36 @@
+# frozen_string_literal: true
+
 module OAuth2
-  class AccessToken
-    attr_reader :client, :token, :expires_in, :expires_at, :params
-    attr_accessor :options, :refresh_token
+  class AccessToken # rubocop:disable Metrics/ClassLength
+    attr_reader :client, :token, :expires_in, :expires_at, :expires_latency, :params
+    attr_accessor :options, :refresh_token, :response
 
     class << self
       # Initializes an AccessToken from a Hash
       #
-      # @param [Client] the OAuth2::Client instance
-      # @param [Hash] a hash of AccessToken property values
-      # @return [AccessToken] the initalized AccessToken
+      # @param client [Client] the OAuth2::Client instance
+      # @param hash [Hash] a hash of AccessToken property values
+      # @return [AccessToken] the initialized AccessToken
       def from_hash(client, hash)
         hash = hash.dup
-        new(client, hash.delete('access_token') || hash.delete(:access_token), hash)
+        new(client, hash.delete('access_token') || hash.delete(:access_token) || hash.delete('token') || hash.delete(:token), hash)
       end
 
       # Initializes an AccessToken from a key/value application/x-www-form-urlencoded string
       #
       # @param [Client] client the OAuth2::Client instance
       # @param [String] kvform the application/x-www-form-urlencoded string
-      # @return [AccessToken] the initalized AccessToken
+      # @return [AccessToken] the initialized AccessToken
       def from_kvform(client, kvform)
         from_hash(client, Rack::Utils.parse_query(kvform))
       end
+
+      def contains_token?(hash)
+        hash.key?('access_token') || hash.key?('id_token') || hash.key?('token')
+      end
     end
 
-    # Initalize an AccessToken
+    # Initialize an AccessToken
     #
     # @param [Client] client the OAuth2::Client instance
     # @param [String] token the Access Token value
@@ -32,25 +38,28 @@ module OAuth2
     # @option opts [String] :refresh_token (nil) the refresh_token value
     # @option opts [FixNum, String] :expires_in (nil) the number of seconds in which the AccessToken will expire
     # @option opts [FixNum, String] :expires_at (nil) the epoch time in seconds in which AccessToken will expire
+    # @option opts [FixNum, String] :expires_latency (nil) the number of seconds by which AccessToken validity will be reduced to offset latency, @version 2.0+
     # @option opts [Symbol] :mode (:header) the transmission mode of the Access Token parameter value
     #    one of :header, :body or :query
     # @option opts [String] :header_format ('Bearer %s') the string format to use for the Authorization header
     # @option opts [String] :param_name ('access_token') the parameter name to use for transmission of the
     #    Access Token value in :body or :query transmission mode
-    def initialize(client, token, opts = {}) # rubocop:disable Metrics/AbcSize
+    def initialize(client, token, opts = {})
       @client = client
       @token = token.to_s
       opts = opts.dup
-      [:refresh_token, :expires_in, :expires_at].each do |arg|
+      %i[refresh_token expires_in expires_at expires_latency].each do |arg|
         instance_variable_set("@#{arg}", opts.delete(arg) || opts.delete(arg.to_s))
       end
       @expires_in ||= opts.delete('expires')
       @expires_in &&= @expires_in.to_i
-      @expires_at &&= @expires_at.to_i
+      @expires_at &&= convert_expires_at(@expires_at)
+      @expires_latency &&= @expires_latency.to_i
       @expires_at ||= Time.now.to_i + @expires_in if @expires_in
-      @options = {:mode          => opts.delete(:mode) || :header,
-                  :header_format => opts.delete(:header_format) || 'Bearer %s',
-                  :param_name    => opts.delete(:param_name) || 'access_token'}
+      @expires_at -= @expires_latency if @expires_latency
+      @options = {mode: opts.delete(:mode) || :header,
+                  header_format: opts.delete(:header_format) || 'Bearer %s',
+                  param_name: opts.delete(:param_name) || 'access_token'}
       @params = opts
     end
 
@@ -72,28 +81,32 @@ module OAuth2
     #
     # @return [Boolean]
     def expired?
-      expires? && (expires_at < Time.now.to_i)
+      expires? && (expires_at <= Time.now.to_i)
     end
 
     # Refreshes the current Access Token
     #
     # @return [AccessToken] a new AccessToken
     # @note options should be carried over to the new AccessToken
-    def refresh!(params = {})
+    def refresh(params = {}, access_token_opts = {})
       raise('A refresh_token is not available') unless refresh_token
+
       params[:grant_type] = 'refresh_token'
       params[:refresh_token] = refresh_token
-      new_token = @client.get_token(params)
+      new_token = @client.get_token(params, access_token_opts)
       new_token.options = options
       new_token.refresh_token = refresh_token unless new_token.refresh_token
       new_token
     end
+    # A compatibility alias
+    # @note does not modify the receiver, so bang is not the default method
+    alias refresh! refresh
 
     # Convert AccessToken to a hash which can be used to rebuild itself with AccessToken.from_hash
     #
     # @return [Hash] a hash of AccessToken property values
     def to_hash
-      params.merge(:access_token => token, :refresh_token => refresh_token, :expires_at => expires_at)
+      params.merge(access_token: token, refresh_token: refresh_token, expires_at: expires_at)
     end
 
     # Make a request with the Access Token
@@ -101,7 +114,7 @@ module OAuth2
     # @param [Symbol] verb the HTTP request method
     # @param [String] path the HTTP URL path of the request
     # @param [Hash] opts the options to make the request with
-    # @see Client#request
+    #   @see Client#request
     def request(verb, path, opts = {}, &block)
       configure_authentication!(opts)
       @client.request(verb, path, opts, &block)
@@ -149,7 +162,7 @@ module OAuth2
 
   private
 
-    def configure_authentication!(opts) # rubocop:disable MethodLength, Metrics/AbcSize
+    def configure_authentication!(opts)
       case options[:mode]
       when :header
         opts[:headers] ||= {}
@@ -162,12 +175,18 @@ module OAuth2
         if opts[:body].is_a?(Hash)
           opts[:body][options[:param_name]] = token
         else
-          opts[:body] << "&#{options[:param_name]}=#{token}"
+          opts[:body] += "&#{options[:param_name]}=#{token}"
         end
         # @todo support for multi-part (file uploads)
       else
         raise("invalid :mode option of #{options[:mode]}")
       end
     end
+
+    def convert_expires_at(expires_at)
+      Time.iso8601(expires_at.to_s).to_i
+    rescue ArgumentError
+      expires_at.to_i
+    end
   end
 end

data/lib/oauth2/authenticator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'base64'
 
 module OAuth2
@@ -25,13 +27,17 @@ module OAuth2
         apply_basic_auth(params)
       when :request_body
         apply_params_auth(params)
+      when :tls_client_auth
+        apply_client_id(params)
+      when :private_key_jwt
+        params
       else
         raise NotImplementedError
       end
     end
 
     def self.encode_basic_auth(user, password)
-      'Basic ' + Base64.encode64(user + ':' + password).delete("\n")
+      "Basic #{Base64.strict_encode64("#{user}:#{password}")}"
     end
 
   private
@@ -39,7 +45,18 @@ module OAuth2
     # Adds client_id and client_secret request parameters if they are not
     # already set.
     def apply_params_auth(params)
-      {'client_id' => id, 'client_secret' => secret}.merge(params)
+      result = {}
+      result['client_id'] = id unless id.nil?
+      result['client_secret'] = secret unless secret.nil?
+      result.merge(params)
+    end
+
+    # When using schemes that don't require the client_secret to be passed i.e TLS Client Auth,
+    # we don't want to send the secret
+    def apply_client_id(params)
+      result = {}
+      result['client_id'] = id unless id.nil?
+      result.merge(params)
     end
 
     # Adds an `Authorization` header with Basic Auth credentials if and only if
@@ -47,10 +64,10 @@ module OAuth2
     def apply_basic_auth(params)
       headers = params.fetch(:headers, {})
       headers = basic_auth_header.merge(headers)
-      params.merge(:headers => headers)
+      params.merge(headers: headers)
     end
 
-    # @see https://tools.ietf.org/html/rfc2617#section-2
+    # @see https://datatracker.ietf.org/doc/html/rfc2617#section-2
     def basic_auth_header
       {'Authorization' => self.class.encode_basic_auth(id, secret)}
     end

data/lib/oauth2/client.rb

@@ -1,9 +1,16 @@
+# frozen_string_literal: true
+
 require 'faraday'
 require 'logger'
 
 module OAuth2
+  ConnectionError = Class.new(Faraday::ConnectionFailed)
+  TimeoutError = Class.new(Faraday::TimeoutError)
+
   # The OAuth2::Client class
   class Client # rubocop:disable Metrics/ClassLength
+    RESERVED_PARAM_KEYS = %w[headers parse].freeze
+
     attr_reader :id, :secret, :site
     attr_accessor :options
     attr_writer :connection
@@ -14,17 +21,19 @@ module OAuth2
     #
     # @param [String] client_id the client_id value
     # @param [String] client_secret the client_secret value
-    # @param [Hash] opts the options to create the client with
-    # @option opts [String] :site the OAuth2 provider site host
-    # @option opts [String] :redirect_uri the absolute URI to the Redirection Endpoint for use in authorization grants and token exchange
-    # @option opts [String] :authorize_url ('/oauth/authorize') absolute or relative URL path to the Authorization endpoint
-    # @option opts [String] :token_url ('/oauth/token') absolute or relative URL path to the Token endpoint
-    # @option opts [Symbol] :token_method (:post) HTTP method to use to request token (:get or :post)
-    # @option opts [Symbol] :auth_scheme (:basic_auth) HTTP method to use to authorize request (:basic_auth or :request_body)
-    # @option opts [Hash] :connection_opts ({}) Hash of connection options to pass to initialize Faraday with
-    # @option opts [FixNum] :max_redirects (5) maximum number of redirects to follow
-    # @option opts [Boolean] :raise_errors (true) whether or not to raise an OAuth2::Error
-    #  on responses with 400+ status codes
+    # @param [Hash] options the options to create the client with
+    # @option options [String] :site the OAuth2 provider site host
+    # @option options [String] :redirect_uri the absolute URI to the Redirection Endpoint for use in authorization grants and token exchange
+    # @option options [String] :authorize_url ('/oauth/authorize') absolute or relative URL path to the Authorization endpoint
+    # @option options [String] :token_url ('/oauth/token') absolute or relative URL path to the Token endpoint
+    # @option options [Symbol] :token_method (:post) HTTP method to use to request token (:get, :post, :post_with_query_string)
+    # @option options [Symbol] :auth_scheme (:basic_auth) HTTP method to use to authorize request (:basic_auth or :request_body)
+    # @option options [Hash] :connection_opts ({}) Hash of connection options to pass to initialize Faraday with
+    # @option options [FixNum] :max_redirects (5) maximum number of redirects to follow
+    # @option options [Boolean] :raise_errors (true) whether or not to raise an OAuth2::Error on responses with 400+ status codes
+    # @option options [Logger] :logger (::Logger.new($stdout)) which logger to use when OAUTH_DEBUG is enabled
+    # @option options [Proc] :extract_access_token proc that takes the client and the response Hash and extracts the access token from the response (DEPRECATED)
+    # @option options [Class] :access_token_class [Class] class of access token for easier subclassing OAuth2::AccessToken, @version 2.0+
     # @yield [builder] The Faraday connection builder
     def initialize(client_id, client_secret, options = {}, &block)
       opts = options.dup
@@ -32,20 +41,25 @@ module OAuth2
       @secret = client_secret
       @site = opts.delete(:site)
       ssl = opts.delete(:ssl)
-      @options = {:authorize_url    => '/oauth/authorize',
-                  :token_url        => '/oauth/token',
-                  :token_method     => :post,
-                  :auth_scheme      => :request_body,
-                  :connection_opts  => {},
-                  :connection_build => block,
-                  :max_redirects    => 5,
-                  :raise_errors     => true}.merge(opts)
+      warn('OAuth2::Client#initialize argument `extract_access_token` will be removed in oauth2 v3. Refactor to use `access_token_class`.') if opts[:extract_access_token]
+      @options = {
+        authorize_url: 'oauth/authorize',
+        token_url: 'oauth/token',
+        token_method: :post,
+        auth_scheme: :basic_auth,
+        connection_opts: {},
+        connection_build: block,
+        max_redirects: 5,
+        raise_errors: true,
+        logger: ::Logger.new($stdout),
+        access_token_class: AccessToken,
+      }.merge(opts)
       @options[:connection_opts][:ssl] = ssl if ssl
     end
 
     # Set the site host
     #
-    # @param [String] the OAuth2 provider site host
+    # @param value [String] the OAuth2 provider site host
     def site=(value)
       @connection = nil
       @site = value
@@ -53,15 +67,16 @@ module OAuth2
 
     # The Faraday connection object
     def connection
-      @connection ||= begin
-        conn = Faraday.new(site, options[:connection_opts])
-        if options[:connection_build]
-          conn.build do |b|
-            options[:connection_build].call(b)
+      @connection ||=
+        Faraday.new(site, options[:connection_opts]) do |builder|
+          oauth_debug_logging(builder)
+          if options[:connection_build]
+            options[:connection_build].call(builder)
+          else
+            builder.request :url_encoded             # form-encode POST params
+            builder.adapter Faraday.default_adapter  # make requests with Net::HTTP
           end
         end
-        conn
-      end
     end
 
     # The authorize endpoint URL of the OAuth2 provider
@@ -80,6 +95,9 @@ module OAuth2
     end
 
     # Makes a request relative to the specified site root.
+    # Updated HTTP 1.1 specification (IETF RFC 7231) relaxed the original constraint (IETF RFC 2616),
+    #   allowing the use of relative URLs in Location headers.
+    # @see https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.2
     #
     # @param [Symbol] verb one of :get, :post, :put, :delete
     # @param [String] url URL path of request
@@ -90,34 +108,36 @@ module OAuth2
     # @option opts [Boolean] :raise_errors whether or not to raise an OAuth2::Error on 400+ status
     #   code response for this request.  Will default to client option
     # @option opts [Symbol] :parse @see Response::initialize
-    # @yield [req] The Faraday request
-    def request(verb, url, opts = {}) # rubocop:disable CyclomaticComplexity, MethodLength, Metrics/AbcSize
-      connection.response :logger, ::Logger.new($stdout) if ENV['OAUTH_DEBUG'] == 'true'
-
-      url = connection.build_url(url, opts[:params]).to_s
-
-      response = connection.run_request(verb, url, opts[:body], opts[:headers]) do |req|
-        yield(req) if block_given?
-      end
-      response = Response.new(response, :parse => opts[:parse])
+    # @option opts [Symbol] :snaky @see Response::initialize
+    # @yield [req] @see Faraday::Connection#run_request
+    def request(verb, url, opts = {}, &block)
+      response = execute_request(verb, url, opts, &block)
 
       case response.status
       when 301, 302, 303, 307
         opts[:redirect_count] ||= 0
         opts[:redirect_count] += 1
         return response if opts[:redirect_count] > options[:max_redirects]
+
         if response.status == 303
           verb = :get
           opts.delete(:body)
         end
-        request(verb, response.headers['location'], opts)
+        location = response.headers['location']
+        if location
+          full_location = response.response.env.url.merge(location)
+          request(verb, full_location, opts)
+        else
+          error = Error.new(response)
+          raise(error, "Got #{response.status} status code, but no Location header was present")
+        end
       when 200..299, 300..399
         # on non-redirecting 3xx statuses, just return the response
         response
       when 400..599
         error = Error.new(response)
         raise(error) if opts.fetch(:raise_errors, options[:raise_errors])
-        response.error = error
+
         response
       else
         error = Error.new(response)
@@ -127,54 +147,78 @@ module OAuth2
 
     # Initializes an AccessToken by making a request to the token endpoint
     #
-    # @param [Hash] params a Hash of params for the token endpoint
-    # @param [Hash] access token options, to pass to the AccessToken object
-    # @param [Class] class of access token for easier subclassing OAuth2::AccessToken
-    # @return [AccessToken] the initalized AccessToken
-    def get_token(params, access_token_opts = {}, access_token_class = AccessToken) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      params = Authenticator.new(id, secret, options[:auth_scheme]).apply(params)
-      opts = {:raise_errors => options[:raise_errors], :parse => params.delete(:parse)}
+    # @param params [Hash] a Hash of params for the token endpoint, except:
+    #   @option params [Symbol] :parse @see Response#initialize
+    #   @option params [true, false] :snaky @see Response#initialize
+    # @param access_token_opts [Hash] access token options, to pass to the AccessToken object
+    # @param extract_access_token [Proc] proc that extracts the access token from the response (DEPRECATED)
+    # @yield [req] @see Faraday::Connection#run_request
+    # @return [AccessToken] the initialized AccessToken
+    def get_token(params, access_token_opts = {}, extract_access_token = nil, &block)
+      warn('OAuth2::Client#get_token argument `extract_access_token` will be removed in oauth2 v3. Refactor to use `access_token_class` on #initialize.') if extract_access_token
+      extract_access_token ||= options[:extract_access_token]
+      params = params.map do |key, value|
+        if RESERVED_PARAM_KEYS.include?(key)
+          [key.to_sym, value]
+        else
+          [key, value]
+        end
+      end.to_h
+
+      request_opts = {
+        raise_errors: options[:raise_errors],
+        parse: params.delete(:parse),
+        snaky: params.delete(:snaky),
+      }
+
+      params = authenticator.apply(params)
       headers = params.delete(:headers) || {}
       if options[:token_method] == :post
-        opts[:body] = params
-        opts[:headers] = {'Content-Type' => 'application/x-www-form-urlencoded'}
+        request_opts[:body] = params
+        request_opts[:headers] = {'Content-Type' => 'application/x-www-form-urlencoded'}
       else
-        opts[:params] = params
-        opts[:headers] = {}
+        request_opts[:params] = params
+        request_opts[:headers] = {}
       end
-      opts[:headers].merge!(headers)
-      response = request(options[:token_method], token_url, opts)
-      if options[:raise_errors] && !(response.parsed.is_a?(Hash) && response.parsed['access_token'])
-        error = Error.new(response)
-        raise(error)
+      request_opts[:headers].merge!(headers)
+      http_method = options[:token_method]
+      http_method = :post if http_method == :post_with_query_string
+      response = request(http_method, token_url, request_opts, &block)
+
+      # In v1.4.x, the deprecated extract_access_token option retrieves the token from the response.
+      # We preserve this behavior here, but a custom access_token_class that implements #from_hash
+      # should be used instead.
+      if extract_access_token
+        parse_response_with_legacy_extract(response, access_token_opts, extract_access_token)
+      else
+        parse_response(response, access_token_opts)
       end
-      access_token_class.from_hash(self, response.parsed.merge(access_token_opts))
     end
 
     # The Authorization Code strategy
     #
-    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.1
+    # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.1
     def auth_code
       @auth_code ||= OAuth2::Strategy::AuthCode.new(self)
     end
 
     # The Implicit strategy
     #
-    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-26#section-4.2
+    # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-26#section-4.2
     def implicit
       @implicit ||= OAuth2::Strategy::Implicit.new(self)
     end
 
     # The Resource Owner Password Credentials strategy
     #
-    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.3
+    # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.3
     def password
       @password ||= OAuth2::Strategy::Password.new(self)
     end
 
     # The Client Credentials strategy
     #
-    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.4
+    # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.4
     def client_credentials
       @client_credentials ||= OAuth2::Strategy::ClientCredentials.new(self)
     end
@@ -194,10 +238,10 @@ module OAuth2
     #
     # @api semipublic
     #
-    # @see https://tools.ietf.org/html/rfc6749#section-4.1
-    # @see https://tools.ietf.org/html/rfc6749#section-4.1.3
-    # @see https://tools.ietf.org/html/rfc6749#section-4.2.1
-    # @see https://tools.ietf.org/html/rfc6749#section-10.6
+    # @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1
+    # @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3
+    # @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.2.1
+    # @see https://datatracker.ietf.org/doc/html/rfc6749#section-10.6
     # @return [Hash] the params to add to a request or URL
     def redirection_params
       if options[:redirect_uri]
@@ -206,5 +250,80 @@ module OAuth2
         {}
       end
     end
+
+  private
+
+    def execute_request(verb, url, opts = {})
+      url = connection.build_url(url).to_s
+
+      begin
+        response = connection.run_request(verb, url, opts[:body], opts[:headers]) do |req|
+          req.params.update(opts[:params]) if opts[:params]
+          yield(req) if block_given?
+        end
+      rescue Faraday::ConnectionFailed => e
+        raise ConnectionError, e
+      rescue Faraday::TimeoutError => e
+        raise TimeoutError, e
+      end
+
+      Response.new(response, parse: opts[:parse], snaky: opts[:snaky])
+    end
+
+    # Returns the authenticator object
+    #
+    # @return [Authenticator] the initialized Authenticator
+    def authenticator
+      Authenticator.new(id, secret, options[:auth_scheme])
+    end
+
+    def parse_response_with_legacy_extract(response, access_token_opts, extract_access_token)
+      access_token = build_access_token_legacy_extract(response, access_token_opts, extract_access_token)
+
+      return access_token if access_token
+
+      if options[:raise_errors]
+        error = Error.new(response)
+        raise(error)
+      end
+
+      nil
+    end
+
+    def parse_response(response, access_token_opts)
+      access_token_class = options[:access_token_class]
+      data = response.parsed
+
+      unless data.is_a?(Hash) && access_token_class.contains_token?(data)
+        return unless options[:raise_errors]
+
+        error = Error.new(response)
+        raise(error)
+      end
+
+      build_access_token(response, access_token_opts, access_token_class)
+    end
+
+    # Builds the access token from the response of the HTTP call
+    #
+    # @return [AccessToken] the initialized AccessToken
+    def build_access_token(response, access_token_opts, access_token_class)
+      access_token_class.from_hash(self, response.parsed.merge(access_token_opts)).tap do |access_token|
+        access_token.response = response if access_token.respond_to?(:response=)
+      end
+    end
+
+    # Builds the access token from the response of the HTTP call with legacy extract_access_token
+    #
+    # @return [AccessToken] the initialized AccessToken
+    def build_access_token_legacy_extract(response, access_token_opts, extract_access_token)
+      extract_access_token.call(self, response.parsed.merge(access_token_opts))
+    rescue StandardError
+      nil
+    end
+
+    def oauth_debug_logging(builder)
+      builder.response :logger, options[:logger], bodies: true if ENV['OAUTH_DEBUG'] == 'true'
+    end
   end
 end

data/lib/oauth2/error.rb

@@ -1,40 +1,51 @@
+# frozen_string_literal: true
+
 module OAuth2
   class Error < StandardError
     attr_reader :response, :code, :description
 
-    # standard error values include:
-    # :invalid_request, :invalid_client, :invalid_token, :invalid_grant, :unsupported_grant_type, :invalid_scope
+    # standard error codes include:
+    # 'invalid_request', 'invalid_client', 'invalid_token', 'invalid_grant', 'unsupported_grant_type', 'invalid_scope'
     def initialize(response)
-      response.error = self
       @response = response
+      message_opts = {}
 
       if response.parsed.is_a?(Hash)
         @code = response.parsed['error']
         @description = response.parsed['error_description']
-        error_description = "#{@code}: #{@description}"
+        message_opts = parse_error_description(@code, @description)
       end
 
-      super(error_message(response.body, :error_description => error_description))
+      super(error_message(response.body, message_opts))
     end
 
-    # Makes a error message
-    # @param [String] response_body response body of request
-    # @param [String] opts :error_description error description to show first line
+  private
+
     def error_message(response_body, opts = {})
-      message = []
+      lines = []
+
+      lines << opts[:error_description] if opts[:error_description]
 
-      opts[:error_description] && message << opts[:error_description]
+      error_string = if response_body.respond_to?(:encode) && opts[:error_description].respond_to?(:encoding)
+                       script_encoding = opts[:error_description].encoding
+                       response_body.encode(script_encoding, invalid: :replace, undef: :replace)
+                     else
+                       response_body
+                     end
+
+      lines << error_string
+
+      lines.join("\n")
+    end
 
-      error_message = if opts[:error_description] && opts[:error_description].respond_to?(:encoding)
-                        script_encoding = opts[:error_description].encoding
-                        response_body.encode(script_encoding, :invalid => :replace, :undef => :replace)
-                      else
-                        response_body
-                      end
+    def parse_error_description(code, description)
+      return {} unless code || description
 
-      message << error_message
+      error_description = ''
+      error_description += "#{code}: " if code
+      error_description += description if description
 
-      message.join("\n")
+      {error_description: error_description}
     end
   end
 end