googleauth 1.14.0 → 1.15.0

data/lib/googleauth/credentials_loader.rb

@@ -15,6 +15,8 @@
 require "os"
 require "rbconfig"
 
+require "googleauth/errors"
+
 module Google
   # Module Auth provides classes that provide Google-specific authorization
   # used to access Google APIs.
@@ -71,11 +73,12 @@ module Google
       #     The following keys are recognized:
       #     * `:default_connection` The connection object to use.
       #     * `:connection_builder` A `Proc` that returns a connection.
+      # @raise [Google::Auth::InitializationError] If the credentials file cannot be read
       def from_env scope = nil, options = {}
         options = interpret_options scope, options
         if ENV.key?(ENV_VAR) && !ENV[ENV_VAR].empty?
           path = ENV[ENV_VAR]
-          raise "file #{path} does not exist" unless File.exist? path
+          raise InitializationError, "file #{path} does not exist" unless File.exist? path
           File.open path do |f|
             return make_creds options.merge(json_key_io: f)
           end
@@ -83,7 +86,7 @@ module Google
           make_creds options
         end
       rescue StandardError => e
-        raise "#{NOT_FOUND_ERROR}: #{e}"
+        raise InitializationError, "#{NOT_FOUND_ERROR}: #{e}"
       end
 
       # Creates an instance from a well known path.
@@ -97,6 +100,7 @@ module Google
       #     The following keys are recognized:
       #     * `:default_connection` The connection object to use.
       #     * `:connection_builder` A `Proc` that returns a connection.
+      # @raise [Google::Auth::InitializationError] If the credentials file cannot be read
       def from_well_known_path scope = nil, options = {}
         options = interpret_options scope, options
         home_var = OS.windows? ? "APPDATA" : "HOME"
@@ -109,7 +113,7 @@ module Google
           return make_creds options.merge(json_key_io: f)
         end
       rescue StandardError => e
-        raise "#{WELL_KNOWN_ERROR}: #{e}"
+        raise InitializationError, "#{WELL_KNOWN_ERROR}: #{e}"
       end
 
       # Creates an instance from the system default path
@@ -123,6 +127,7 @@ module Google
       #     The following keys are recognized:
       #     * `:default_connection` The connection object to use.
       #     * `:connection_builder` A `Proc` that returns a connection.
+      # @raise [Google::Auth::InitializationError] If the credentials file cannot be read or is invalid
       def from_system_default_path scope = nil, options = {}
         options = interpret_options scope, options
         if OS.windows?
@@ -137,7 +142,7 @@ module Google
           return make_creds options.merge(json_key_io: f)
         end
       rescue StandardError => e
-        raise "#{SYSTEM_DEFAULT_ERROR}: #{e}"
+        raise InitializationError, "#{SYSTEM_DEFAULT_ERROR}: #{e}"
       end
 
       module_function

data/lib/googleauth/default_credentials.rb

@@ -16,6 +16,7 @@ require "multi_json"
 require "stringio"
 
 require "googleauth/credentials_loader"
+require "googleauth/errors"
 require "googleauth/external_account"
 require "googleauth/service_account"
 require "googleauth/service_account_jwt_header"
@@ -42,6 +43,9 @@ module Google
       # information, refer to [Validate credential configurations from external
       # sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
       #
+      # @param options [Hash] Options for creating the credentials
+      # @return [Google::Auth::Credentials] The credentials instance
+      # @raise [Google::Auth::InitializationError] If the credentials cannot be determined
       def self.make_creds options = {}
         json_key_io = options[:json_key_io]
         if json_key_io
@@ -54,10 +58,14 @@ module Google
         end
       end
 
+      # Reads the credential type from environment and returns the appropriate class
+      #
+      # @return [Class] The credential class to use
+      # @raise [Google::Auth::InitializationError] If the credentials type is undefined or unsupported
       def self.read_creds
         env_var = CredentialsLoader::ACCOUNT_TYPE_VAR
         type = ENV[env_var]
