googleauth 1.8.0 → 1.15.0

data/lib/googleauth/json_key_reader.rb

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "googleauth/errors"
+
 module Google
   # Module Auth provides classes that provide Google-specific authorization
   # used to access Google APIs.
@@ -19,15 +21,23 @@ module Google
     # JsonKeyReader contains the behaviour used to read private key and
     # client email fields from the service account
     module JsonKeyReader
+      # Reads a JSON key from an IO object and extracts common fields.
+      #
+      # @param json_key_io [IO] An IO object containing the JSON key
+      # @return [Array(String, String, String, String, String)] An array containing:
+      #   private_key, client_email, project_id, quota_project_id, and universe_domain
+      # @raise [Google::Auth::InitializationError] If client_email or private_key
+      #   fields are missing from the JSON
       def read_json_key json_key_io
         json_key = MultiJson.load json_key_io.read
-        raise "missing client_email" unless json_key.key? "client_email"
-        raise "missing private_key" unless json_key.key? "private_key"
+        raise InitializationError, "missing client_email" unless json_key.key? "client_email"
+        raise InitializationError, "missing private_key" unless json_key.key? "private_key"
         [
           json_key["private_key"],
           json_key["client_email"],
           json_key["project_id"],
-          json_key["quota_project_id"]
+          json_key["quota_project_id"],
+          json_key["universe_domain"]
         ]
       end
     end

data/lib/googleauth/oauth2/sts_client.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "googleauth/errors"
 require "googleauth/helpers/connection"
 
 module Google
@@ -36,10 +37,12 @@ module Google
 
         # Create a new instance of the STSClient.
         #
-        # @param [String] token_exchange_endpoint
-        #  The token exchange endpoint.
+        # @param [Hash] options Configuration options
+        # @option options [String] :token_exchange_endpoint The token exchange endpoint
+        # @option options [Faraday::Connection] :connection The Faraday connection to use
+        # @raise [Google::Auth::InitializationError] If token_exchange_endpoint is nil
         def initialize options = {}
-          raise "Token exchange endpoint can not be nil" if options[:token_exchange_endpoint].nil?
+          raise InitializationError, "Token exchange endpoint can not be nil" if options[:token_exchange_endpoint].nil?
           self.default_connection = options[:connection]
           @token_exchange_endpoint = options[:token_exchange_endpoint]
         end
@@ -67,6 +70,8 @@ module Google
         #   The optional additional headers to pass to the token exchange endpoint.
         #
         # @return [Hash] A hash containing the token exchange response.
+        # @raise [ArgumentError] If required options are missing
+        # @raise [Google::Auth::AuthorizationError] If the token exchange request fails
         def exchange_token options = {}
           missing_required_opts = [:grant_type, :subject_token, :subject_token_type] - options.keys
           unless missing_required_opts.empty?
@@ -81,7 +86,7 @@ module Google
           response = connection.post @token_exchange_endpoint, URI.encode_www_form(request_body), headers
 
           if response.status != 200
-            raise "Token exchange failed with status #{response.status}"
+            raise AuthorizationError, "Token exchange failed with status #{response.status}"
           end
 
           MultiJson.load response.body

data/lib/googleauth/scope_util.rb

@@ -57,7 +57,7 @@ module Google
       #
       # @param scope [String,Array<String>] Input scope(s)
       # @return [Array<String>] Always an array of strings
-      # @raise ArgumentError If the input is not a string or array of strings
+      # @raise [ArgumentError] If the input is not a string or array of strings
       #
       def self.as_array scope
         case scope

data/lib/googleauth/service_account.rb

@@ -12,13 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "googleauth/signet"
-require "googleauth/credentials_loader"
-require "googleauth/json_key_reader"
 require "jwt"
 require "multi_json"
 require "stringio"
 
+require "google/logging/message"
+require "googleauth/signet"
+require "googleauth/credentials_loader"
+require "googleauth/json_key_reader"
+require "googleauth/service_account_jwt_header"
+
 module Google
   # Module Auth provides classes that provide Google-specific authorization
   # used to access Google APIs.
@@ -39,13 +42,18 @@ module Google
       attr_reader :quota_project_id
 
       def enable_self_signed_jwt?
-        @enable_self_signed_jwt
+        # Use a self-singed JWT if there's no information that can be used to
+        # obtain an OAuth token, OR if there are scopes but also an assertion
+        # that they are default scopes that shouldn't be used to fetch a token,
+        # OR we are not in the default universe and thus OAuth isn't supported.
+        target_audience.nil? && (scope.nil? || @enable_self_signed_jwt || universe_domain != "googleapis.com")
       end
 
       # Creates a ServiceAccountCredentials.
       #
