googleauth 1.14.0 → 1.15.0

data/lib/googleauth/external_account/identity_pool_credentials.rb

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 require "time"
+require "googleauth/errors"
 require "googleauth/external_account/base_credentials"
 require "googleauth/external_account/external_account_utils"
 
@@ -32,10 +33,12 @@ module Google
 
         # Initialize from options map.
         #
-        # @param [string] audience
-        # @param [hash{symbol => value}] credential_source
-        #     credential_source is a hash that contains either source file or url.
-        #     credential_source_format is either text or json. To define how we parse the credential response.
+        # @param [Hash] options Configuration options
+        # @option options [String] :audience The audience for the token
+        # @option options [Hash{Symbol => Object}] :credential_source A hash containing either source file or url.
+        #     credential_source_format is either text or json to define how to parse the credential response.
+        # @raise [Google::Auth::InitializationError] If credential_source format is invalid, field_name is missing,
+        #     contains ambiguous sources, or is missing required fields
         #
         def initialize options = {}
           base_setup options
@@ -51,6 +54,9 @@ module Google
         end
 
         # Implementation of BaseCredentials retrieve_subject_token!
+        #
+        # @return [String] The subject token
+        # @raise [Google::Auth::CredentialsError] If the token can't be parsed from JSON or is missing
         def retrieve_subject_token!
           content, resource_name = token_data
           if @credential_source_format_type == "text"
@@ -60,56 +66,75 @@ module Google
               response_data = MultiJson.load content, symbolize_keys: true
               token = response_data[@credential_source_field_name.to_sym]
             rescue StandardError
-              raise "Unable to parse subject_token from JSON resource #{resource_name} " \
-                    "using key #{@credential_source_field_name}"
+              raise CredentialsError, "Unable to parse subject_token from JSON resource #{resource_name} " \
+                                      "using key #{@credential_source_field_name}"
             end
           end
-          raise "Missing subject_token in the credential_source file/response." unless token
+          raise CredentialsError, "Missing subject_token in the credential_source file/response." unless token
           token
         end
 
         private
 
+        # Validates input
+        #
+        # @raise [Google::Auth::InitializationError] If credential_source format is invalid, field_name is missing,
+        #     contains ambiguous sources, or is missing required fields
         def validate_credential_source
           # `environment_id` is only supported in AWS or dedicated future external account credentials.
           unless @credential_source[:environment_id].nil?
-            raise "Invalid Identity Pool credential_source field 'environment_id'"
+            raise InitializationError, "Invalid Identity Pool credential_source field 'environment_id'"
           end
           unless ["json", "text"].include? @credential_source_format_type
-            raise "Invalid credential_source format #{@credential_source_format_type}"
+            raise InitializationError, "Invalid credential_source format #{@credential_source_format_type}"
           end
           # for JSON types, get the required subject_token field name.
           @credential_source_field_name = @credential_source_format[:subject_token_field_name]
           if @credential_source_format_type == "json" && @credential_source_field_name.nil?
-            raise "Missing subject_token_field_name for JSON credential_source format"
+            raise InitializationError, "Missing subject_token_field_name for JSON credential_source format"
           end
           # check file or url must be fulfilled and mutually exclusiveness.
           if @credential_source_file && @credential_source_url
-            raise "Ambiguous credential_source. 'file' is mutually exclusive with 'url'."
+            raise InitializationError, "Ambiguous credential_source. 'file' is mutually exclusive with 'url'."
           end
           return unless (@credential_source_file || @credential_source_url).nil?
-          raise "Missing credential_source. A 'file' or 'url' must be provided."
+          raise InitializationError, "Missing credential_source. A 'file' or 'url' must be provided."
         end
 
         def token_data
           @credential_source_file.nil? ? url_data : file_data
         end
 
+        # Reads data from a file source
+        #
+        # @return [Array(String, String)] The file content and file path
+        # @raise [Google::Auth::CredentialsError] If the source file doesn't exist
         def file_data
-          raise "File #{@credential_source_file} was not found." unless File.exist? @credential_source_file
+          unless File.exist? @credential_source_file
+            raise CredentialsError,
+                  "File #{@credential_source_file} was not found."
+          end
           content = File.read @credential_source_file, encoding: "utf-8"
           [content, @credential_source_file]
         end
 
+        # Fetches data from a URL source
+        #
+        # @return [Array(String, String)] The response body and URL
+        # @raise [Google::Auth::CredentialsError] If there's an error retrieving data from the URL
+        #   or if the response is not successful
         def url_data
           begin
             response = connection.get @credential_source_url do |req|
               req.headers.merge! @credential_source_headers
             end
           rescue Faraday::Error => e