-        raise "#{env_var} is undefined in env" unless type
+        raise InitializationError, "#{env_var} is undefined in env" unless type
         case type
         when "service_account"
           ServiceAccountCredentials
@@ -66,15 +74,19 @@ module Google
         when "external_account"
           ExternalAccount::Credentials
         else
-          raise "credentials type '#{type}' is not supported"
+          raise InitializationError, "credentials type '#{type}' is not supported"
         end
       end
 
       # Reads the input json and determines which creds class to use.
+      #
+      # @param json_key_io [IO] An IO object containing the JSON key
+      # @return [Array(Hash, Class)] The JSON key and the credential class to use
+      # @raise [Google::Auth::InitializationError] If the JSON is missing the type field or has an unsupported type
       def self.determine_creds_class json_key_io
         json_key = MultiJson.load json_key_io.read
         key = "type"
-        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
         type = json_key[key]
         case type
         when "service_account"
@@ -84,7 +96,7 @@ module Google
         when "external_account"
           [json_key, ExternalAccount::Credentials]
         else
-          raise "credentials type '#{type}' is not supported"
+          raise InitializationError, "credentials type '#{type}' is not supported"
         end
       end
     end

data/lib/googleauth/errors.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "signet/oauth_2/client"
+
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Google
+  module Auth
+    ##
+    # Error mixin module for Google Auth errors
+    # All Google Auth errors should include this module
+    #
+    module Error; end
+
+    ##
+    # Mixin module that contains detailed error information
+    # typically this is available if credentials initialization
+    # succeeds and credentials object is valid
+    #
+    module DetailedError
+      include Error
+
+      # The type of the credentials that the error was originated from
+      # @return [String, nil] The class name of the credential that raised the error
+      attr_reader :credential_type_name
+
+      # The principal for the authentication flow. Typically obtained from credentials
+      # @return [String, Symbol, nil] The principal identifier associated with the credentials
+      attr_reader :principal
+
+      # All details passed in the options hash when creating the error
+      # @return [Hash] Additional details about the error
+      attr_reader :details
+
+      # @private
+      def self.included base
+        base.extend ClassMethods
+      end
+
+      # Class methods to be added to including classes
+      module ClassMethods
+        # Creates a new error with detailed information
+        # @param message [String] The error message
+        # @param credential_type_name [String] The credential type that raised the error
+        # @param principal [String, Symbol] The principal for the authentication flow
+        # @return [Error] The new error with details
+        def with_details message, credential_type_name:, principal:
+          new(message).tap do |error|
+            error.instance_variable_set :@credential_type_name, credential_type_name
+            error.instance_variable_set :@principal, principal
+          end
+        end
+      end
+    end
+
+    ##
+    # Error raised during Credentials initialization.
+    # All new code should use this instead of ArgumentError during initializtion.
+    #
+    class InitializationError < StandardError
+      include Error
+    end
+
+    ##
+    # Generic error raised during operation of Credentials
+    # This should be used for all purposes not covered by other errors.
+    #
+    class CredentialsError < StandardError
+      include DetailedError
+    end
+
+    ##
+    # An error indicating the remote server refused to authorize the client.
+    # Maintains backward compatibility with Signet.
+    #
+    # Should not be used in the new code, even when wrapping `Signet::AuthorizationError`.
+    # New code should use CredentialsError instead.
+    #
+    class AuthorizationError < Signet::AuthorizationError
+      include DetailedError
+    end
+
+    ##
+    # An error indicating that the server sent an unexpected http status.
+    # Maintains backward compatibility with Signet.
+    #
+    # Should not be used in the new code, even when wrapping `Signet::UnexpectedStatusError`.
+    # New code should use CredentialsError instead.
+    #
+    class UnexpectedStatusError < Signet::UnexpectedStatusError
+      include DetailedError
+    end
+
+    ##
+    # An error indicating the client failed to parse a value.
+    # Maintains backward compatibility with Signet.
+    #
+    # Should not be used in the new code, even when wrapping `Signet::ParseError`.
+    # New code should use CredentialsError instead.
+    #
+    class ParseError < Signet::ParseError
+      include DetailedError
+    end
+  end
+end

