googleauth 1.8.0 → 1.15.0

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,14 @@ 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
+
+        a_hash[AUTH_METADATA_KEY]
       end
 
       # Returns a clone of a_hash updated with the authentication token
@@ -63,17 +72,25 @@ module Google
       end
 
       def expires_within?
-        raise NotImplementedError
+        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 principal
+        raise NoMethodError, "principal not implemented"
       end
 
       private
 
       def token_type
-        raise NotImplementedError
+        raise NoMethodError, "token_type not implemented"
       end
 
       def fetch_access_token!
-        raise NotImplementedError
+        raise NoMethodError, "fetch_access_token! not implemented"
       end
     end
   end

data/lib/googleauth/bearer_token.rb

@@ -0,0 +1,162 @@
+# 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.
+
+require "googleauth/base_client"
+require "googleauth/errors"
+
+module Google
+  module Auth
+    ##
+    # Implementation of Bearer Token authentication scenario.
+    #
+    # Bearer tokens are strings representing an authorization grant.
+    # They can be OAuth2 ("ya.29") tokens, JWTs, IDTokens -- anything
+    # that is sent as a `Bearer` in an `Authorization` header.
+    #
+    # Not all 'authentication' strings can be used with this class,
+    # e.g. an API key cannot since API keys are sent in a
+    # `x-goog-api-key` header or as a query parameter.
+    #
+    # This class should be used when the end-user is managing the
+    # authentication token separately, e.g. with a separate service.
+    # This means that tasks like tracking the lifetime of and
+    # refreshing the token are outside the scope of this class.
+    #
+    # There is no JSON representation for this type of credentials.
+    # If the end-user has credentials in JSON format they should typically
+    # use the corresponding credentials type, e.g. ServiceAccountCredentials
+    # with the service account JSON.
+    #
+    class BearerTokenCredentials
+      include Google::Auth::BaseClient
+
+      # @private Authorization header name
+      AUTH_METADATA_KEY = Google::Auth::BaseClient::AUTH_METADATA_KEY
+
+      # @return [String] The token to be sent as a part of Bearer claim
+      attr_reader :token
+      # The following aliasing is needed for BaseClient since it sends :token_type
+      alias bearer_token token
+
+      # @return [Time, nil] The token expiration time provided by the end-user.
+      attr_reader :expires_at
+
+      # @return [String] The universe domain of the universe
+      #   this token is for
+      attr_accessor :universe_domain
+
+      class << self
+        # Create the BearerTokenCredentials.
+        #
+        # @param [Hash] options The credentials options
+        # @option options [String] :token The bearer token to use.
+        # @option options [Time, Numeric, nil] :expires_at The token expiration time provided by the end-user.
+        #   Optional, for the end-user's convenience. Can be a Time object, a number of seconds since epoch.
+        #   If `expires_at` is `nil`, it is treated as "token never expires".
+        # @option options [String] :universe_domain The universe domain of the universe
+        #   this token is for (defaults to googleapis.com)
+        # @return [Google::Auth::BearerTokenCredentials]
+        def make_creds options = {}
+          new options
+        end
+      end
+
+      # Initialize the BearerTokenCredentials.
+      #
+      # @param [Hash] options The credentials options
+      # @option options [String] :token The bearer token to use.
+      # @option options [Time, Numeric, nil] :expires_at The token expiration time provided by the end-user.
+      #   Optional, for the end-user's convenience. Can be a Time object, a number of seconds since epoch.
+      #   If `expires_at` is `nil`, it is treated as "token never expires".
+      # @option options [String] :universe_domain The universe domain of the universe
+      #   this token is for (defaults to googleapis.com)
+      # @raise [ArgumentError] If the bearer token is nil or empty
+      def initialize options = {}
+        raise ArgumentError, "Bearer token must be provided" if options[:token].nil? || options[:token].empty?
+        @token = options[:token]
+        @expires_at = case options[:expires_at]
+                      when Time
+                        options[:expires_at]
+                      when Numeric
+                        Time.at options[:expires_at]
+                      end
+
+        @universe_domain = options[:universe_domain] || "googleapis.com"
+      end
+
+      # Determines if the credentials object has expired.
+      #
+      # @param [Numeric] seconds The optional timeout in seconds.
+      # @return [Boolean] True if the token has expired, false otherwise, or
+      #   if the expires_at was not provided.
+      def expires_within? seconds
+        return false if @expires_at.nil? # Treat nil expiration as "never expires"
+        Time.now + seconds >= @expires_at
+      end
+
+      # Creates a duplicate of these credentials.
+      #
+      # @param [Hash] options Additional options for configuring the credentials
+      # @option options [String] :token The bearer token to use.
+      # @option options [Time, Numeric] :expires_at The token expiration time. Can be a Time
+      #   object or a number of seconds since epoch.
+      # @option options [String] :universe_domain The universe domain (defaults to googleapis.com)
+      # @return [Google::Auth::BearerTokenCredentials]
+      def duplicate options = {}
+        self.class.new(
+          token: options[:token] || @token,
+          expires_at: options[:expires_at] || @expires_at,
+          universe_domain: options[:universe_domain] || @universe_domain
+        )
+      end
+
+      # For credentials that are initialized with a token without a principal,
+      # the type of that token should be returned as a principal instead
+      # @private
+      # @return [Symbol] the token type in lieu of the principal
+      def principal
+        token_type
+      end
+
+      protected
+
+      ##
+      # BearerTokenCredentials do not support fetching a new token.
+      #
+      # If the token has an expiration time and is expired, this method will
+      # raise an error.
+      #
+      # @param [Hash] _options Options for fetching a new token (not used).
+      # @return [nil] Always returns nil.
+      # @raise [Google::Auth::CredentialsError] If the token is expired.
+      def fetch_access_token! _options = {}
+        if @expires_at && Time.now >= @expires_at
+          raise CredentialsError.with_details(
+            "Bearer token has expired.",
+            credential_type_name: self.class.name,
+            principal: principal
+          )
+        end
+
+        nil
+      end
+
+      private
+
+      def token_type
+        :bearer_token
+      end
+    end
+  end
+end

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,11 +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
-        CredentialsLoader.warn_if_cloud_sdk_credentials id
-        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
@@ -78,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
@@ -95,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