-            raise "Error retrieving from credential url: #{e}"
+            raise CredentialsError, "Error retrieving from credential url: #{e}"
+          end
+          unless response.success?
+            raise CredentialsError,
+                  "Unable to retrieve Identity Pool subject token #{response.body}"
           end
-          raise "Unable to retrieve Identity Pool subject token #{response.body}" unless response.success?
           [response.body, @credential_source_url]
         end
       end

data/lib/googleauth/external_account/pluggable_credentials.rb

@@ -14,6 +14,7 @@
 
 require "open3"
 require "time"
+require "googleauth/errors"
 require "googleauth/external_account/base_credentials"
 require "googleauth/external_account/external_account_utils"
 
@@ -41,34 +42,43 @@ module Google
 
         # Initialize from options map.
         #
-        # @param [string] audience
-        # @param [hash{symbol => value}] credential_source
-        #     credential_source is a hash that contains either source file or url.
-        #     credential_source_format is either text or json. To define how we parse the credential response.
-        #
+        # @param [Hash] options Configuration options
+        # @option options [String] :audience Audience for the token
+        # @option options [Hash] :credential_source Credential source configuration that contains executable
+        #   configuration
+        # @raise [Google::Auth::InitializationError] If executable source, command is missing, or timeout is invalid
         def initialize options = {}
           base_setup options
 
           @audience = options[:audience]
           @credential_source = options[:credential_source] || {}
           @credential_source_executable = @credential_source[:executable]
-          raise "Missing excutable source. An 'executable' must be provided" if @credential_source_executable.nil?
+          if @credential_source_executable.nil?
+            raise InitializationError,
+                  "Missing excutable source. An 'executable' must be provided"
+          end
           @credential_source_executable_command = @credential_source_executable[:command]
           if @credential_source_executable_command.nil?
-            raise "Missing command field. Executable command must be provided."
+            raise InitializationError, "Missing command field. Executable command must be provided."
           end
           @credential_source_executable_timeout_millis = @credential_source_executable[:timeout_millis] ||
                                                          EXECUTABLE_TIMEOUT_MILLIS_DEFAULT
           if @credential_source_executable_timeout_millis < EXECUTABLE_TIMEOUT_MILLIS_LOWER_BOUND ||
              @credential_source_executable_timeout_millis > EXECUTABLE_TIMEOUT_MILLIS_UPPER_BOUND
-            raise "Timeout must be between 5 and 120 seconds."
+            raise InitializationError, "Timeout must be between 5 and 120 seconds."
           end
           @credential_source_executable_output_file = @credential_source_executable[:output_file]
         end
 
+        # Retrieves the subject token using the credential_source object.
+        #
+        # @return [String] The retrieved subject token
+        # @raise [Google::Auth::CredentialsError] If executables are not allowed, if token retrieval fails,
+        #   or if the token is invalid
         def retrieve_subject_token!
           unless ENV[ENABLE_PLUGGABLE_ENV] == "1"
-            raise "Executables need to be explicitly allowed (set GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES to '1') " \
+            raise CredentialsError,
+                  "Executables need to be explicitly allowed (set GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES to '1') " \
                   "to run."
           end
           # check output file first
@@ -97,7 +107,7 @@ module Google
             subject_token = parse_subject_token response
           rescue StandardError => e
             return nil if e.message.match(/The token returned by the executable is expired/)
-            raise e
+            raise CredentialsError, e.message
           end
           subject_token
         end
@@ -106,25 +116,29 @@ module Google
           validate_response_schema response
           unless response[:success]
             if response[:code].nil? || response[:message].nil?
-              raise "Error code and message fields are required in the response."
+              raise CredentialsError, "Error code and message fields are required in the response."
             end
-            raise "Executable returned unsuccessful response: code: #{response[:code]}, message: #{response[:message]}."
+            raise CredentialsError,
+                  "Executable returned unsuccessful response: code: #{response[:code]}, message: #{response[:message]}."
           end
           if response[:expiration_time] && response[:expiration_time] < Time.now.to_i
-            raise "The token returned by the executable is expired."
+            raise CredentialsError, "The token returned by the executable is expired."
+          end
+          if response[:token_type].nil?
+            raise CredentialsError,
+                  "The executable response is missing the token_type field."
           end