-      # @param json_key_io [IO] an IO from which the JSON key can be read
+      # @param json_key_io [IO] An IO object containing the JSON key
       # @param scope [string|array|nil] the scope(s) to access
+      # @raise [ArgumentError] If both scope and target_audience are specified
       def self.make_creds options = {}
         json_key_io, scope, enable_self_signed_jwt, target_audience, audience, token_credential_uri =
           options.values_at :json_key_io, :scope, :enable_self_signed_jwt, :target_audience,
@@ -53,12 +61,13 @@ module Google
         raise ArgumentError, "Cannot specify both scope and target_audience" if scope && target_audience
 
         if json_key_io
-          private_key, client_email, project_id, quota_project_id = read_json_key json_key_io
+          private_key, client_email, project_id, quota_project_id, universe_domain = read_json_key json_key_io
         else
           private_key = unescape ENV[CredentialsLoader::PRIVATE_KEY_VAR]
           client_email = ENV[CredentialsLoader::CLIENT_EMAIL_VAR]
           project_id = ENV[CredentialsLoader::PROJECT_ID_VAR]
           quota_project_id = nil
+          universe_domain = nil
         end
         project_id ||= CredentialsLoader.load_gcloud_project_id
 
@@ -70,13 +79,41 @@ module Google
             issuer:                 client_email,
             signing_key:            OpenSSL::PKey::RSA.new(private_key),
             project_id:             project_id,
-            quota_project_id:       quota_project_id)
+            quota_project_id:       quota_project_id,
+            universe_domain:        universe_domain || "googleapis.com")
           .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.
+      #
+      # @param str [String] The string to unescape
+      # @return [String] The unescaped string
       def self.unescape str
         str = str.gsub '\n', "\n"
         str = str[1..-2] if str.start_with?('"') && str.end_with?('"')
@@ -93,16 +130,51 @@ module Google
       # Extends the base class to use a transient
       # ServiceAccountJwtHeaderCredentials for certain cases.
       def apply! a_hash, opts = {}
-        # Use a self-singed JWT if there's no information that can be used to
-        # obtain an OAuth token, OR if there are scopes but also an assertion
-        # that they are default scopes that shouldn't be used to fetch a token.
-        if target_audience.nil? && (scope.nil? || enable_self_signed_jwt?)
+        if enable_self_signed_jwt?
           apply_self_signed_jwt! a_hash
         else
           super
         end
       end
 
+      # Modifies this logic so it also requires self-signed-jwt to be disabled
+      def needs_access_token?
+        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
+
+      # Returns the client email as the principal for service account credentials
+      # @private
+      # @return [String] the email address of the service account
+      def principal
+        @issuer
+      end
+
       private
 
       def apply_self_signed_jwt! a_hash
@@ -115,101 +187,9 @@ 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
-
-    # Authenticates requests using Google's Service Account credentials via
-    # JWT Header.
-    #
-    # This class allows authorizing requests for service accounts directly
-    # from credentials from a json key file downloaded from the developer
-    # console (via 'Generate new Json Key').  It is not part of any OAuth2
-    # flow, rather it creates a JWT and sends that as a credential.
-    #
-    # cf [Application Default Credentials](https://cloud.google.com/docs/authentication/production)
-    class ServiceAccountJwtHeaderCredentials
-      JWT_AUD_URI_KEY = :jwt_aud_uri
-      AUTH_METADATA_KEY = Google::Auth::BaseClient::AUTH_METADATA_KEY
-      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
-
-      # Create a ServiceAccountJwtHeaderCredentials.
-      #
-      # @param json_key_io [IO] an IO from which the JSON key can be read
-      # @param scope [string|array|nil] the scope(s) to access
-      def self.make_creds options = {}
-        json_key_io, scope = options.values_at :json_key_io, :scope
-        new json_key_io: json_key_io, scope: scope
-      end
-
-      # Initializes a ServiceAccountJwtHeaderCredentials.
-      #
-      # @param json_key_io [IO] an IO from which the JSON key can be read
-      def initialize options = {}
-        json_key_io = options[:json_key_io]
-        if json_key_io
-          @private_key, @issuer, @project_id, @quota_project_id =
-            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
-        end
-        @project_id ||= CredentialsLoader.load_gcloud_project_id
-        @signing_key = OpenSSL::PKey::RSA.new @private_key
-        @scope = options[:scope]
-      end
-
-      # Construct a jwt token if the JWT_AUD_URI key is present in the input
-      # hash.
-      #
-      # The jwt token is used as the value of a 'Bearer '.
-      def apply! a_hash, opts = {}
-        jwt_aud_uri = a_hash.delete JWT_AUD_URI_KEY
-        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}"
-        a_hash
-      end
-
-      # Returns a clone of a_hash updated with the authoriation header
-      def apply a_hash, opts = {}
-        a_copy = a_hash.clone
-        apply! a_copy, opts
-        a_copy
-      end
-
-      # Returns a reference to the #apply method, suitable for passing as
-      # a closure
-      def updater_proc
-        proc { |a_hash, opts = {}| apply a_hash, opts }
-      end
-
-      # Creates a jwt uri token.
-      def new_jwt_token jwt_aud_uri = nil, options = {}
-        now = Time.new
-        skew = options[:skew] || 60
-        assertion = {
-          "iss" => @issuer,
-          "sub" => @issuer,
-          "exp" => (now + EXPIRY).to_i,
-          "iat" => (now - skew).to_i
-        }
-
-        jwt_aud_uri = nil if @scope
-
-        assertion["scope"] = Array(@scope).join " " if @scope
-        assertion["aud"] = jwt_aud_uri if jwt_aud_uri
-
-        JWT.encode assertion, @signing_key, SIGNING_ALGORITHM
-      end
-    end
   end
 end