data/lib/googleauth/external_account/aws_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"
 
@@ -106,17 +107,32 @@ module Google
 
         private
 
+        # Retrieves an IMDSv2 session token or returns a cached token if valid
+        #
+        # @return [String] The IMDSv2 session token
+        # @raise [Google::Auth::CredentialsError] If the token URL is missing or there's an error retrieving the token
         def imdsv2_session_token
           return @imdsv2_session_token unless imdsv2_session_token_invalid?
-          raise "IMDSV2 token url must be provided" if @imdsv2_session_token_url.nil?
+          if @imdsv2_session_token_url.nil?
+            raise CredentialsError.with_details(
+              "IMDSV2 token url must be provided",
+              credential_type_name: self.class.name,
+              principal: principal
+            )
+          end
           begin
             response = connection.put @imdsv2_session_token_url do |req|
               req.headers["x-aws-ec2-metadata-token-ttl-seconds"] = IMDSV2_TOKEN_EXPIRATION_IN_SECONDS.to_s
             end
+            raise Faraday::Error unless response.success?
           rescue Faraday::Error => e
-            raise "Fetching AWS IMDSV2 token error: #{e}"
+            raise CredentialsError.with_details(
+              "Fetching AWS IMDSV2 token error: #{e}",
+              credential_type_name: self.class.name,
+              principal: principal
+            )
           end
-          raise Faraday::Error unless response.success?
+
           @imdsv2_session_token = response.body
           @imdsv2_session_token_expiry = Time.now + IMDSV2_TOKEN_EXPIRATION_IN_SECONDS
           @imdsv2_session_token
@@ -127,6 +143,14 @@ module Google
           @imdsv2_session_token_expiry.nil? || @imdsv2_session_token_expiry < Time.now
         end
 
+        # Makes a request to an AWS resource endpoint
+        #
+        # @param [String] url The AWS endpoint URL
+        # @param [String] name Resource name for error messages
+        # @param [Hash, nil] data Optional data to send in POST requests
+        # @param [Hash] headers Optional request headers
+        # @return [Faraday::Response] The successful response
+        # @raise [Google::Auth::CredentialsError] If the request fails
         def get_aws_resource url, name, data: nil, headers: {}
           begin
             headers["x-aws-ec2-metadata-token"] = imdsv2_session_token
@@ -136,11 +160,14 @@ module Google
                        else
                          connection.get url, nil, headers
                        end
-
             raise Faraday::Error unless response.success?
             response
           rescue Faraday::Error
-            raise "Failed to retrieve AWS #{name}."
+            raise CredentialsError.with_details(
+              "Failed to retrieve AWS #{name}.",
+              credential_type_name: self.class.name,
+              principal: principal
+            )
           end
         end
 
@@ -181,9 +208,16 @@ module Google
         # Retrieves the AWS role currently attached to the current AWS workload by querying the AWS metadata server.
         # This is needed for the AWS metadata server security credentials endpoint in order to retrieve the AWS security
         # credentials needed to sign requests to AWS APIs.
+        #
+        # @return [String] The AWS role name
+        # @raise [Google::Auth::CredentialsError] If the credential verification URL is not set or if the request fails
         def fetch_metadata_role_name
           unless @credential_verification_url
-            raise "Unable to determine the AWS metadata server security credentials endpoint"
+            raise CredentialsError.with_details(
+              "Unable to determine the AWS metadata server security credentials endpoint",
+              credential_type_name: self.class.name,
+              principal: principal
+            )
           end
 
           get_aws_resource(@credential_verification_url, "IAM Role").body
@@ -195,11 +229,22 @@ module Google
           MultiJson.load response.body
         end
 
+        # Reads the name of the AWS region from the environment
+        #
+        # @return [String] The name of the AWS region
+        # @raise [Google::Auth::CredentialsError] If the region is not set in the environment
+        #   and the region_url was not set in credentials source
         def region
           @region = ENV[CredentialsLoader::AWS_REGION_VAR] || ENV[CredentialsLoader::AWS_DEFAULT_REGION_VAR]
 
           unless @region
