googleauth 1.11.2 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cfe9034bbf9362f45a8489765bee5b8253deb27c75d50a43b01a4ff3f46a002
-  data.tar.gz: e5bd5f777b3caa2aeae4d42e0576d8f10295cba035736f741399db80a58c50e0
+  metadata.gz: 7f0abc7ed9fc9deefc0b45abbd3b66d6b4a5aa859774f652e2b8c8c8ff12ff77
+  data.tar.gz: c8a2ab192e92bf610f96044c04d5e02ad138dd99f2a1311d14d4e029639b210e
 SHA512:
-  metadata.gz: 1bf31f0d2c50d10cbb1f2e0aec62bb720e0274b518617d0263e30c0952c72589784102a09f251a11996eb7c05181b1639b685803c575d1090c55ce573a62a9d7
-  data.tar.gz: e941dad8ae8e72483587a28d014870a694773dac46aa77f8a8ce0e7fabd2202f82d08e5b1bbc062a4e748effa40fb21f450b4b1b5e423cc66ea76ec04b1c2e23
+  metadata.gz: 17bde72c9466591719a1f069875242a6abbfa9533fef63d5c9d696c16227d68ac2fd053d63f9d46588cb23c38841eb04a27953a38bbd63c2bc8f8f02709f684c
+  data.tar.gz: 4e4c81aad747f3beb7fd610e836ef871e5fa03a2ab7e9b6c2b223cd48e5e891976e736ad90539a493de8ce2805c692667bf3f11162ecb8646ba7a59be82eface

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 1.12.0 (2024-12-05)
+
+#### Features
+
+* provided opt-in debug logging ([#490](https://github.com/googleapis/google-auth-library-ruby/issues/490)) 
+
 ### 1.11.2 (2024-10-23)
 
 #### Bug Fixes

data/lib/googleauth/base_client.rb

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "google/logging/message"
+
 module Google
   # Module Auth provides classes that provide Google-specific authorization
   # used to access Google APIs.
@@ -29,7 +31,12 @@ module Google
         # fetch the access token there is currently not one, or if the client
         # has expired
         fetch_access_token! opts if needs_access_token?
-        a_hash[AUTH_METADATA_KEY] = "Bearer #{send token_type}"
+        token = send token_type
+        a_hash[AUTH_METADATA_KEY] = "Bearer #{token}"
+        logger&.debug do
+          hash = Digest::SHA256.hexdigest token
+          Google::Logging::Message.from message: "Sending auth token. (sha256:#{hash})"
+        end
       end
 
       # Returns a clone of a_hash updated with the authentication token
@@ -66,6 +73,9 @@ module Google
         raise NoMethodError, "expires_within? not implemented"
       end
 
+      # The logger used to log operations on this client, such as token refresh.
+      attr_accessor :logger
+
       private
 
       def token_type

data/lib/googleauth/compute_engine.rb

@@ -96,35 +96,71 @@ module Google
       # Overrides the super class method to change how access tokens are
       # fetched.
       def fetch_access_token _options = {}
-        if token_type == :id_token
-          query = { "audience" => target_audience, "format" => "full" }
-          entry = "service-accounts/default/identity"
-        else
-          query = {}
-          entry = "service-accounts/default/token"
-        end
+        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
         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
-            msg = "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
-            raise Signet::UnexpectedStatusError, msg
+            raise Signet::UnexpectedStatusError, "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
           when 404
             raise Signet::AuthorizationError, NO_METADATA_SERVER_ERROR
           else
-            msg = "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
-            raise Signet::AuthorizationError, msg
+            raise Signet::AuthorizationError, "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
           end
         rescue Google::Cloud::Env::MetadataServerNotResponding => e
+          log_fetch_err e
           raise Signet::AuthorizationError, e.message
         end
       end
 
       private
 
+      def log_fetch_query
+        if token_type == :id_token
+          logger&.info do
+            Google::Logging::Message.from(
+              message: "Requesting id token from MDS with aud=#{target_audience}",
+              "credentialsId" => object_id
+            )
+          end
+        else
+          logger&.info do
+            Google::Logging::Message.from(
+              message: "Requesting access token from MDS",
+              "credentialsId" => object_id
+            )
+          end
+        end
+      end
+
+      def log_fetch_resp resp
+        logger&.info do
+          Google::Logging::Message.from(
+            message: "Received #{resp.status} from MDS",
+            "credentialsId" => object_id
+          )
+        end
+      end
+
+      def log_fetch_err _err
+        logger&.info do
+          Google::Logging::Message.from(
+            message: "MDS did not respond to token request",
+            "credentialsId" => object_id
+          )
+        end
+      end
+
       def build_token_hash body, content_type, retrieval_time
         hash =
           if ["text/html", "application/text"].include? content_type

data/lib/googleauth/credentials.rb

@@ -337,10 +337,13 @@ module Google
       # @!attribute [rw] universe_domain
       #   @return [String] The universe domain issuing these credentials.
       #
+      # @!attribute [rw] logger
+      #   @return [Logger] The logger used to log credential operations such as token refresh.
+      #
       def_delegators :@client,
                      :token_credential_uri, :audience,
                      :scope, :issuer, :signing_key, :updater_proc, :target_audience,
-                     :universe_domain, :universe_domain=
+                     :universe_domain, :universe_domain=, :logger, :logger=
 
       ##
       # Creates a new Credentials instance with the provided auth credentials, and with the default
@@ -349,16 +352,17 @@ module Google
       # @param [String, Hash, Signet::OAuth2::Client] keyfile
       #   The keyfile 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
+      #   * The path to a JSON keyfile (as a `String`)
+      #   * The contents of a JSON keyfile (as a `Hash`)
+      #   * A `Signet::OAuth2::Client` object
       # @param [Hash] options
       #   The options for configuring the credentials instance. The following is supported:
       #
-      #   * +: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
+      #   * `: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.
       #
       def initialize keyfile, options = {}
         verify_keyfile_provided! keyfile
@@ -373,8 +377,8 @@ module Google
         else
           update_from_filepath keyfile, options
         end
+        setup_logging logger: options.fetch(:logger, :default)
         @project_id ||= CredentialsLoader.load_gcloud_project_id
-        @client.fetch_access_token! if @client.needs_access_token?
         @env_vars = nil
         @paths = nil
         @scope = nil
@@ -468,7 +472,8 @@ module Google
           audience:               options[:audience] || audience
         }
         client = Google::Auth::DefaultCredentials.make_creds creds_input
-        new client
+        options = options.select { |k, _v| k == :logger }
+        new client, options
       end
 
       private_class_method :from_env_vars,
@@ -549,6 +554,23 @@ module Google
         @quota_project_id ||= json["quota_project_id"]
         @client = init_client json, options
       end
+
+      def setup_logging logger: :default
+        return unless @client.respond_to? :logger=
+        logging_env = ENV["GOOGLE_SDK_RUBY_LOGGING_GEMS"].to_s.downcase
+        if ["false", "none"].include? logging_env
+          logger = nil
+        elsif @client.logger
+          logger = @client.logger
+        elsif logger == :default
+          logger = nil
+          if ["true", "all"].include?(logging_env) || logging_env.split(",").include?("googleauth")
+            formatter = Google::Logging::StructuredFormatter.new if Google::Cloud::Env.get.logging_agent_expected?
+            logger = Logger.new $stderr, progname: "googleauth", formatter: formatter
+          end
+        end
+        @client.logger = logger
+      end
     end
   end
 end

data/lib/googleauth/external_account/base_credentials.rb

@@ -129,7 +129,7 @@ module Google
           if @client_id.nil? && @workforce_pool_user_project
             additional_options = { userProject: @workforce_pool_user_project }
           end
-          @sts_client.exchange_token(
+          token_request = {
             audience: @audience,
             grant_type: STS_GRANT_TYPE,
             subject_token: retrieve_subject_token!,
@@ -137,10 +137,31 @@ module Google
             scopes: @service_account_impersonation_url ? IAM_SCOPE : @scope,
             requested_token_type: STS_REQUESTED_TOKEN_TYPE,
             additional_options: additional_options
-          )
+          }
+          log_token_request token_request
+          @sts_client.exchange_token token_request
+        end
+
+        def log_token_request token_request
+          logger&.info do
+            Google::Logging::Message.from(
+              message: "Requesting access token from #{token_request[:grant_type]}",
+              "credentialsId" => object_id
+            )
+          end
+          logger&.debug do
+            digest = Digest::SHA256.hexdigest token_request[:subject_token].to_s
+            loggable_request = token_request.merge subject_token: "(sha256:#{digest})"
+            Google::Logging::Message.from(
+              message: "Request data",
+              "request" => loggable_request,
+              "credentialsId" => object_id
+            )
+          end
         end
 
         def get_impersonated_access_token token, _options = {}
+          log_impersonated_token_request token
           response = connection.post @service_account_impersonation_url do |req|
             req.headers["Authorization"] = "Bearer #{token}"
             req.headers["Content-Type"] = "application/json"
@@ -153,6 +174,16 @@ module Google
 
           MultiJson.load response.body
         end
+
+        def log_impersonated_token_request original_token
+          logger&.info do
+            digest = Digest::SHA256.hexdigest original_token
+            Google::Logging::Message.from(
+              message: "Requesting impersonated access token with original token (sha256:#{digest})",
+              "credentialsId" => object_id
+            )
+          end
+        end
       end
     end
   end

data/lib/googleauth/id_tokens.rb

@@ -168,7 +168,6 @@ module Google
                         aud: nil,
                         azp: nil,
                         iss: OIDC_ISSUERS
-
           verifier = Verifier.new key_source: oidc_key_source,
                                   aud:        aud,
                                   azp:        azp,
@@ -206,7 +205,6 @@ module Google
                        aud: nil,
                        azp: nil,
                        iss: IAP_ISSUERS
-
           verifier = Verifier.new key_source: iap_key_source,
                                   aud:        aud,
                                   azp:        azp,

data/lib/googleauth/service_account.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "google/logging/message"
 require "googleauth/signet"
 require "googleauth/credentials_loader"
 require "googleauth/json_key_reader"
@@ -123,6 +124,7 @@ module Google
         }
         key_io = StringIO.new MultiJson.dump(cred_json)
         alt = ServiceAccountJwtHeaderCredentials.make_creds json_key_io: key_io, scope: scope