@@ -12,7 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "faraday"
+require "google-cloud-env"
+require "googleauth/errors"
 require "googleauth/signet"
 
 module Google
@@ -33,93 +34,274 @@ module Google
     # Extends Signet::OAuth2::Client so that the auth token is obtained from
     # the GCE metadata server.
     class GCECredentials < Signet::OAuth2::Client
-      # The IP Address is used in the URIs to speed up failures on non-GCE
-      # systems.
+      # @private Unused and deprecated but retained to prevent breaking changes
       DEFAULT_METADATA_HOST = "169.254.169.254".freeze
 
-      # @private Unused and deprecated
+      # @private Unused and deprecated but retained to prevent breaking changes
       COMPUTE_AUTH_TOKEN_URI =
         "http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token".freeze
-      # @private Unused and deprecated
+      # @private Unused and deprecated but retained to prevent breaking changes
       COMPUTE_ID_TOKEN_URI =
         "http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/identity".freeze
-      # @private Unused and deprecated
+      # @private Unused and deprecated but retained to prevent breaking changes
       COMPUTE_CHECK_URI = "http://169.254.169.254".freeze
 
-      @on_gce_cache = {}
-
       class << self
+        # @private Unused and deprecated
         def metadata_host
           ENV.fetch "GCE_METADATA_HOST", DEFAULT_METADATA_HOST
         end
 
+        # @private Unused and deprecated
         def compute_check_uri
           "http://#{metadata_host}".freeze
         end
 
+        # @private Unused and deprecated
         def compute_auth_token_uri
           "#{compute_check_uri}/computeMetadata/v1/instance/service-accounts/default/token".freeze
         end
 
+        # @private Unused and deprecated
         def compute_id_token_uri
           "#{compute_check_uri}/computeMetadata/v1/instance/service-accounts/default/identity".freeze
         end
 
         # Detect if this appear to be a GCE instance, by checking if metadata
         # is available.
-        def on_gce? options = {}, reload = false # rubocop:disable Style/OptionalBooleanParameter
-          # We can follow OptionalBooleanParameter here because it's a public interface, we can't change it.
-          @on_gce_cache.delete options if reload
-          @on_gce_cache.fetch options do
-            @on_gce_cache[options] = begin
-              # TODO: This should use google-cloud-env instead.
-              c = options[:connection] || Faraday.default_connection
-              headers = { "Metadata-Flavor" => "Google" }
-              resp = c.get compute_check_uri, nil, headers do |req|
-                req.options.timeout = 1.0
-                req.options.open_timeout = 0.1
-              end
-              return false unless resp.status == 200
-              resp.headers["Metadata-Flavor"] == "Google"
-            rescue Faraday::TimeoutError, Faraday::ConnectionFailed
-              false
-            end
-          end
+        # The parameters are deprecated and unused.
+        def on_gce? _options = {}, _reload = false # rubocop:disable Style/OptionalBooleanParameter
+          Google::Cloud.env.metadata?
         end
 
         def reset_cache