data/lib/googleauth/service_account_jwt_header.rb

@@ -0,0 +1,187 @@
+# Copyright 2025 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 "google/logging/message"
+require "googleauth/credentials_loader"
+require "googleauth/json_key_reader"
+require "jwt"
+
+module Google
+  # Module Auth provides classes that provide Google-specific authorization
+  # used to access Google APIs.
+  module Auth
+    # Authenticates requests using Google's Service Account credentials via
+    # JWT Header.
+    #
+    # This class allows authorizing requests for service accounts directly
+    # from credentials from a json key file downloaded from the developer
+    # console (via 'Generate new Json Key').  It is not part of any OAuth2
+    # flow, rather it creates a JWT and sends that as a credential.
+    #
+    # cf [Application Default Credentials](https://cloud.google.com/docs/authentication/production)
+    class ServiceAccountJwtHeaderCredentials
+      JWT_AUD_URI_KEY = :jwt_aud_uri
+      AUTH_METADATA_KEY = Google::Auth::BaseClient::AUTH_METADATA_KEY
+      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
+      attr_accessor :logger
+
+      # Create a ServiceAccountJwtHeaderCredentials.
+      #
+      # @param json_key_io [IO] An IO object containing the JSON key
+      # @param scope [string|array|nil] the scope(s) to access
+      def self.make_creds options = {}
+        json_key_io, scope = options.values_at :json_key_io, :scope
+        new json_key_io: json_key_io, scope: scope
+      end
+
+      # Initializes a ServiceAccountJwtHeaderCredentials.
+      #
+      # @param json_key_io [IO] An IO object containing the JSON key
+      def initialize options = {}
+        json_key_io = options[:json_key_io]
+        if json_key_io
+          @private_key, @issuer, @project_id, @quota_project_id, @universe_domain =
+            self.class.read_json_key json_key_io
+        else
+          @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] if options.key? :scope
+        @logger = options[:logger] if options.key? :logger
+      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
+      # hash.
+      #
+      # The jwt token is used as the value of a 'Bearer '.
+      def apply! a_hash, opts = {}
+        jwt_aud_uri = a_hash.delete JWT_AUD_URI_KEY
+        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 authorization header
+      def apply a_hash, opts = {}
+        a_copy = a_hash.clone
+        apply! a_copy, opts
+        a_copy
+      end
+
+      # Returns a reference to the #apply method, suitable for passing as
+      # a closure
+      def updater_proc
+        proc { |a_hash, opts = {}| apply a_hash, opts }
+      end
+
+      # Creates a jwt uri token.
+      def new_jwt_token jwt_aud_uri = nil, options = {}
+        now = Time.new
+        skew = options[:skew] || 60
+        assertion = {
+          "iss" => @issuer,
+          "sub" => @issuer,
+          "exp" => (now + EXPIRY).to_i,
+          "iat" => (now - skew).to_i
+        }
+
+        jwt_aud_uri = nil if @scope
+
+        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
+
+      # Duck-types the corresponding method from BaseClient
+      def needs_access_token?
+        false
+      end
+
+      # Returns the client email as the principal for service account JWT header credentials
+      # @private
+      # @return [String] the email address of the service account
+      def principal
+        @issuer
+      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