-          raise "The executable response is missing the token_type field." if response[:token_type].nil?
           return response[:id_token] if ID_TOKEN_TYPE.include? response[:token_type]
           return response[:saml_response] if response[:token_type] == "urn:ietf:params:oauth:token-type:saml2"
-          raise "Executable returned unsupported token type."
+          raise CredentialsError, "Executable returned unsupported token type."
         end
 
         def validate_response_schema response
-          raise "The executable response is missing the version field." if response[:version].nil?
+          raise CredentialsError, "The executable response is missing the version field." if response[:version].nil?
           if response[:version] > EXECUTABLE_SUPPORTED_MAX_VERSION
-            raise "Executable returned unsupported version #{response[:version]}."
+            raise CredentialsError, "Executable returned unsupported version #{response[:version]}."
           end
-          raise "The executable response is missing the success field." if response[:success].nil?
+          raise CredentialsError, "The executable response is missing the success field." if response[:success].nil?
         end
 
         def inject_environment_variables
@@ -145,7 +159,8 @@ module Google
           Timeout.timeout timeout_seconds do
             output, error, status = Open3.capture3 environment_vars, command
             unless status.success?
-              raise "Executable exited with non-zero return code #{status.exitstatus}. Error: #{output}, #{error}"
+              raise CredentialsError,
+                    "Executable exited with non-zero return code #{status.exitstatus}. Error: #{output}, #{error}"
             end
             output
           end

data/lib/googleauth/external_account.rb

@@ -15,6 +15,7 @@
 require "time"
 require "uri"
 require "googleauth/credentials_loader"
+require "googleauth/errors"
 require "googleauth/external_account/aws_credentials"
 require "googleauth/external_account/identity_pool_credentials"
 require "googleauth/external_account/pluggable_credentials"
@@ -35,30 +36,41 @@ module Google
 
         # Create a ExternalAccount::Credentials
         #
-        # @param json_key_io [IO] an IO from which the JSON key can be read
-        # @param scope [String,Array,nil] the scope(s) to access
+        # @param options [Hash] Options for creating credentials
+        # @option options [IO] :json_key_io (required) An IO object containing the JSON key
+        # @option options [String,Array,nil] :scope The scope(s) to access
+        # @return [Google::Auth::ExternalAccount::AwsCredentials,
+        #   Google::Auth::ExternalAccount::IdentityPoolCredentials,
+        #   Google::Auth::ExternalAccount::PluggableAuthCredentials]
+        #   The appropriate external account credentials based on the credential source
+        # @raise [Google::Auth::InitializationError] If the json file is missing, lacks required fields,
+        #   or does not contain a supported credential source
         def self.make_creds options = {}
           json_key_io, scope = options.values_at :json_key_io, :scope
 
-          raise "A json file is required for external account credentials." unless json_key_io
+          raise InitializationError, "A json file is required for external account credentials." unless json_key_io
           user_creds = read_json_key json_key_io
 
           # AWS credentials is determined by aws subject token type
           return make_aws_credentials user_creds, scope if user_creds[:subject_token_type] == AWS_SUBJECT_TOKEN_TYPE
 
-          raise MISSING_CREDENTIAL_SOURCE if user_creds[:credential_source].nil?
+          raise InitializationError, MISSING_CREDENTIAL_SOURCE if user_creds[:credential_source].nil?
           user_creds[:scope] = scope
           make_external_account_credentials user_creds
         end
 
         # Reads the required fields from the JSON.
+        #
+        # @param json_key_io [IO] An IO object containing the JSON key
+        # @return [Hash] The parsed JSON key
+        # @raise [Google::Auth::InitializationError] If the JSON is missing required fields
         def self.read_json_key json_key_io
           json_key = MultiJson.load json_key_io.read, symbolize_keys: true
           wanted = [
             :audience, :subject_token_type, :token_url, :credential_source
           ]
           wanted.each do |key|
-            raise "the json is missing the #{key} field" unless json_key.key? key
+            raise InitializationError, "the json is missing the #{key} field" unless json_key.key? key
           end
           json_key
         end
@@ -66,6 +78,11 @@ module Google
         class << self
           private
 
+          # Creates AWS credentials from the provided user credentials
+          #
+          # @param user_creds [Hash] The user credentials containing AWS credential source information
+          # @param scope [String,Array,nil] The scope(s) to access
+          # @return [Google::Auth::ExternalAccount::AwsCredentials] The AWS credentials
           def make_aws_credentials user_creds, scope
             Google::Auth::ExternalAccount::AwsCredentials.new(
               audience: user_creds[:audience],
@@ -78,6 +95,13 @@ module Google
             )
           end
 
