googleauth 1.13.1 → 1.15.0

data/lib/googleauth/client_id.rb

@@ -14,6 +14,7 @@
 
 require "multi_json"
 require "googleauth/credentials_loader"
+require "googleauth/errors"
 
 module Google
   module Auth
@@ -62,10 +63,11 @@ module Google
       # @note Direct instantiation is discouraged to avoid embedding IDs
       #       and secrets in source. See {#from_file} to load from
       #       `client_secrets.json` files.
+      # @raise [Google::Auth::InitializationError] If id or secret is nil
       #
       def initialize id, secret
-        raise "Client id can not be nil" if id.nil?
-        raise "Client secret can not be nil" if secret.nil?
+        raise InitializationError, "Client id can not be nil" if id.nil?
+        raise InitializationError, "Client secret can not be nil" if secret.nil?
         @id = id
         @secret = secret
       end
@@ -77,9 +79,10 @@ module Google
       # @param [String, File] file
       #  Path of file to read from
       # @return [Google::Auth::ClientID]
+      # @raise [Google::Auth::InitializationError] If file is nil
       #
       def self.from_file file
-        raise "File can not be nil." if file.nil?
+        raise InitializationError, "File can not be nil." if file.nil?
         File.open file.to_s do |f|
           json = f.read
           config = MultiJson.load json
@@ -94,11 +97,12 @@ module Google
       # @param [hash] config
       #  Parsed contents of the JSON file
       # @return [Google::Auth::ClientID]
+      # @raise [Google::Auth::InitializationError] If config is nil or missing required elements
       #
       def self.from_hash config
-        raise "Hash can not be nil." if config.nil?
+        raise InitializationError, "Hash can not be nil." if config.nil?
         raw_detail = config[INSTALLED_APP] || config[WEB_APP]
-        raise MISSING_TOP_LEVEL_ELEMENT_ERROR if raw_detail.nil?
+        raise InitializationError, MISSING_TOP_LEVEL_ELEMENT_ERROR if raw_detail.nil?
         ClientId.new raw_detail[CLIENT_ID], raw_detail[CLIENT_SECRET]
       end
     end

data/lib/googleauth/compute_engine.rb

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 require "google-cloud-env"
+require "googleauth/errors"
 require "googleauth/signet"
 
 module Google
@@ -87,7 +88,7 @@ module Google
       def initialize options = {}
         # Override the constructor to remember whether the universe domain was
         # overridden by a constructor argument.
-        @universe_domain_overridden = options["universe_domain"] || options[:universe_domain] ? true : false
+        @universe_domain_overridden = options["universe_domain"] || options[:universe_domain]
         # TODO: Remove when universe domain metadata endpoint is stable (see b/349488459).
         @disable_universe_domain_check = true
         super options
@@ -126,31 +127,25 @@ module Google
 
       # Overrides the super class method to change how access tokens are
       # fetched.
+      #
+      # @param [Hash] _options Options for token fetch (not used)
+      # @return [Hash] The token data hash
+      # @raise [Google::Auth::UnexpectedStatusError] On unexpected HTTP status codes
+      # @raise [Google::Auth::AuthorizationError] If metadata server is unavailable or returns error
       def fetch_access_token _options = {}
-        query, entry =
-          if token_type == :id_token
-            [{ "audience" => target_audience, "format" => "full" }, "service-accounts/default/identity"]
-          else
-            [{}, "service-accounts/default/token"]
-          end
-        query[:scopes] = Array(scope).join "," if scope
+        query, entry = build_metadata_request_params
         begin
           log_fetch_query
           resp = Google::Cloud.env.lookup_metadata_response "instance", entry, query: query
           log_fetch_resp resp
-          case resp.status
-          when 200
-            build_token_hash resp.body, resp.headers["content-type"], resp.retrieval_monotonic_time
-          when 403, 500
-            raise Signet::UnexpectedStatusError, "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
-          when 404
-            raise Signet::AuthorizationError, NO_METADATA_SERVER_ERROR
-          else
-            raise Signet::AuthorizationError, "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
-          end
+          handle_metadata_response resp
         rescue Google::Cloud::Env::MetadataServerNotResponding => e
           log_fetch_err e
-          raise Signet::AuthorizationError, e.message
+          raise AuthorizationError.with_details(
+            e.message,
+            credential_type_name: self.class.name,
+            principal: principal
+          )
         end
       end
 
@@ -175,8 +170,47 @@ module Google
         self
       end
 
+      # Returns the principal identifier for GCE credentials
+      # @private
+      # @return [Symbol] :gce to represent Google Compute Engine identity
+      def principal
+        :gce_metadata
+      end
+
       private
 
+      # @private
+      # Builds query parameters and endpoint for metadata request
+      # @return [Array] The query parameters and endpoint path
+      def build_metadata_request_params
+        query, entry =
+          if token_type == :id_token
+            [{ "audience" => target_audience, "format" => "full" }, "service-accounts/default/identity"]
+          else
+            [{}, "service-accounts/default/token"]
+          end
+        query[:scopes] = Array(scope).join "," if scope
+        [query, entry]
+      end
+
+      # @private
+      # Handles the response from the metadata server
+      # @param [Google::Cloud::Env::MetadataResponse] resp The metadata server response
+      # @return [Hash] The token hash on success
+      # @raise [Google::Auth::UnexpectedStatusError, Google::Auth::AuthorizationError] On error
+      def handle_metadata_response resp
+        case resp.status
+        when 200
+          build_token_hash resp.body, resp.headers["content-type"], resp.retrieval_monotonic_time
+        when 403, 500
+          raise Signet::UnexpectedStatusError, "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
+        when 404
+          raise Signet::AuthorizationError, NO_METADATA_SERVER_ERROR
+        else
+          raise Signet::AuthorizationError, "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
+        end
+      end
+
       def log_fetch_query
         if token_type == :id_token
           logger&.info do
