googleauth 1.14.0 → 1.16.0

data/lib/googleauth/credentials.rb

@@ -14,9 +14,12 @@
 
 require "forwardable"
 require "json"
+require "pathname"
 require "signet/oauth_2/client"
+require "multi_json"
 
 require "googleauth/credentials_loader"
+require "googleauth/errors"
 
 module Google
   module Auth
@@ -357,12 +360,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 +395,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
@@ -499,17 +509,61 @@ module Google
           token_credential_uri:   options[:token_credential_uri] || token_credential_uri,
           audience:               options[:audience] || audience
         }
-        client = Google::Auth::DefaultCredentials.make_creds creds_input
+
+        # Determine the class, which consumes the IO stream
+        json_key, clz = Google::Auth::DefaultCredentials.determine_creds_class creds_input[:json_key_io]
+
+        # Re-serialize the parsed JSON and replace the IO stream in creds_input
+        creds_input[:json_key_io] = StringIO.new MultiJson.dump(json_key)
+
+        client = clz.make_creds creds_input
         options = options.select { |k, _v| k == :logger }
         new client, options
       end
 
+      # @private
+      # Initializes the Signet client.
+      def self.init_client hash, options = {}
+        options = update_client_options options
+        io = StringIO.new JSON.generate hash
+
+        # Determine the class, which consumes the IO stream
+        json_key, clz = Google::Auth::DefaultCredentials.determine_creds_class io
+
+        # Re-serialize the parsed JSON and create a new IO stream.
+        new_io = StringIO.new MultiJson.dump(json_key)
+
+        clz.make_creds options.merge!(json_key_io: new_io)
+      end
+
+      # @private
+      # 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 self.update_client_options options
+        options = options.dup
+
+        # options have higher priority over constructor defaults
+        options[:token_credential_uri] ||= token_credential_uri
+        options[:audience] ||= audience
+        options[:scope] ||= scope
+        options[:target_audience] ||= target_audience
+
+        if !Array(options[:scope]).empty? && options[:target_audience]
+          raise ArgumentError, "Cannot specify both scope and target_audience"
+        end
+        options.delete :scope unless options[:target_audience].nil?
+
+        options
+      end
+
       private_class_method :from_env_vars,
                            :from_default_paths,
                            :from_application_default,
                            :from_io
 
-
       # Creates a duplicate of these credentials. This method tries to create the duplicate of the
       # wrapped credentials if they support duplication and use them as is if they don't.
       #
@@ -554,17 +608,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
-      end
-
-      # Initializes the Signet client.
-      def init_client hash, options = {}
-        options = update_client_options options
-        io = StringIO.new JSON.generate hash
-        options.merge! json_key_io: io
-        Google::Auth::DefaultCredentials.make_creds options
+        raise InitializationError, "The keyfile '#{keyfile}' is not a valid file." unless exists
       end
 
       # returns a new Hash with string keys instead of symbol keys.
@@ -577,23 +626,6 @@ module Google
         hash.to_h.transform_keys(&:to_sym)
       end
 
-      def update_client_options options
-        options = options.dup
-
-        # options have higher priority over constructor defaults
-        options[:token_credential_uri] ||= self.class.token_credential_uri
-        options[:audience] ||= self.class.audience
-        options[:scope] ||= self.class.scope
-        options[:target_audience] ||= self.class.target_audience
-
-        if !Array(options[:scope]).empty? && options[:target_audience]
-          raise ArgumentError, "Cannot specify both scope and target_audience"
-        end
-        options.delete :scope unless options[:target_audience].nil?
-
-        options
-      end
-
       def update_from_client client
         @project_id ||= client.project_id if client.respond_to? :project_id
         @quota_project_id ||= client.quota_project_id if client.respond_to? :quota_project_id
@@ -607,7 +639,7 @@ module Google
         hash["target_audience"] ||= options[:target_audience]
         @project_id ||= hash["project_id"] || hash["project"]
         @quota_project_id ||= hash["quota_project_id"]
-        @client = init_client hash, options
+        @client = self.class.init_client hash, options
       end
 
       def update_from_filepath path, options
@@ -617,7 +649,7 @@ module Google
         json["target_audience"] ||= options[:target_audience]
         @project_id ||= json["project_id"] || json["project"]
         @quota_project_id ||= json["quota_project_id"]
-        @client = init_client json, options
+        @client = self.class.init_client json, options
       end
 
       def setup_logging logger: :default

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
@@ -153,6 +158,21 @@ module Google
         nil
       end
 