+          # Creates the appropriate external account credentials based on the credential source type
+          #
+          # @param user_creds [Hash] The user credentials containing credential source information
+          # @return [Google::Auth::ExternalAccount::IdentityPoolCredentials,
+          #   Google::Auth::ExternalAccount::PluggableAuthCredentials]
+          #   The appropriate external account credentials
+          # @raise [Google::Auth::InitializationError] If the credential source is not a supported type
           def make_external_account_credentials user_creds
             unless user_creds[:credential_source][:file].nil? && user_creds[:credential_source][:url].nil?
               return Google::Auth::ExternalAccount::IdentityPoolCredentials.new user_creds
@@ -85,7 +109,7 @@ module Google
             unless user_creds[:credential_source][:executable].nil?
               return Google::Auth::ExternalAccount::PluggableAuthCredentials.new user_creds
             end
-            raise INVALID_EXTERNAL_ACCOUNT_TYPE
+            raise InitializationError, INVALID_EXTERNAL_ACCOUNT_TYPE
           end
         end
       end

data/lib/googleauth/iam.rb

@@ -27,8 +27,9 @@ module Google
 
       # Initializes an IAMCredentials.
       #
-      # @param selector the IAM selector.
-      # @param token the IAM token.
+      # @param selector [String] The IAM selector.
+      # @param token [String] The IAM token.
+      # @raise [TypeError] If selector or token is not a String
       def initialize selector, token
         raise TypeError unless selector.is_a? String
         raise TypeError unless token.is_a? String
@@ -37,13 +38,19 @@ module Google
       end
 
       # Adds the credential fields to the hash.
+      #
+      # @param a_hash [Hash] The hash to update with credentials
+      # @return [Hash] The updated hash with credentials
       def apply! a_hash
         a_hash[SELECTOR_KEY] = @selector
         a_hash[TOKEN_KEY] = @token
         a_hash
       end
 
-      # Returns a clone of a_hash updated with the authoriation header
+      # Returns a clone of a_hash updated with the authorization header
+      #
+      # @param a_hash [Hash] The hash to clone and update with credentials
+      # @return [Hash] A new hash with credentials
       def apply a_hash
         a_copy = a_hash.clone
         apply! a_copy
@@ -52,9 +59,18 @@ module Google
 
       # Returns a reference to the #apply method, suitable for passing as
       # a closure
+      #
+      # @return [Proc] A procedure that updates a hash with credentials
       def updater_proc
         proc { |a_hash, _opts = {}| apply a_hash }
       end
+
+      # Returns the IAM authority selector as the principal
+      # @private
+      # @return [String] the IAM authoirty selector
+      def principal
+        @selector
+      end
     end
   end
 end

data/lib/googleauth/id_tokens/errors.rb

@@ -14,6 +14,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "googleauth/errors"
+
 
 module Google
   module Auth
@@ -21,35 +23,39 @@ module Google
       ##
       # Failed to obtain keys from the key source.
       #
-      class KeySourceError < StandardError; end
+      class KeySourceError < StandardError
+        include Google::Auth::Error
+      end
 
       ##
       # Failed to verify a token.
       #
-      class VerificationError < StandardError; end
+      class VerificationError < StandardError
+        include Google::Auth::Error
+      end
 
       ##
-      # Failed to verify a token because it is expired.
+      # Failed to verify token because it is expired.
       #
       class ExpiredTokenError < VerificationError; end
 
       ##
-      # Failed to verify a token because its signature did not match.
+      # Failed to verify token because its signature did not match.
       #
       class SignatureError < VerificationError; end
 
       ##
-      # Failed to verify a token because its issuer did not match.
+      # Failed to verify token because its issuer did not match.
       #
       class IssuerMismatchError < VerificationError; end
 
       ##
-      # Failed to verify a token because its audience did not match.
+      # Failed to verify token because its audience did not match.
       #
       class AudienceMismatchError < VerificationError; end
 
       ##
-      # Failed to verify a token because its authorized party did not match.
+      # Failed to verify token because its authorized party did not match.
       #
       class AuthorizedPartyMismatchError < VerificationError; end
     end

data/lib/googleauth/id_tokens/key_sources.rb

@@ -72,8 +72,8 @@ module Google
           #
           # @param jwk [Hash,String] The JWK specification.
           # @return [KeyInfo]