+        alt.logger = logger
         alt.apply! a_hash
       end
     end
@@ -147,6 +149,7 @@ module Google
       attr_reader :project_id
       attr_reader :quota_project_id
       attr_accessor :universe_domain
+      attr_accessor :logger
 
       # Create a ServiceAccountJwtHeaderCredentials.
       #
@@ -187,10 +190,14 @@ module Google
         return a_hash if jwt_aud_uri.nil? && @scope.nil?
         jwt_token = new_jwt_token jwt_aud_uri, opts
         a_hash[AUTH_METADATA_KEY] = "Bearer #{jwt_token}"
+        logger&.debug do
+          hash = Digest::SHA256.hexdigest jwt_token
+          Google::Logging::Message.from message: "Sending JWT auth token. (sha256:#{hash})"
+        end
         a_hash
       end
 
-      # Returns a clone of a_hash updated with the authoriation header
+      # Returns a clone of a_hash updated with the authorization header
       def apply a_hash, opts = {}
         a_copy = a_hash.clone
         apply! a_copy, opts
@@ -219,6 +226,10 @@ module Google
         assertion["scope"] = Array(@scope).join " " if @scope
         assertion["aud"] = jwt_aud_uri if jwt_aud_uri
 
+        logger&.debug do
+          Google::Logging::Message.from message: "JWT assertion: #{assertion}"
+        end
+
         JWT.encode assertion, @signing_key, SIGNING_ALGORITHM
       end
 