-            raise "region_url or region must be set for external account credentials" unless @region_url
+            unless @region_url
+              raise CredentialsError.with_details(
+                "region_url or region must be set for external account credentials",
+                credential_type_name: self.class.name,
+                principal: principal
+              )
+            end
 
             @region ||= get_aws_resource(@region_url, "region").body[0..-2]
           end
@@ -220,23 +265,45 @@ module Google
           @region_name = region_name
         end
 
-        # Generates the signed request for the provided HTTP request for calling
-        # an AWS API. This follows the steps described at:
+        # Generates an AWS signature version 4 signed request.
+        #
+        # Creates a signed request following the AWS Signature Version 4 process, which
+        # provides secure authentication for AWS API calls. The process includes creating
+        # canonical request strings, calculating signatures using the AWS credentials, and
+        # building proper authorization headers.
+        #
+        # For detailed information on the signing process, see:
         # https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html
         #
-        # @param [Hash[string, string]] aws_security_credentials
-        #     A dictionary containing the AWS security credentials.
-        # @param [string] url
-        #     The AWS service URL containing the canonical URI and query string.
-        # @param [string] method
-        #     The HTTP method used to call this API.
+        # @param [Hash] aws_credentials The AWS security credentials with the following keys:
+        #   @option aws_credentials [String] :access_key_id The AWS access key ID
+        #   @option aws_credentials [String] :secret_access_key The AWS secret access key
+        #   @option aws_credentials [String, nil] :session_token Optional AWS session token
+        # @param [Hash] original_request The request to sign with the following keys:
+        #   @option original_request [String] :url The AWS service URL (must be HTTPS)
+        #   @option original_request [String] :method The HTTP method (GET, POST, etc.)
+        #   @option original_request [Hash, nil] :headers Optional request headers
+        #   @option original_request [String, nil] :data Optional request payload
+        #
+        # @return [Hash] The signed request with the following keys:
+        #   * :url - The original URL as a string
+        #   * :headers - A hash of headers with the authorization header added
+        #   * :method - The HTTP method
+        #   * :data - The request payload (if present)
         #
-        # @return [hash{string => string}]
-        #     The AWS signed request dictionary object.
+        # @raise [Google::Auth::CredentialsError] If the AWS service URL is invalid
         #
         def generate_signed_request aws_credentials, original_request
           uri = Addressable::URI.parse original_request[:url]
-          raise "Invalid AWS service URL" unless uri.hostname && uri.scheme == "https"
+          unless uri.hostname && uri.scheme == "https"
+            # NOTE: We use AwsCredentials name but can't access its principal since AwsRequestSigner
+            # is a separate class and not a credential object with access to the audience
+            raise CredentialsError.with_details(
+              "Invalid AWS service URL",
+              credential_type_name: AwsCredentials.name,
+              principal: "aws"
+            )
+          end
           service_name = uri.host.split(".").first
 
           datetime = Time.now.utc.strftime "%Y%m%dT%H%M%SZ"

data/lib/googleauth/external_account/base_credentials.rb

@@ -13,6 +13,7 @@
 # limitations under the License.require "time"
 
 require "googleauth/base_client"
+require "googleauth/errors"
 require "googleauth/helpers/connection"
 require "googleauth/oauth2/sts_client"
 
@@ -89,6 +90,14 @@ module Google
           %r{/iam\.googleapis\.com/locations/[^/]+/workforcePools/}.match?(@audience || "")
         end
 
+        # For external account credentials, the principal is
+        # represented by the audience, such as a workforce pool
+        # @private
+        # @return [String] the GCP principal, e.g. a workforce pool
+        def principal
+          @audience
+        end
+
         private
 
         def token_type
@@ -96,6 +105,8 @@ module Google
           :access_token
         end
 