+      # @private
+      # Loads a JSON key from an IO object, verifies its type, and rewinds the IO.
+      #
+      # @param json_key_io [IO] An IO object containing the JSON key.
+      # @param expected_type [String] The expected credential type name.
+      # @raise [Google::Auth::InitializationError] If the JSON key type does not match the expected type.
+      def load_and_verify_json_key_type json_key_io, expected_type
+        json_key = MultiJson.load json_key_io.read
+        json_key_io.rewind # Rewind the stream so it can be read again.
+        return if json_key["type"] == expected_type
+        raise Google::Auth::InitializationError,
+              "The provided credentials were not of type '#{expected_type}'. " \
+              "Instead, the type was '#{json_key['type']}'."
+      end
+
       private
 
       def interpret_options scope, options

data/lib/googleauth/default_credentials.rb

@@ -16,10 +16,12 @@ 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/impersonated_service_account"
 
 module Google
   # Module Auth provides classes that provide Google-specific authorization
@@ -42,50 +44,83 @@ module Google
       # information, refer to [Validate credential configurations from external
       # sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
       #
+      # @deprecated This method is deprecated and will be removed in a future version.
+      #   Please use the `make_creds` method on the specific credential class you intend to load,
+      #   e.g., `Google::Auth::ServiceAccountCredentials.make_creds`.
+      #
+      #   This method does not validate the credential configuration. The security
+      #   risk occurs when a credential configuration is accepted from a source that
+      #   is not under your control and used without validation on your side.
+      #
+      #   If you know that you will be loading credential configurations of a
+      #   specific type, it is recommended to use a credential-type-specific
+      #   `make_creds` method.
+      #   This will ensure that an unexpected credential type with potential for
+      #   malicious intent is not loaded unintentionally. You might still have to do
+      #   validation for certain credential types. Please follow the recommendation
+      #   for that method. For example, if you want to load only service accounts,
+      #   you can use:
+      #   ```
+      #   creds = Google::Auth::ServiceAccountCredentials.make_creds
+      #   ```
+      #   @see Google::Auth::ServiceAccountCredentials.make_creds
+      #
+      #   If you are loading your credential configuration from an untrusted source and have
+      #   not mitigated the risks (e.g. by validating the configuration yourself), make
+      #   these changes as soon as possible to prevent security risks to your environment.
+      #
+      #   Regardless of the method used, it is always your responsibility to validate
+      #   configurations received from external sources.
+      #
+      #   See https://cloud.google.com/docs/authentication/external/externally-sourced-credentials for more details.
+      #
+      # @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
-          json_key, clz = determine_creds_class json_key_io
+        json_key, clz = determine_creds_class json_key_io
+        if json_key
           io = StringIO.new MultiJson.dump(json_key)
           clz.make_creds options.merge(json_key_io: io)
         else
-          clz = read_creds
           clz.make_creds options
         end
       end
 
-      def self.read_creds
-        env_var = CredentialsLoader::ACCOUNT_TYPE_VAR
-        type = ENV[env_var]
-        raise "#{env_var} is undefined in env" unless type
-        case type
-        when "service_account"
-          ServiceAccountCredentials
-        when "authorized_user"
-          UserRefreshCredentials
-        when "external_account"
-          ExternalAccount::Credentials
-        else
-          raise "credentials type '#{type}' is not supported"
-        end
-      end
-
       # Reads the input json and determines which creds class to use.
-      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
-        type = json_key[key]
-        case type
-        when "service_account"
-          [json_key, ServiceAccountCredentials]
-        when "authorized_user"
-          [json_key, UserRefreshCredentials]
-        when "external_account"
-          [json_key, ExternalAccount::Credentials]
+      #
+      # @param json_key_io [IO, nil] An optional IO object containing the JSON key.
+      #   If nil, the credential type is determined from environment variables.
+      # @return [Array(Hash, Class)] The JSON key (or nil if from environment) and the credential class to use
+      # @raise [Google::Auth::InitializationError] If the JSON is missing the type field or has an unsupported type,
+      #   or if the environment variable is undefined or unsupported.
+      def self.determine_creds_class json_key_io = nil
+        if json_key_io
+          json_key = MultiJson.load json_key_io.read
+          key = "type"
+          raise InitializationError, "the json is missing the '#{key}' field" unless json_key.key? key
+          type = json_key[key]
         else
-          raise "credentials type '#{type}' is not supported"
+          env_var = CredentialsLoader::ACCOUNT_TYPE_VAR
+          type = ENV[env_var]
+          raise InitializationError, "#{env_var} is undefined in env" unless type
+          json_key = nil
         end
+
+        clz = case type
+              when ServiceAccountCredentials::CREDENTIAL_TYPE_NAME
+                ServiceAccountCredentials
+              when UserRefreshCredentials::CREDENTIAL_TYPE_NAME
+                UserRefreshCredentials
+              when ExternalAccount::Credentials::CREDENTIAL_TYPE_NAME
+                ExternalAccount::Credentials
+              when ImpersonatedServiceAccountCredentials::CREDENTIAL_TYPE_NAME
+                ImpersonatedServiceAccountCredentials
+              else
+                raise InitializationError, "credentials type '#{type}' is not supported"
+              end
+        [json_key, clz]
       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