googleauth 1.12.2 → 1.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34f510693238aa2d0ac63fb3d7a91f8685d34dc9962e33952220b6ee8845beef
-  data.tar.gz: 97d0eb5127ac1c609740d8b422b2002bd8f983043ff1a11cc09130c3c650d30f
+  metadata.gz: 6d8ca5b2b0c7f4ce54f7971d8de2f23f3ee0837d08d7d3c568c503308fcf82ab
+  data.tar.gz: d5f8b8fd2fcb4fef4240db58bf90f54a8bfd021c550a7bc9063c9087285f3921
 SHA512:
-  metadata.gz: 821238707fdf60880359514bc2385a273b4d16fe6bc6bd8ad804fcd36d2255667ad4a4dd39e7fabbd5f422367208a7fc7b74949943cda444481a8da3edfd16e2
-  data.tar.gz: 792636b6a808d5c93dc7a3883a7c7d1e62cbb3d8b33b76e4da025cdbdac8cbd915c1cd4c5e1e698a58173d6fb2840e7623bd8c2a5673edc69113b662486029c4
+  metadata.gz: 6a4de2b23f4dc0310a18568e0618c5d81fad54dfc8d57fe3c27b954c4bd21272fcc467c2c313f98f80fa127eab11ebe0d0fc55ceed7e6c5439764500e334df49
+  data.tar.gz: f4aff68138105ea19875bb7a51d4b6ced9ec2e7185ce725eca205ea1dc11beb9e6019c9dd89449866598ca6e4d3abb06b91f277f34e51ac7726d79a39fc40c67

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Release History
 