+        # A common method for Other credentials to call during initialization
+        # @raise [Google::Auth::InitializationError] If workforce_pool_user_project is incorrectly set
         def base_setup options
           self.default_connection = options[:connection]
 
@@ -121,9 +132,11 @@ module Google
             connection: default_connection
           )
           return unless @workforce_pool_user_project && !is_workforce_pool?
-          raise "workforce_pool_user_project should not be set for non-workforce pool credentials."
+          raise InitializationError, "workforce_pool_user_project should not be set for non-workforce pool credentials."
         end
 
+        # Exchange tokens at STS endpoint
+        # @raise [Google::Auth::AuthorizationError] If the token exchange request fails
         def exchange_token
           additional_options = nil
           if @client_id.nil? && @workforce_pool_user_project
@@ -140,6 +153,12 @@ module Google
           }
           log_token_request token_request
           @sts_client.exchange_token token_request
+        rescue Google::Auth::AuthorizationError => e
+          raise Google::Auth::AuthorizationError.with_details(
+            e.message,
+            credential_type_name: self.class.name,
+            principal: principal
+          )
         end
 
         def log_token_request token_request
@@ -160,6 +179,12 @@ module Google
           end
         end
 
+        # Exchanges a token for an impersonated service account access token
+        #
+        # @param [String] token The token to exchange
+        # @param [Hash] _options Additional options (not used)
+        # @return [Hash] The response containing the impersonated access token
+        # @raise [Google::Auth::CredentialsError] If the impersonation request fails
         def get_impersonated_access_token token, _options = {}
           log_impersonated_token_request token
           response = connection.post @service_account_impersonation_url do |req|
@@ -169,7 +194,11 @@ module Google
           end
 
           if response.status != 200
-            raise "Service account impersonation failed with status #{response.status}"
+            raise CredentialsError.with_details(
+              "Service account impersonation failed with status #{response.status}",
+              credential_type_name: self.class.name,
+              principal: principal
+            )
           end
 
           MultiJson.load response.body

data/lib/googleauth/external_account/external_account_utils.rb

@@ -13,6 +13,7 @@
 # limitations under the License.require "time"
 
 require "googleauth/base_client"
+require "googleauth/errors"
 require "googleauth/helpers/connection"
 require "googleauth/oauth2/sts_client"
 
@@ -36,8 +37,8 @@ module Google
         # call this API or the required scopes may not be selected:
         # https://cloud.google.com/resource-manager/reference/rest/v1/projects/get#authorization-scopes
         #
-        # @return [string,nil]
-        #     The project ID corresponding to the workload identity pool or workforce pool if determinable.
+        # @return [String, nil] The project ID corresponding to the workload identity
+        #   pool or workforce pool if determinable
         #
         def project_id
           return @project_id unless @project_id.nil?
@@ -65,7 +66,8 @@ module Google
         # STS audience pattern:
         #     `//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/...`
         #
-        # @return [string, nil]
+        # @return [String, nil] The project number extracted from the audience string,
+        #   or nil if it cannot be determined
         #
         def project_number
           segments = @audience.split "/"
@@ -74,6 +76,11 @@ module Google
           segments[idx + 1]
         end
 
+        # Normalizes a timestamp value to a Time object
+        #
+        # @param time [Time, String, nil] The timestamp to normalize
+        # @return [Time, nil] The normalized timestamp or nil if input is nil
+        # @raise [Google::Auth::CredentialsError] If the time value is not nil, Time, or String
         def normalize_timestamp time
           case time
           when NilClass
@@ -83,10 +90,14 @@ module Google
           when String
             Time.parse time
           else
-            raise "Invalid time value #{time}"
+            raise CredentialsError, "Invalid time value #{time}"
           end
         end
 
+        # Extracts the service account email from the impersonation URL
+        #
+        # @return [String, nil] The service account email extracted from the
+        #   service_account_impersonation_url, or nil if it cannot be determined
         def service_account_email
           return nil if @service_account_impersonation_url.nil?
           start_idx = @service_account_impersonation_url.rindex "/"