data/lib/googleauth/signet.rb

@@ -65,6 +65,24 @@ module Signet
         info
       end
 
+      alias googleauth_orig_generate_access_token_request generate_access_token_request
+      def generate_access_token_request options = {}
+        parameters = googleauth_orig_generate_access_token_request options
+        logger&.info do
+          Google::Logging::Message.from(
+            message: "Requesting access token from #{parameters['grant_type']}",
+            "credentialsId" => object_id
+          )
+        end
+        logger&.debug do
+          Google::Logging::Message.from(
+            message: "Token fetch params: #{parameters}",
+            "credentialsId" => object_id
+          )
+        end
+        parameters
+      end
+
       def build_default_connection
         if !defined?(@connection_info)
           nil
@@ -79,15 +97,20 @@ module Signet
         retry_count = 0
 
         begin
-          yield
+          yield.tap { |resp| log_response resp }
         rescue StandardError => e
-          raise e if e.is_a?(Signet::AuthorizationError) || e.is_a?(Signet::ParseError)
+          if e.is_a?(Signet::AuthorizationError) || e.is_a?(Signet::ParseError)
+            log_auth_error e
+            raise e
+          end
 
           if retry_count < max_retry_count
+            log_transient_error e
             retry_count += 1
             sleep retry_count * 0.3
             retry
           else
+            log_retries_exhausted e
             msg = "Unexpected error: #{e.inspect}"
             raise Signet::AuthorizationError, msg
           end
@@ -106,6 +129,49 @@ module Signet
         # Shouldn't happen unless we get a garbled ID token
         nil
       end
+
+      def log_response token_response
+        response_hash = JSON.parse token_response rescue {}
+        if response_hash["access_token"]
+          digest = Digest::SHA256.hexdigest response_hash["access_token"]
+          response_hash["access_token"] = "(sha256:#{digest})"
+        end
+        if response_hash["id_token"]
+          digest = Digest::SHA256.hexdigest response_hash["id_token"]
+          response_hash["id_token"] = "(sha256:#{digest})"
+        end
+        Google::Logging::Message.from(
+          message: "Received auth token response: #{response_hash}",
+          "credentialsId" => object_id
+        )
+      end
+
+      def log_auth_error err
+        logger&.info do
+          Google::Logging::Message.from(
+            message: "Auth error when fetching auth token: #{err}",
+            "credentialsId" => object_id
+          )
+        end
+      end
+
+      def log_transient_error err
+        logger&.info do
+          Google::Logging::Message.from(
+            message: "Transient error when fetching auth token: #{err}",
+            "credentialsId" => object_id
+          )
+        end
+      end
+
+      def log_retries_exhausted err
+        logger&.info do
+          Google::Logging::Message.from(
+            message: "Exhausted retries when fetching auth token: #{err}",
+            "credentialsId" => object_id
+          )
+        end
+      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.11.2".freeze
+    VERSION = "1.12.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: googleauth
 version: !ruby/object:Gem::Version
-  version: 1.11.2
+  version: 1.12.0
 platform: ruby
 authors:
 - Tim Emiola
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-10-23 00:00:00.000000000 Z
+date: 2024-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -36,14 +36,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: google-logging-utils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: jwt
   requirement: !ruby/object:Gem::Requirement
@@ -186,7 +200,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
+rubygems_version: 3.5.23
 signing_key: 
 specification_version: 4
 summary: Google Auth Library for Ruby