+### 1.13.1 (2025-01-24)
+
+#### Bug Fixes
+
+* Signet client subclasses no longer make the update! method private ([#516](https://github.com/googleapis/google-auth-library-ruby/issues/516)) 
+
+### 1.13.0 (2025-01-22)
+
+#### Features
+
+* create impersonated service credentials ([#499](https://github.com/googleapis/google-auth-library-ruby/issues/499)) 
+#### Documentation
+
+* Include note about validating externally-provided credentials ([#512](https://github.com/googleapis/google-auth-library-ruby/issues/512)) 
+
 ### 1.12.2 (2024-12-19)
 
 #### Bug Fixes

data/README.md

@@ -64,6 +64,15 @@ well as a web variant tailored toward Rack-based applications.
 The authorizers are intended for authorization use cases. For sign-on,
 see [Google Identity Platform](https://developers.google.com/identity/)
 
+## Important notes
+
+If you accept a credential configuration (credential JSON/File/Stream) from an
+external source for authentication to Google Cloud, you must validate it before
+providing it to any Google API or library. Providing an unvalidated credential
+configuration to Google APIs can compromise the security of your systems and data.
+For more information, refer to [Validate credential configurations from external
+sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
+
 ### Example (Web)
 
 ```ruby

data/lib/googleauth/compute_engine.rb

@@ -93,6 +93,24 @@ module Google
         super options
       end
 
+      # Creates a duplicate of these credentials
+      # without the Signet::OAuth2::Client-specific
+      # transient state (e.g. cached tokens)
+      #
+      # @param options [Hash] Overrides for the credentials parameters.
+      #   The following keys are recognized in addition to keys in the
+      #   Signet::OAuth2::Client
+      #   * `:universe_domain_overridden` Whether the universe domain was
+      #     overriden during credentials creation
+      def duplicate options = {}
+        options = deep_hash_normalize options
+        super(
+          {
+            universe_domain_overridden: @universe_domain_overridden
+          }.merge(options)
+        )
+      end
+
       # @private
       # Overrides universe_domain getter to fetch lazily if it hasn't been
       # fetched yet. This is necessary specifically for Compute Engine because
@@ -136,6 +154,27 @@ module Google
         end
       end
 
+      # Destructively updates these credentials.
+      #
+      # This method is called by `Signet::OAuth2::Client`'s constructor
+      #
+      # @param options [Hash] Overrides for the credentials parameters.
+      #   The following keys are recognized in addition to keys in the
+      #   Signet::OAuth2::Client
+      #   * `:universe_domain_overridden` Whether the universe domain was
+      #     overriden during credentials creation
+      # @return [Google::Auth::GCECredentials]
+      def update! options = {}
+        # Normalize all keys to symbols to allow indifferent access.
+        options = deep_hash_normalize options
+
+        @universe_domain_overridden = options[:universe_domain_overridden] if options.key? :universe_domain_overridden
+
+        super(options)
+
+        self
+      end
+
       private
 
       def log_fetch_query

data/lib/googleauth/credentials.rb

@@ -26,6 +26,14 @@ module Google
     # In most cases, it is subclassed by API-specific credential classes that
     # can be instantiated by clients.
     #
+    # **Important:** If you accept a credential configuration (credential
+    # JSON/File/Stream) from an external source for authentication to Google
+    # Cloud, you must validate it before providing it to any Google API or
+    # library. Providing an unvalidated credential configuration to Google APIs
+    # can compromise the security of your systems and data. For more
+    # information, refer to [Validate credential configurations from external
+    # sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
+    #
     # ## Options
     #
     # Credentials classes are configured with options that dictate default
@@ -321,9 +329,6 @@ module Google
       #   @return [String, Array<String>] The scope for this client. A scope is an access range
       #     defined by the authorization server. The scope can be a single value or a list of values.
       #
-      # @!attribute [r] target_audience
-      #   @return [String] The final target audience for ID tokens returned by this credential.
-      #
       # @!attribute [r] issuer
       #   @return [String] The issuer ID associated with this client.
       #
@@ -334,6 +339,9 @@ module Google
       #   @return [Proc] Returns a reference to the {Signet::OAuth2::Client#apply} method,
       #     suitable for passing as a closure.
       #
+      # @!attribute [r] target_audience
+      #   @return [String] The final target audience for ID tokens returned by this credential.
+      #
       # @!attribute [rw] universe_domain
       #   @return [String] The universe domain issuing these credentials.
       #
@@ -349,33 +357,53 @@ 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] keyfile
-      #   The keyfile can be provided as one of the following:
+      # @param [String, Hash, Signet::OAuth2::Client] 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 contents of a JSON keyfile (as a `Hash`)
-      #   * A `Signet::OAuth2::Client` object
+      #   * A `Signet::OAuth2::Client` credentials 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.
+      #   Otherwise the inner client will be constructed from the JSON keyfile or the contens of the hash.
+      #
       # @param [Hash] options
-      #   The options for configuring the credentials instance. The following is supported:
+      #   The options for configuring this wrapper credentials object and the inner client.
+      #   The options hash is used in two ways:
       #
-      #   * `:scope` - the scope for the client
-      #   * `project_id` (and optionally `project`) - the project identifier for the client
-      #   * `:connection_builder` - the connection builder to use for the client
-      #   * `:default_connection` - the default connection to use for the client
-      #   * `:logger` - the logger used to log credential operations such as token refresh.
+      #   1. **Configuring the wrapper object:** Some options are used to directly
+      #      configure the wrapper `Credentials` instance. These include:
       #
-      def initialize keyfile, options = {}
-        verify_keyfile_provided! keyfile
+      #     * `:project_id` (and optionally `:project`) - the project identifier for the client
+      #     * `:quota_project_id` - the quota project identifier for the client
+      #     * `:logger` - the logger used to log credential operations such as token refresh.
+      #
+      #   2. **Configuring the inner client:** When the `source_creds` parameter
+      #      is a `String` or `Hash`, a new `Signet::OAuth2::Client` is created
+      #      internally. The following options are used to configure this inner client:
+      #
+      #     * `:scope` - the scope for the client
+      #     * `:target_audience` - the target audience for the client
+      #
+      #   Any other options in the `options` hash are passed directly to the
+      #   inner client constructor. This allows you to configure additional
+      #   parameters of the `Signet::OAuth2::Client`, such as connection parameters,
+      #   timeouts, etc.
+      #
+      def initialize source_creds, options = {}
+        raise "The source credentials passed to Google::Auth::Credentials.new were nil." if source_creds.nil?
+
         options = symbolize_hash_keys options
         @project_id = options[:project_id] || options[:project]
         @quota_project_id = options[:quota_project_id]
-        case keyfile
-        when Google::Auth::BaseClient
-          update_from_signet keyfile
+        case source_creds
+        when String
+          update_from_filepath source_creds, options
         when Hash
-          update_from_hash keyfile, options
+          update_from_hash source_creds, options
         else
-          update_from_filepath keyfile, options
+          update_from_client source_creds
         end
         setup_logging logger: options.fetch(:logger, :default)
         @project_id ||= CredentialsLoader.load_gcloud_project_id
@@ -481,14 +509,50 @@ module Google
                            :from_application_default,
                            :from_io
 
-      protected
 
-      # Verify that the keyfile argument is provided.
-      def verify_keyfile_provided! keyfile
-        return unless keyfile.nil?
-        raise "The keyfile passed to Google::Auth::Credentials.new was nil."
+      # 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.
+      #
+      # The wrapped credentials are typically `Signet::OAuth2::Client` objects and they keep
+      # the transient state (token, refresh token, etc). The duplication discards that state,
+      # allowing e.g. to get the token with a different scope.
+      #
+      # @param options [Hash] Overrides for the credentials parameters.
+      #
+      #   The options hash is used in two ways:
+      #
+      #   1. **Configuring the duplicate of the wrapper object:** Some options are used to directly
+      #      configure the wrapper `Credentials` instance. These include:
+      #
+      #     * `:project_id` (and optionally `:project`) - the project identifier for the credentials
+      #     * `:quota_project_id` - the quota project identifier for the credentials
+      #
+      #   2. **Configuring the duplicate of the inner client:** If the inner client supports duplication
+      #   the options hash is passed to it. This allows for configuration of additional parameters,
+      #   most importantly (but not limited to) the following:
+      #
+      #     * `:scope` - the scope for the client
+      #
+      # @return [Credentials]
+      def duplicate options = {}
+        options = deep_hash_normalize options
+
+        options = {
+          project_id: @project_id,
+          quota_project_id: @quota_project_id
+        }.merge(options)
+
+        new_client = if @client.respond_to? :duplicate
+                       @client.duplicate options
+                     else
+                       @client
+                     end
+
+        self.class.new new_client, options
       end
 
+      protected
+
       # Verify that the keyfile argument is a file.
       def verify_keyfile_exists! keyfile
         exists = ::File.file? keyfile
@@ -530,11 +594,12 @@ module Google
         options
       end
 
-      def update_from_signet client
+      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
         @client = client
       end
+      alias update_from_signet update_from_client
 
       def update_from_hash hash, options
         hash = stringify_hash_keys hash
@@ -571,6 +636,23 @@ module Google
         end
         @client.logger = logger
       end
+
+      private
+
+      # Convert all keys in this hash (nested) to symbols for uniform retrieval
+      def recursive_hash_normalize_keys val
+        if val.is_a? Hash
+          deep_hash_normalize val
+        else
+          val
+        end
+      end
+
+      def deep_hash_normalize old_hash
+        sym_hash = {}
+        old_hash&.each { |k, v| sym_hash[k.to_sym] = recursive_hash_normalize_keys v }
+        sym_hash
+      end
     end
   end
 end

data/lib/googleauth/default_credentials.rb

@@ -19,6 +19,7 @@ require "googleauth/credentials_loader"
 require "googleauth/service_account"
 require "googleauth/user_refresh"
 require "googleauth/external_account"
+require "googleauth/impersonated_service_account"
 
 module Google
   # Module Auth provides classes that provide Google-specific authorization
@@ -29,8 +30,18 @@ module Google
     class DefaultCredentials
       extend CredentialsLoader
 
-      # override CredentialsLoader#make_creds to use the class determined by
+      ##
+      # Override CredentialsLoader#make_creds to use the class determined by
       # loading the json.
+      #
+      # **Important:** If you accept a credential configuration (credential
+      # JSON/File/Stream) from an external source for authentication to Google
+      # Cloud, you must validate it before providing it to any Google API or
+      # library. Providing an unvalidated credential configuration to Google
+      # APIs can compromise the security of your systems and data. For more
+      # information, refer to [Validate credential configurations from external
+      # sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
+      #
       def self.make_creds options = {}
         json_key_io = options[:json_key_io]
         if json_key_io

data/lib/googleauth/impersonated_service_account.rb

@@ -0,0 +1,282 @@
+# Copyright 2024 Google, Inc.
+#
+# 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.
+
+require "googleauth/signet"
+require "googleauth/base_client"
+require "googleauth/helpers/connection"
+
+module Google
+  module Auth
+    # Authenticates requests using impersonation from base credentials.
+    # This is a two-step process: first authentication claim from the base credentials is created
+    # and then that claim is exchanged for a short-lived token at an IAMCredentials endpoint.
+    # The short-lived token and its expiration time are cached.
+    class ImpersonatedServiceAccountCredentials
+      # @private
+      ERROR_SUFFIX = <<~ERROR.freeze
+        when trying to get security access token
+        from IAM Credentials endpoint using the credentials provided.
+      ERROR
+
+      # @private
+      IAM_SCOPE = ["https://www.googleapis.com/auth/iam".freeze].freeze
+
+      # BaseClient most importantly implements the `:updater_proc` getter,
+      # that returns a reference to an `apply!` method that updates
+      # a hash argument provided with the authorization header containing
+      # the access token (impersonation token in this case).
+      include Google::Auth::BaseClient
+
+      include Helpers::Connection
+
+      # @return [Object] The original authenticated credentials used to fetch short-lived impersonation access tokens
+      attr_reader :base_credentials
+
+      # @return [Object] The modified version of base credentials, tailored for impersonation purposes
+      #   with necessary scope adjustments
+      attr_reader :source_credentials
+
+      # @return [String] The URL endpoint used to generate an impersonation token. This URL should follow a specific
+      #   format to specify the impersonated service account.
+      attr_reader :impersonation_url
+
+      # @return [Array<String>, String] The scope(s) required for the impersonated access token,
+      #   indicating the permissions needed for the short-lived token
+      attr_reader :scope
+
+      # @return [String, nil] The short-lived impersonation access token, retrieved and cached
+      #   after making the impersonation request
+      attr_reader :access_token
+
+      # @return [Time, nil] The expiration time of the current access token, used to determine
+      #   if the token is still valid
+      attr_reader :expires_at
+
+      # Create a ImpersonatedServiceAccountCredentials
+      # When you use service account impersonation, you start with an authenticated principal
+      # (e.g. your user account or a service account)
+      # and request short-lived credentials for a service account
+      # that has the authorization that your use case requires.
+      #
+      # @param options [Hash] A hash of options to configure the credentials.
+      # @option options [Object] :base_credentials (required) The authenticated principal.
+      #   It will be used as following:
+      #   * will be duplicated (with IAM scope) to create the source credentials if it supports duplication
+      #   * as source credentials otherwise.
+      # @option options [String] :impersonation_url (required) The URL to impersonate the service account.
+      #   This URL should follow the format:
+      #   `https://iamcredentials.{universe_domain}/v1/projects/-/serviceAccounts/{source_sa_email}:generateAccessToken`,
+      #   where:
+      #     - `{universe_domain}` is the domain of the IAMCredentials API endpoint (e.g., `googleapis.com`).
+      #     - `{source_sa_email}` is the email address of the service account to impersonate.
+      # @option options [Array<String>, String] :scope (required) The scope(s) for the short-lived impersonation token,
+      #   defining the permissions required for the token.
+      # @option options [Object] :source_credentials The authenticated principal that will be used
+      #   to fetch the short-lived impersonation access token. It is an alternative to providing the base credentials.
+      #
+      # @return [Google::Auth::ImpersonatedServiceAccountCredentials]
+      def self.make_creds options = {}
+        new options
+      end
+
+      # Initializes a new instance of ImpersonatedServiceAccountCredentials.
+      #
+      # @param options [Hash] A hash of options to configure the credentials.
+      # @option options [Object] :base_credentials (required) The authenticated principal.
+      #   It will be used as following:
+      #   * will be duplicated (with IAM scope) to create the source credentials if it supports duplication
+      #   * as source credentials otherwise.
+      # @option options [String] :impersonation_url (required) The URL to impersonate the service account.
+      #   This URL should follow the format:
+      #   `https://iamcredentials.{universe_domain}/v1/projects/-/serviceAccounts/{source_sa_email}:generateAccessToken`,
+      #   where:
+      #     - `{universe_domain}` is the domain of the IAMCredentials API endpoint (e.g., `googleapis.com`).
+      #     - `{source_sa_email}` is the email address of the service account to impersonate.
+      # @option options [Array<String>, String] :scope (required) The scope(s) for the short-lived impersonation token,
+      #   defining the permissions required for the token.
+      # @option options [Object] :source_credentials The authenticated principal that will be used
+      #   to fetch the short-lived impersonation access token. It is an alternative to providing the base credentials.
+      #   It is redundant to provide both source and base credentials as only source will be used,
+      #   but it can be done, e.g. when duplicating existing credentials.
+      #
+      # @raise [ArgumentError] If any of the required options are missing.
+      #
+      # @return [Google::Auth::ImpersonatedServiceAccountCredentials]
+      def initialize options = {}
+        @base_credentials, @impersonation_url, @scope =
+          options.values_at :base_credentials,
+                            :impersonation_url,
+                            :scope
+
+        # Fail-fast checks for required parameters
+        if @base_credentials.nil? && !options.key?(:source_credentials)
+          raise ArgumentError, "Missing required option: either :base_credentials or :source_credentials"
+        end
+        raise ArgumentError, "Missing required option: :impersonation_url" if @impersonation_url.nil?
+        raise ArgumentError, "Missing required option: :scope" if @scope.nil?
+
+        # Some credentials (all Signet-based ones and this one) include scope and a bunch of transient state
+        # (e.g. refresh status) as part of themselves
+        # so a copy needs to be created with the scope overriden and transient state dropped.
+        #
+        # If a credentials does not support `duplicate` we'll try to use it as is assuming it has a broad enough scope.
+        # This might result in an "access denied" error downstream when the token from that credentials is being used
+        # for the token exchange.
+        @source_credentials = if options.key? :source_credentials
+                                options[:source_credentials]
+                              elsif @base_credentials.respond_to? :duplicate
+                                @base_credentials.duplicate({
+                                                              scope: IAM_SCOPE
+                                                            })
+                              else
+                                @base_credentials
+                              end
+      end
+
+      # Determines whether the current access token expires within the specified number of seconds.
+      #
+      # @param seconds [Integer] The number of seconds to check against the token's expiration time.
+      #
+      # @return [Boolean] Whether the access token expires within the given time frame
+      def expires_within? seconds
+        # This method is needed for BaseClient
+        @expires_at && @expires_at - Time.now.utc < seconds
+      end
+
+      # The universe domain of the impersonated credentials.
+      # Effectively this retrieves the universe domain of the source credentials.
+      #
+      # @return [String] The universe domain of the credentials.
+      def universe_domain
+        @source_credentials.universe_domain
+      end
+
+      # @return [Logger, nil] The logger of the credentials.
+      def logger
+        @source_credentials.logger if source_credentials.respond_to? :logger
+      end
+
+      # Creates a duplicate of these credentials without transient token state
+      #
+      # @param options [Hash] Overrides for the credentials parameters.
+      #   The following keys are recognized
+      #   * `base_credentials` the base credentials used to initialize the impersonation
+      #   * `source_credentials` the authenticated credentials which usually would be
+      #     base credentials with scope overridden to IAM_SCOPE
+      #   * `impersonation_url` the URL to use to make an impersonation token exchange
+      #   * `scope` the scope(s) to access
+      #
+      # @return [Google::Auth::ImpersonatedServiceAccountCredentials]
+      def duplicate options = {}
+        options = deep_hash_normalize options
+
+        options = {
+          base_credentials: @base_credentials,
+          source_credentials: @source_credentials,
+          impersonation_url: @impersonation_url,
+          scope: @scope
+        }.merge(options)
+
+        self.class.new options
+      end
+
+      private
+
+      # Generates a new impersonation access token by exchanging the source credentials' token
+      # at the impersonation URL.
+      #
+      # This method first fetches an access token from the source credentials and then exchanges it
+      # for an impersonation token using the specified impersonation URL. The generated token and
+      # its expiration time are cached for subsequent use.
+      #
+      # @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.
+      #
+      # @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
+
+        case resp.status
+        when 200
+          response = MultiJson.load resp.body
+          self.expires_at = response["expireTime"]
+          @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
+        else
+          msg = "Unexpected error code #{resp.status}.\n #{resp.env.response_body} #{ERROR_SUFFIX}"
+          raise Signet::AuthorizationError, msg
+        end
+      end
+
+      # Setter for the expires_at value that makes sure it is converted
+      # to Time object.
+      def expires_at= new_expires_at
+        @expires_at = normalize_timestamp new_expires_at
+      end
+
+      # Returns the type of token (access_token).
+      # This method is needed for BaseClient.
+      def token_type
+        :access_token
+      end
+
+      # Normalizes a timestamp to a Time object.
+      #
+      # @param time [Time, String, nil] The timestamp to normalize.
+      #
+      # @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.
+      def normalize_timestamp time
+        case time
+        when NilClass
+          nil
+        when Time
+          time
+        when String
+          Time.parse time
+        else
+          raise "Invalid time value #{time}"
+        end
+      end
+
+      # Convert all keys in this hash (nested) to symbols for uniform retrieval
+      def recursive_hash_normalize_keys val
+        if val.is_a? Hash
+          deep_hash_normalize val
+        else
+          val
+        end
+      end
+
+      def deep_hash_normalize old_hash
+        sym_hash = {}
+        old_hash&.each { |k, v| sym_hash[k.to_sym] = recursive_hash_normalize_keys v }
+        sym_hash
+      end
+    end
+  end
+end

data/lib/googleauth/service_account.rb

@@ -81,6 +81,30 @@ module Google
           .configure_connection(options)
       end
 
+      # Creates a duplicate of these credentials
+      # without the Signet::OAuth2::Client-specific
+      # transient state (e.g. cached tokens)
+      #
+      # @param options [Hash] Overrides for the credentials parameters.
+      #   The following keys are recognized in addition to keys in the
+      #   Signet::OAuth2::Client
+      #   * `:enable_self_signed_jwt` Whether the self-signed JWT should
+      #     be used for the authentication
+      #   * `project_id` the project id to use during the authentication
+      #   * `quota_project_id` the quota project id to use
+      #     during the authentication
+      def duplicate options = {}
+        options = deep_hash_normalize options
+        super(
+          {
+            enable_self_signed_jwt: @enable_self_signed_jwt,
+            project_id: project_id,
+            quota_project_id: quota_project_id,
+            logger: logger
+          }.merge(options)
+        )
+      end
+
       # Handles certain escape sequences that sometimes appear in input.
       # Specifically, interprets the "\n" sequence for newline, and removes
       # enclosing quotes.
@@ -112,6 +136,32 @@ module Google
         super && !enable_self_signed_jwt?
       end
 
+      # Destructively updates these credentials
+      #
+      # This method is called by `Signet::OAuth2::Client`'s constructor
+      #
+      # @param options [Hash] Overrides for the credentials parameters.
+      #   The following keys are recognized in addition to keys in the
+      #   Signet::OAuth2::Client
+      #   * `:enable_self_signed_jwt` Whether the self-signed JWT should
+      #     be used for the authentication
+      #   * `project_id` the project id to use during the authentication
+      #   * `quota_project_id` the quota project id to use
+      #     during the authentication
+      # @return [Google::Auth::ServiceAccountCredentials]
+      def update! options = {}
+        # Normalize all keys to symbols to allow indifferent access.
+        options = deep_hash_normalize options
+
+        @enable_self_signed_jwt = options[:enable_self_signed_jwt] ? true : false
+        @project_id = options[:project_id] if options.key? :project_id
+        @quota_project_id = options[:quota_project_id] if options.key? :quota_project_id
+
+        super(options)
+
+        self
+      end
+
       private
 
       def apply_self_signed_jwt! a_hash
@@ -144,8 +194,10 @@ module Google
       TOKEN_CRED_URI = "https://www.googleapis.com/oauth2/v4/token".freeze
       SIGNING_ALGORITHM = "RS256".freeze
       EXPIRY = 60
+
       extend CredentialsLoader
       extend JsonKeyReader
+
       attr_reader :project_id
       attr_reader :quota_project_id
       attr_accessor :universe_domain
@@ -169,16 +221,43 @@ module Google
           @private_key, @issuer, @project_id, @quota_project_id, @universe_domain =
             self.class.read_json_key json_key_io
         else
-          @private_key = ENV[CredentialsLoader::PRIVATE_KEY_VAR]
-          @issuer = ENV[CredentialsLoader::CLIENT_EMAIL_VAR]
-          @project_id = ENV[CredentialsLoader::PROJECT_ID_VAR]
-          @quota_project_id = nil
-          @universe_domain = nil
+          @private_key = options.key?(:private_key) ? options[:private_key] : ENV[CredentialsLoader::PRIVATE_KEY_VAR]
+          @issuer = options.key?(:issuer) ? options[:issuer] : ENV[CredentialsLoader::CLIENT_EMAIL_VAR]
+          @project_id = options.key?(:project_id) ? options[:project_id] : ENV[CredentialsLoader::PROJECT_ID_VAR]
+          @quota_project_id = options[:quota_project_id] if options.key? :quota_project_id
+          @universe_domain = options[:universe_domain] if options.key? :universe_domain
         end
         @universe_domain ||= "googleapis.com"
         @project_id ||= CredentialsLoader.load_gcloud_project_id
         @signing_key = OpenSSL::PKey::RSA.new @private_key
-        @scope = options[:scope]
+        @scope = options[:scope] if options.key? :scope
+        @logger = options[:logger] if options.key? :scope
+      end
+
+      # Creates a duplicate of these credentials
+      #
+      # @param options [Hash] Overrides for the credentials parameters.
+      #   The following keys are recognized
+      #   * `private key` the private key in string form
+      #   * `issuer` the SA issuer
+      #   * `scope` the scope(s) to access
+      #   * `project_id` the project id to use during the authentication
+      #   * `quota_project_id` the quota project id to use
+      #   * `universe_domain` the universe domain of the credentials
+      def duplicate options = {}
+        options = deep_hash_normalize options
+
+        options = {
+          private_key: @private_key,
+          issuer: @issuer,
+          scope: @scope,
+          project_id: project_id,
+          quota_project_id: quota_project_id,
+          universe_domain: universe_domain,
+          logger: logger
+        }.merge(options)
+
+        self.class.new options
       end
 
       # Construct a jwt token if the JWT_AUD_URI key is present in the input
@@ -237,6 +316,23 @@ module Google
       def needs_access_token?
         false
       end
+
+      private
+
+      def deep_hash_normalize old_hash
+        sym_hash = {}
+        old_hash&.each { |k, v| sym_hash[k.to_sym] = recursive_hash_normalize_keys v }
+        sym_hash
+      end
+
+      # Convert all keys in this hash (nested) to symbols for uniform retrieval
+      def recursive_hash_normalize_keys val
+        if val.is_a? Hash
+          deep_hash_normalize val
+        else
+          val
+        end
+      end
     end
   end
 end

data/lib/googleauth/signet.rb

@@ -38,6 +38,22 @@ module Signet
         self
       end
 
+      alias update_signet_base update!
+      def update! options = {}
+        # Normalize all keys to symbols to allow indifferent access.
+        options = deep_hash_normalize options
+
+        # This `update!` method "overide" adds the `@logger`` update and
+        # the `universe_domain` update.
+        #
+        # The `universe_domain` is also updated in `update_token!` but is
+        # included here for completeness
+        self.universe_domain = options[:universe_domain] if options.key? :universe_domain
+        @logger = options[:logger] if options.key? :logger
+
+        update_signet_base options
+      end
+
       def configure_connection options
         @connection_info =
           options[:connection_builder] || options[:default_connection]
@@ -117,6 +133,42 @@ module Signet
         end
       end
 
+      # Creates a duplicate of these credentials
+      # without the Signet::OAuth2::Client-specific
+      # transient state (e.g. cached tokens)
+      #
+      # @param options [Hash] Overrides for the credentials parameters.
+      # @see Signet::OAuth2::Client#update!
+      def duplicate options = {}
+        options = deep_hash_normalize options
+
+        opts = {
+          authorization_uri: @authorization_uri,
+          token_credential_uri: @token_credential_uri,
+          client_id: @client_id,
+          client_secret: @client_secret,
+          scope: @scope,
+          target_audience: @target_audience,
+          redirect_uri: @redirect_uri,
+          username: @username,
+          password: @password,
+          issuer: @issuer,
+          person: @person,
+          sub: @sub,
+          audience: @audience,
+          signing_key: @signing_key,
+          extension_parameters: @extension_parameters,
+          additional_parameters: @additional_parameters,
+          access_type: @access_type,
+          universe_domain: @universe_domain,
+          logger: @logger
+        }.merge(options)
+
+        new_client = self.class.new opts
+
+        new_client.configure_connection options
+      end
+
       private
 
       def expires_at_from_id_token id_token

data/lib/googleauth/user_refresh.rb

@@ -85,6 +85,26 @@ module Google
         super options
       end
 
+      # Creates a duplicate of these credentials
+      # without the Signet::OAuth2::Client-specific
+      # transient state (e.g. cached tokens)
+      #
+      # @param options [Hash] Overrides for the credentials parameters.
+      #   The following keys are recognized in addition to keys in the
+      #   Signet::OAuth2::Client
+      #   * `project_id` the project id to use during the authentication
+      #   * `quota_project_id` the quota project id to use
+      #     during the authentication
+      def duplicate options = {}
+        options = deep_hash_normalize options
+        super(
+          {
+            project_id: @project_id,
+            quota_project_id: @quota_project_id
+          }.merge(options)
+        )
+      end
+
       # Revokes the credential
       def revoke! options = {}
         c = options[:connection] || Faraday.default_connection
@@ -114,6 +134,29 @@ module Google
                         Google::Auth::ScopeUtil.normalize(scope)
         missing_scope.empty?
       end
+
+      # Destructively updates these credentials
+      #
+      # This method is called by `Signet::OAuth2::Client`'s constructor
+      #
+      # @param options [Hash] Overrides for the credentials parameters.
+      #   The following keys are recognized in addition to keys in the
+      #   Signet::OAuth2::Client
+      #   * `project_id` the project id to use during the authentication
+      #   * `quota_project_id` the quota project id to use
+      #     during the authentication
+      # @return [Google::Auth::UserRefreshCredentials]
+      def update! options = {}
+        # Normalize all keys to symbols to allow indifferent access.
+        options = deep_hash_normalize options
+
+        @project_id = options[:project_id] if options.key? :project_id
+        @quota_project_id = options[:quota_project_id] if options.key? :quota_project_id
+
+        super(options)
+
+        self
+      end
     end
   end
 end

data/lib/googleauth/version.rb

@@ -16,6 +16,6 @@ module Google
   # Module Auth provides classes that provide Google-specific authorization
   # used to access Google APIs.
   module Auth
-    VERSION = "1.12.2".freeze
+    VERSION = "1.13.1".freeze
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: googleauth
 version: !ruby/object:Gem::Version
-  version: 1.12.2
+  version: 1.13.1
 platform: ruby
 authors:
 - Tim Emiola
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-12-19 00:00:00.000000000 Z
+date: 2025-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -166,6 +165,7 @@ files:
 - lib/googleauth/id_tokens/errors.rb
 - lib/googleauth/id_tokens/key_sources.rb
 - lib/googleauth/id_tokens/verifier.rb
+- lib/googleauth/impersonated_service_account.rb
 - lib/googleauth/json_key_reader.rb
 - lib/googleauth/oauth2/sts_client.rb
 - lib/googleauth/scope_util.rb
@@ -185,7 +185,6 @@ metadata:
   changelog_uri: https://github.com/googleapis/google-auth-library-ruby/blob/main/CHANGELOG.md
   source_code_uri: https://github.com/googleapis/google-auth-library-ruby
   bug_tracker_uri: https://github.com/googleapis/google-auth-library-ruby/issues
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -200,8 +199,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Google Auth Library for Ruby
 test_files: []