-          # @raise [KeySourceError] If the key could not be extracted from the
-          #     JWK.
+          # @raise [Google::Auth::IDTokens::KeySourceError] If the key could not be extracted from the
+          #     JWK due to invalid type, malformed JSON, or invalid key data.
           #
           def from_jwk jwk
             jwk = symbolize_keys ensure_json_parsed jwk
@@ -94,10 +94,10 @@ module Google
           # Create an array of KeyInfo from a JWK Set, which may be given as
           # either a hash or an unparsed JSON string.
           #
-          # @param jwk [Hash,String] The JWK Set specification.
+          # @param jwk_set [Hash,String] The JWK Set specification.
           # @return [Array<KeyInfo>]
-          # @raise [KeySourceError] If a key could not be extracted from the
-          #     JWK Set.
+          # @raise [Google::Auth::IDTokens::KeySourceError] If a key could not be extracted from the
+          #     JWK Set, or if the set contains no keys.
           #
           def from_jwk_set jwk_set
             jwk_set = symbolize_keys ensure_json_parsed jwk_set
@@ -261,7 +261,8 @@ module Google
         # return the new keys.
         #
         # @return [Array<KeyInfo>]
-        # @raise [KeySourceError] if key retrieval failed.
+        # @raise [Google::Auth::IDTokens::KeySourceError] If key retrieval fails, JSON parsing
+        #     fails, or the data cannot be interpreted as keys
         #
         def refresh_keys
           @monitor.synchronize do
@@ -310,6 +311,11 @@ module Google
 
         protected
 
+        # Interpret JSON data as X509 certificates
+        #
+        # @param data [Hash] The JSON data containing certificate strings
+        # @return [Array<KeyInfo>] Array of key info objects
+        # @raise [Google::Auth::IDTokens::KeySourceError] If X509 certificates cannot be parsed
         def interpret_json data
           data.map do |id, cert_str|
             key = OpenSSL::X509::Certificate.new(cert_str).public_key
@@ -371,7 +377,7 @@ module Google
         # Attempt to refresh keys and return the new keys.
         #
         # @return [Array<KeyInfo>]
-        # @raise [KeySourceError] if key retrieval failed.
+        # @raise [Google::Auth::IDTokens::KeySourceError] If key retrieval failed for any source.
         #
         def refresh_keys
           @sources.flat_map(&:refresh_keys)

data/lib/googleauth/id_tokens/verifier.rb

@@ -61,10 +61,9 @@ module Google
         # @param iss [String,nil] If given, override the `iss` check.
         #
         # @return [Hash] the decoded payload, if verification succeeded.
-        # @raise [KeySourceError] if the key source failed to obtain public keys
-        # @raise [VerificationError] if the token verification failed.
+        # @raise [Google::Auth::IDTokens::KeySourceError] if the key source failed to obtain public keys
+        # @raise [Google::Auth::IDTokens::VerificationError] if the token verification failed.
         #     Additional data may be available in the error subclass and message.
-        #
         def verify token,
                    key_source: :default,
                    aud:        :default,

data/lib/googleauth/id_tokens.rb

@@ -160,8 +160,8 @@ module Google
         #     checking is performed. Default is to check against {OIDC_ISSUERS}.
         #
         # @return [Hash] The decoded token payload.
-        # @raise [KeySourceError] if the key source failed to obtain public keys
-        # @raise [VerificationError] if the token verification failed.
+        # @raise [Google::Auth::IDTokens::KeySourceError] if the key source failed to obtain public keys
+        # @raise [Google::Auth::IDTokens::VerificationError] if the token verification failed.
         #     Additional data may be available in the error subclass and message.
         #
         def verify_oidc token,
@@ -197,8 +197,8 @@ module Google
         #     checking is performed. Default is to check against {IAP_ISSUERS}.
         #
         # @return [Hash] The decoded token payload.
-        # @raise [KeySourceError] if the key source failed to obtain public keys
-        # @raise [VerificationError] if the token verification failed.
+        # @raise [Google::Auth::IDTokens::KeySourceError] if the key source failed to obtain public keys
+        # @raise [Google::Auth::IDTokens::VerificationError] if the token verification failed.
         #     Additional data may be available in the error subclass and message.
         #
         def verify_iap token,

data/lib/googleauth/impersonated_service_account.rb

@@ -12,8 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "googleauth/signet"
 require "googleauth/base_client"
+require "googleauth/errors"
 require "googleauth/helpers/connection"
 
 module Google