@@ -213,6 +247,18 @@ module Google
         end
       end
 
+      # Constructs a token hash from the metadata server response
+      #
+      # @private
+      # @param [String] body The response body from the metadata server
+      # @param [String] content_type The content type of the response
+      # @param [Float] retrieval_time The monotonic time when the response was retrieved
+      #
+      # @return [Hash] A hash containing:
+      #   - access_token/id_token: The actual token depending on what was requested
+      #   - token_type: The type of token (usually "Bearer")
+      #   - expires_in: Seconds until token expiration (adjusted for freshness)
+      #   - universe_domain: The universe domain for the token (if not overridden)
       def build_token_hash body, content_type, retrieval_time
         hash =
           if ["text/html", "application/text"].include? content_type

data/lib/googleauth/credentials.rb

@@ -14,9 +14,11 @@
 
 require "forwardable"
 require "json"
+require "pathname"
 require "signet/oauth_2/client"
 
 require "googleauth/credentials_loader"
+require "googleauth/errors"
 
 module Google
   module Auth
@@ -357,12 +359,13 @@ module Google
       # Creates a new Credentials instance with the provided auth credentials, and with the default
       # values configured on the class.
       #
-      # @param [String, Hash, Signet::OAuth2::Client] source_creds
+      # @param [String, Pathname, Hash, Google::Auth::BaseClient] source_creds
       #   The source of credentials. It can be provided as one of the following:
       #
-      #   * The path to a JSON keyfile (as a `String`)
+      #   * The path to a JSON keyfile (as a `String` or a `Pathname`)
       #   * The contents of a JSON keyfile (as a `Hash`)
-      #   * A `Signet::OAuth2::Client` credentials object
+      #   * A `Google::Auth::BaseClient` credentials object, including but not limited to
+      #       a `Signet::OAuth2::Client` object.
       #   * Any credentials object that supports the methods this wrapper delegates to an inner client.
       #
       #   If this parameter is an object (`Signet::OAuth2::Client` or other) it will be used as an inner client.
@@ -391,14 +394,20 @@ module Google
       #   parameters of the `Signet::OAuth2::Client`, such as connection parameters,
       #   timeouts, etc.
       #
+      # @raise [Google::Auth::InitializationError] If source_creds is nil
+      # @raise [ArgumentError] If both scope and target_audience are specified
+      #
       def initialize source_creds, options = {}
-        raise "The source credentials passed to Google::Auth::Credentials.new were nil." if source_creds.nil?
+        if source_creds.nil?
+          raise InitializationError,
+                "The source credentials passed to Google::Auth::Credentials.new were nil."
+        end
 
         options = symbolize_hash_keys options
         @project_id = options[:project_id] || options[:project]
         @quota_project_id = options[:quota_project_id]
         case source_creds
-        when String
+        when String, Pathname
           update_from_filepath source_creds, options
         when Hash
           update_from_hash source_creds, options
@@ -554,9 +563,12 @@ module Google
       protected
 
       # Verify that the keyfile argument is a file.
+      #
+      # @param [String] keyfile Path to the keyfile
+      # @raise [Google::Auth::InitializationError] If the keyfile does not exist
       def verify_keyfile_exists! keyfile
         exists = ::File.file? keyfile
-        raise "The keyfile '#{keyfile}' is not a valid file." unless exists
+        raise InitializationError, "The keyfile '#{keyfile}' is not a valid file." unless exists
       end
 
       # Initializes the Signet client.
@@ -577,6 +589,11 @@ module Google
         hash.to_h.transform_keys(&:to_sym)
       end
 
+      # Updates client options with defaults from the credential class
+      #
+      # @param [Hash] options Options to update
+      # @return [Hash] Updated options hash
+      # @raise [ArgumentError] If both scope and target_audience are specified
       def update_client_options options
         options = options.dup
 

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.
@@ -37,7 +39,7 @@ module Google
       AWS_SESSION_TOKEN_VAR     = "AWS_SESSION_TOKEN".freeze
       GCLOUD_POSIX_COMMAND      = "gcloud".freeze
       GCLOUD_WINDOWS_COMMAND    = "gcloud.cmd".freeze
-      GCLOUD_CONFIG_COMMAND     = "config config-helper --format json --verbosity none".freeze
+      GCLOUD_CONFIG_COMMAND     = "config config-helper --format json --verbosity none --quiet".freeze
 
       CREDENTIALS_FILE_NAME = "application_default_credentials.json".freeze
       NOT_FOUND_ERROR = "Unable to read the credential file specified by #{ENV_VAR}".freeze
@@ -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
@@ -146,7 +151,7 @@ module Google
       def load_gcloud_project_id
         gcloud = GCLOUD_WINDOWS_COMMAND if OS.windows?
         gcloud = GCLOUD_POSIX_COMMAND unless OS.windows?
-        gcloud_json = IO.popen("#{gcloud} #{GCLOUD_CONFIG_COMMAND}", in: :close, err: :close, &:read)
+        gcloud_json = IO.popen("#{gcloud} #{GCLOUD_CONFIG_COMMAND}", err: :close, &:read)
         config = MultiJson.load gcloud_json
         config["configuration"]["properties"]["core"]["project"]
       rescue StandardError

data/lib/googleauth/default_credentials.rb

@@ -16,10 +16,11 @@ 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"
 require "googleauth/user_refresh"
-require "googleauth/external_account"
-require "googleauth/impersonated_service_account"
 
 module Google
   # Module Auth provides classes that provide Google-specific authorization
@@ -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