-          @on_gce_cache.clear
+          Google::Cloud.env.compute_metadata.reset_existence!
+          Google::Cloud.env.compute_metadata.cache.expire_all!
         end
         alias unmemoize_all reset_cache
       end
 
+      # @private Temporary; remove when universe domain metadata endpoint is stable (see b/349488459).
+      attr_accessor :disable_universe_domain_check
+
+      # Construct a GCECredentials
+      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]
+        # TODO: Remove when universe domain metadata endpoint is stable (see b/349488459).
+        @disable_universe_domain_check = true
+        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
+      # the universe comes from the metadata service, and isn't known
+      # immediately on credential construction. All other credential types read
+      # the universe from their json key or other immediate input.
+      def universe_domain
+        value = super
+        return value unless value.nil?
+        fetch_access_token!
+        super
+      end
+
       # Overrides the super class method to change how access tokens are
       # fetched.
-      def fetch_access_token options = {}
-        c = options[:connection] || Faraday.default_connection
-        retry_with_error do
-          uri = target_audience ? GCECredentials.compute_id_token_uri : GCECredentials.compute_auth_token_uri
-          query = target_audience ? { "audience" => target_audience, "format" => "full" } : {}
-          query[:scopes] = Array(scope).join "," if scope
-          resp = c.get uri, query, "Metadata-Flavor" => "Google"
-          case resp.status
-          when 200
-            content_type = resp.headers["content-type"]
-            if ["text/html", "application/text"].include? content_type
-              { (target_audience ? "id_token" : "access_token") => resp.body }
-            else
-              Signet::OAuth2.parse_credentials resp.body, content_type
-            end
-          when 403, 500
-            msg = "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
-            raise Signet::UnexpectedStatusError, msg
-          when 404
-            raise Signet::AuthorizationError, NO_METADATA_SERVER_ERROR
+      #
+      # @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 = build_metadata_request_params
+        begin
+          log_fetch_query
+          resp = Google::Cloud.env.lookup_metadata_response "instance", entry, query: query
+          log_fetch_resp resp
+          handle_metadata_response resp
+        rescue Google::Cloud::Env::MetadataServerNotResponding => e
+          log_fetch_err e
+          raise AuthorizationError.with_details(
+            e.message,
+            credential_type_name: self.class.name,
+            principal: principal
+          )
+        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
+
+      # 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
+            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
+
+      # 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
+            parse_encoded_token body
           else
-            msg = "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
-            raise Signet::AuthorizationError, msg
+            Signet::OAuth2.parse_credentials body, content_type
           end
+        add_universe_domain_to hash
+        adjust_for_stale_expires_in hash, retrieval_time
+        hash
+      end
+
+      def parse_encoded_token body
+        hash = { token_type.to_s => body }
+        if token_type == :id_token
+          expires_at = expires_at_from_id_token body
+          hash["expires_at"] = expires_at if expires_at
         end
+        hash
+      end
+
+      def add_universe_domain_to hash
+        return if @universe_domain_overridden
+        universe_domain =
+          if disable_universe_domain_check
+            # TODO: Remove when universe domain metadata endpoint is stable (see b/349488459).
+            "googleapis.com"
+          else
+            Google::Cloud.env.lookup_metadata "universe", "universe-domain"
+          end
+        universe_domain = "googleapis.com" if !universe_domain || universe_domain.empty?
+        hash["universe_domain"] = universe_domain.strip
+      end
+
+      # The response might have been cached, which means expires_in might be
+      # stale. Update it based on the time since the data was retrieved.
+      # We also ensure expires_in is conservative; subtracting at least 1
+      # second to offset any skew from metadata server latency.
+      def adjust_for_stale_expires_in hash, retrieval_time
+        return unless hash["expires_in"].is_a? Numeric
+        offset = 1 + (Process.clock_gettime(Process::CLOCK_MONOTONIC) - retrieval_time).round
+        hash["expires_in"] -= offset if offset.positive?
+        hash["expires_in"] = 0 if hash["expires_in"].negative?
       end
     end
   end