@@ -191,6 +191,20 @@ module Google
         self.class.new options
       end
 
+      # The principal behind the credentials. This class allows custom source credentials type
+      # that might not implement `principal`, in which case `:unknown` is returned.
+      #
+      # @private
+      # @return [String, Symbol] The string representation of the principal,
+      #     the token type in lieu of the principal, or :unknown if source principal is unknown.
+      def principal
+        if @source_credentials.respond_to? :principal
+          @source_credentials.principal
+        else
+          :unknown
+        end
+      end
+
       private
 
       # Generates a new impersonation access token by exchanging the source credentials' token
@@ -200,21 +214,16 @@ module Google
       # for an impersonation token using the specified impersonation URL. The generated token and
       # its expiration time are cached for subsequent use.
       #
+      # @private
       # @param _options [Hash] (optional) Additional options for token retrieval (currently unused).
       #
-      # @raise [Signet::UnexpectedStatusError] If the response status is 403 or 500.
-      # @raise [Signet::AuthorizationError] For other unexpected response statuses.
+      # @raise [Google::Auth::UnexpectedStatusError] If the response status is 403 or 500.
+      # @raise [Google::Auth::AuthorizationError] For other unexpected response statuses.
       #
       # @return [String] The newly generated impersonation access token.
       def fetch_access_token! _options = {}
-        auth_header = {}
-        auth_header = @source_credentials.updater_proc.call auth_header
-
-        resp = connection.post @impersonation_url do |req|
-          req.headers.merge! auth_header
-          req.headers["Content-Type"] = "application/json"
-          req.body = MultiJson.dump({ scope: @scope })
-        end
+        auth_header = prepare_auth_header
+        resp = make_impersonation_request auth_header
 
         case resp.status
         when 200
@@ -223,14 +232,51 @@ module Google
           @access_token = response["accessToken"]
           access_token
         when 403, 500
-          msg = "Unexpected error code #{resp.status}.\n #{resp.env.response_body} #{ERROR_SUFFIX}"
-          raise Signet::UnexpectedStatusError, msg
+          handle_error_response resp, UnexpectedStatusError
         else
-          msg = "Unexpected error code #{resp.status}.\n #{resp.env.response_body} #{ERROR_SUFFIX}"
-          raise Signet::AuthorizationError, msg
+          handle_error_response resp, AuthorizationError
+        end
+      end
+
+      # Prepares the authorization header for the impersonation request
+      # by fetching a token from source credentials.
+      #
+      # @private
+      # @return [Hash] The authorization header with the source credentials' token
+      def prepare_auth_header
+        auth_header = {}
+        @source_credentials.updater_proc.call auth_header
+        auth_header
+      end
+
+      # Makes the HTTP request to the impersonation endpoint.
+      #
+      # @private
+      # @param [Hash] auth_header The authorization header containing the source token
+      # @return [Faraday::Response] The HTTP response from the impersonation endpoint
+      def make_impersonation_request auth_header
+        connection.post @impersonation_url do |req|
+          req.headers.merge! auth_header
+          req.headers["Content-Type"] = "application/json"
+          req.body = MultiJson.dump({ scope: @scope })
         end
       end
 
+      # Creates and raises an appropriate error based on the response.
+      #
+      # @private
+      # @param [Faraday::Response] resp The HTTP response
+      # @param [Class] error_class The error class to instantiate
+      # @raise [StandardError] The appropriate error with details
+      def handle_error_response resp, error_class
+        msg = "Unexpected error code #{resp.status}.\n #{resp.env.response_body} #{ERROR_SUFFIX}"
+        raise error_class.with_details(
+          msg,
+          credential_type_name: self.class.name,
+          principal: principal
+        )
+      end
+
       # Setter for the expires_at value that makes sure it is converted
       # to Time object.
       def expires_at= new_expires_at
@@ -249,7 +295,7 @@ module Google
       #
       # @return [Time, nil] The normalized Time object, or nil if the input is nil.
       #
-      # @raise [RuntimeError] If the input is not a Time, String, or nil.
+      # @raise [Google::Auth::CredentialsError] If the input is not a Time, String, or nil.
       def normalize_timestamp time
         case time
         when NilClass
@@ -259,7 +305,8 @@ module Google
         when String
           Time.parse time
         else
-          raise "Invalid time value #{time}"
+          message = "Invalid time value #{time}"
+          raise CredentialsError.with_details(message, credential_type_name: self.class.name, principal: principal)
         end
       end