googleauth 1.13.1 → 1.15.0

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

data/lib/googleauth/signet.rb

@@ -16,6 +16,7 @@ require "base64"
 require "json"
 require "signet/oauth_2/client"
 require "googleauth/base_client"
+require "googleauth/errors"
 
 module Signet
   # OAuth2 supports OAuth2 authentication.
@@ -109,17 +110,29 @@ module Signet
         end
       end
 
+      # rubocop:disable Metrics/MethodLength
+
+      # Retries the provided block with exponential backoff, handling and wrapping errors.
+      #
+      # @param [Integer] max_retry_count The maximum number of retries before giving up
+      # @yield The block to execute and potentially retry
+      # @return [Object] The result of the block if successful
+      # @raise [Google::Auth::AuthorizationError] If a Signet::AuthorizationError occurs or if retries are exhausted
+      # @raise [Google::Auth::ParseError] If a Signet::ParseError occurs during token parsing
       def retry_with_error max_retry_count = 5
         retry_count = 0
 
         begin
           yield.tap { |resp| log_response resp }
+        rescue Signet::AuthorizationError, Signet::ParseError => e
+          log_auth_error e
+          error_class = e.is_a?(Signet::ParseError) ? Google::Auth::ParseError : Google::Auth::AuthorizationError
+          raise error_class.with_details(
+            e.message,
+            credential_type_name: self.class.name,
+            principal: respond_to?(:principal) ? principal : :signet_client
+          )
         rescue StandardError => e
-          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
@@ -128,10 +141,15 @@ module Signet
           else
             log_retries_exhausted e
             msg = "Unexpected error: #{e.inspect}"
-            raise Signet::AuthorizationError, msg
+            raise Google::Auth::AuthorizationError.with_details(
+              msg,
+              credential_type_name: self.class.name,
+              principal: respond_to?(:principal) ? principal : :signet_client
+            )
           end
         end
       end
+      # rubocop:enable Metrics/MethodLength
 
       # Creates a duplicate of these credentials
       # without the Signet::OAuth2::Client-specific

data/lib/googleauth/user_authorizer.rb

@@ -63,12 +63,14 @@ module Google
       # @param [String] code_verifier
       #  Random string of 43-128 chars used to verify the key exchange using
       #  PKCE.
+      # @raise [Google::Auth::InitializationError]
+      #  If client_id is nil or scope is nil
       def initialize client_id, scope, token_store,
                      legacy_callback_uri = nil,
                      callback_uri: nil,
                      code_verifier: nil
-        raise NIL_CLIENT_ID_ERROR if client_id.nil?
-        raise NIL_SCOPE_ERROR if scope.nil?
+        raise InitializationError, NIL_CLIENT_ID_ERROR if client_id.nil?
+        raise InitializationError, NIL_SCOPE_ERROR if scope.nil?
 
         @client_id = client_id
         @scope = Array(scope)
@@ -133,14 +135,19 @@ module Google
       #  the requested scopes
       # @return [Google::Auth::UserRefreshCredentials]
       #  Stored credentials, nil if none present
+      # @raise [Google::Auth::CredentialsError]
+      #  If the client ID in the stored token doesn't match the configured client ID
       def get_credentials user_id, scope = nil
         saved_token = stored_token user_id
         return nil if saved_token.nil?
         data = MultiJson.load saved_token
 
         if data.fetch("client_id", @client_id.id) != @client_id.id
-          raise format(MISMATCHED_CLIENT_ID_ERROR,
-                       data["client_id"], @client_id.id)
+          raise CredentialsError.with_details(
+            format(MISMATCHED_CLIENT_ID_ERROR, data["client_id"], @client_id.id),
+            credential_type_name: self.class.name,
+            principal: principal
+          )
         end
 
         credentials = UserRefreshCredentials.new(
@@ -240,6 +247,8 @@ module Google
       #  Unique ID of the user for loading/storing credentials.
       # @param [Google::Auth::UserRefreshCredentials] credentials
       #  Credentials to store.
+      # @return [Google::Auth::UserRefreshCredentials]
+      #  The stored credentials
       def store_credentials user_id, credentials
         json = MultiJson.dump(
           client_id:              credentials.client_id,
@@ -269,6 +278,15 @@ module Google
         SecureRandom.alphanumeric random_number
       end
 
+      # Returns the principal identifier for this authorizer
+      # The client ID is used as the principal for user authorizers
+      #
+      # @private
+      # @return [String] The client ID associated with this authorizer
+      def principal
+        @client_id.id
+      end
+
       private
 
       # @private Fetch stored token with given user_id
@@ -276,9 +294,11 @@ module Google
       # @param [String] user_id
       #  Unique ID of the user for loading/storing credentials.
       # @return [String] The saved token from @token_store
+      # @raise [Google::Auth::InitializationError]
+      #  If user_id is nil or token_store is nil
       def stored_token user_id
-        raise NIL_USER_ID_ERROR if user_id.nil?
-        raise NIL_TOKEN_STORE_ERROR if @token_store.nil?
+        raise InitializationError, NIL_USER_ID_ERROR if user_id.nil?
+        raise InitializationError, NIL_TOKEN_STORE_ERROR if @token_store.nil?
 
         @token_store.load user_id
       end
@@ -303,9 +323,17 @@ module Google
       #  Absolute URL to resolve the callback against if necessary.
       # @return [String]
       #  Redirect URI
+      # @raise [Google::Auth::CredentialsError]
+      #  If the callback URI is relative and base_url is nil or not absolute
       def redirect_uri_for base_url
         return @callback_uri if uri_is_postmessage?(@callback_uri) || !URI(@callback_uri).scheme.nil?
-        raise format(MISSING_ABSOLUTE_URL_ERROR, @callback_uri) if base_url.nil? || URI(base_url).scheme.nil?
+        if base_url.nil? || URI(base_url).scheme.nil?
+          raise CredentialsError.with_details(
+            format(MISSING_ABSOLUTE_URL_ERROR, @callback_uri),
+            credential_type_name: self.class.name,
+            principal: principal
+          )
+        end
         URI.join(base_url, @callback_uri).to_s
       end
 

data/lib/googleauth/user_refresh.rb

@@ -12,9 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "googleauth/signet"
 require "googleauth/credentials_loader"
+require "googleauth/errors"
 require "googleauth/scope_util"
+require "googleauth/signet"
 require "multi_json"
 
 module Google
@@ -40,7 +41,7 @@ module Google
 
       # Create a UserRefreshCredentials.
       #
-      # @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
       def self.make_creds options = {}
         json_key_io, scope = options.values_at :json_key_io, :scope
@@ -64,13 +65,16 @@ module Google
           .configure_connection(options)
       end
 
-      # Reads the client_id, client_secret and refresh_token fields from the
-      # JSON key.
+      # Reads a JSON key from an IO object and extracts required fields.
+      #
+      # @param [IO] json_key_io An IO object containing the JSON key
+      # @return [Hash] The parsed JSON key
+      # @raise [Google::Auth::InitializationError] If the JSON is missing required fields
       def self.read_json_key json_key_io
         json_key = MultiJson.load json_key_io.read
         wanted = ["client_id", "client_secret", "refresh_token"]
         wanted.each do |key|
-          raise "the json is missing the #{key} field" unless json_key.key? key
+          raise InitializationError, "the json is missing the #{key} field" unless json_key.key? key
         end
         json_key
       end
@@ -106,6 +110,10 @@ module Google
       end
 
       # Revokes the credential
+      #
+      # @param [Hash] options Options for revoking the credential
+      # @option options [Faraday::Connection] :connection The connection to use
+      # @raise [Google::Auth::AuthorizationError] If the revocation request fails
       def revoke! options = {}
         c = options[:connection] || Faraday.default_connection
 
@@ -117,8 +125,11 @@ module Google
             self.refresh_token = nil
             self.expires_at = 0
           else
-            raise(Signet::AuthorizationError,
-                  "Unexpected error code #{resp.status}")
+            raise AuthorizationError.with_details(
+              "Unexpected error code #{resp.status}",
+              credential_type_name: self.class.name,
+              principal: principal
+            )
           end
         end
       end
@@ -157,6 +168,13 @@ module Google
 
         self
       end
+
+      # Returns the client ID as the principal for user refresh credentials
+      # @private
+      # @return [String, Symbol] the client ID or :user_refresh if not available
+      def principal
+        @client_id || :user_refresh
+      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.13.1".freeze
+    VERSION = "1.15.0".freeze
   end
 end

data/lib/googleauth/web_user_authorizer.rb

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 require "multi_json"
+require "googleauth/errors"
 require "googleauth/signet"
 require "googleauth/user_authorizer"
 require "googleauth/user_refresh"
@@ -79,6 +80,8 @@ module Google
       #
       # @param [Rack::Request] request
       #  Current request
+      # @return [String, nil]
+      #  Redirect URI if successfully extracted, nil otherwise
       def self.handle_auth_callback_deferred request
         callback_state, redirect_uri = extract_callback_state request
         request.session[CALLBACK_STATE_KEY] = MultiJson.dump callback_state
@@ -151,11 +154,13 @@ module Google
       #  Optional key-values to be returned to the oauth callback.
       # @return [String]
       #  Authorization url
+      # @raise [Google::Auth::InitializationError]
+      #  If request is nil or request.session is nil
       def get_authorization_url options = {}
         options = options.dup
         request = options[:request]
-        raise NIL_REQUEST_ERROR if request.nil?
-        raise NIL_SESSION_ERROR if request.session.nil?
+        raise InitializationError, NIL_REQUEST_ERROR if request.nil?
+        raise InitializationError, NIL_SESSION_ERROR if request.session.nil?
 
         state = options[:state] || {}
 
@@ -181,9 +186,9 @@ module Google
       #  requested scopes
       # @return [Google::Auth::UserRefreshCredentials]
       #  Stored credentials, nil if none present
-      # @raise [Signet::AuthorizationError]
-      #  May raise an error if an authorization code is present in the session
-      #  and exchange of the code fails
+      # @raise [Google::Auth::AuthorizationError]
+      #  If the authorization code is missing, there's an error in the request,
+      #  or the state token doesn't match
       def get_credentials user_id, request = nil, scope = nil
         if request&.session&.key? CALLBACK_STATE_KEY
           # Note - in theory, no need to check required scope as this is
@@ -202,6 +207,12 @@ module Google
         end
       end
 
+      # Extract the callback state from the request
+      #
+      # @param [Rack::Request] request
+      #  Current request
+      # @return [Array<Hash, String>]
+      #  Callback state and redirect URI
       def self.extract_callback_state request
         state = MultiJson.load(request.params[STATE_PARAM] || "{}")
         redirect_uri = state[CURRENT_URI_KEY]
@@ -214,6 +225,15 @@ module Google
         [callback_state, redirect_uri]
       end
 
+      # Returns the principal identifier for this web authorizer
+      # This is a class method that returns a symbol since
+      # we might not have a client_id in the static callback context
+      #
+      # @return [Symbol] The symbol for web user authorization
+      def self.principal
+        :web_user_authorization
+      end
+
       # Verifies the results of an authorization callback
       #
       # @param [Hash] state
@@ -224,13 +244,30 @@ module Google
       #  Error message if failed
       # @param [Rack::Request] request
       #  Current request
+      # @raise [Google::Auth::AuthorizationError]
+      #  If the authorization code is missing, there's an error in the callback state,
+      #  or the state token doesn't match
       def self.validate_callback_state state, request
-        raise Signet::AuthorizationError, MISSING_AUTH_CODE_ERROR if state[AUTH_CODE_KEY].nil?
+        if state[AUTH_CODE_KEY].nil?
+          raise AuthorizationError.with_details(
+            MISSING_AUTH_CODE_ERROR,
+            credential_type_name: name,
+            principal: principal
+          )
+        end
+
         if state[ERROR_CODE_KEY]
-          raise Signet::AuthorizationError,
-                format(AUTHORIZATION_ERROR, state[ERROR_CODE_KEY])
+          raise AuthorizationError.with_details(
+            format(AUTHORIZATION_ERROR, state[ERROR_CODE_KEY]),
+            credential_type_name: name,
+            principal: principal
+          )
         elsif request.session[XSRF_KEY] != state[SESSION_ID_KEY]
-          raise Signet::AuthorizationError, INVALID_STATE_TOKEN_ERROR
+          raise AuthorizationError.with_details(
+            INVALID_STATE_TOKEN_ERROR,
+            credential_type_name: name,
+            principal: principal
+          )
         end
       end
 

data/lib/googleauth.rb

@@ -13,9 +13,17 @@
 # limitations under the License.
 
 require "googleauth/application_default"
+require "googleauth/api_key"
+require "googleauth/bearer_token"
 require "googleauth/client_id"
 require "googleauth/credentials"
 require "googleauth/default_credentials"
+require "googleauth/errors"
+require "googleauth/external_account"
 require "googleauth/id_tokens"
+require "googleauth/impersonated_service_account"
+require "googleauth/service_account"
+require "googleauth/service_account_jwt_header"
 require "googleauth/user_authorizer"
+require "googleauth/user_refresh"
 require "googleauth/web_user_authorizer"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: googleauth
 version: !ruby/object:Gem::Version
-  version: 1.13.1
+  version: 1.15.0
 platform: ruby
 authors:
-- Tim Emiola
+- Google LLC
 bindir: bin
 cert_chain: []
-date: 2025-01-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -66,7 +66,7 @@ dependencies:
         version: '1.4'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -76,7 +76,7 @@ dependencies:
         version: '1.4'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement
@@ -134,7 +134,7 @@ dependencies:
 description: Implements simple authorization for accessing Google APIs, and provides
   support for Application Default Credentials.
 email:
-- temiola@google.com
+- googleapis-packages@google.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -142,17 +142,22 @@ files:
 - ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- Credentials.md
+- Errors.md
 - LICENSE
 - README.md
 - SECURITY.md
 - lib/googleauth.rb
+- lib/googleauth/api_key.rb
 - lib/googleauth/application_default.rb
 - lib/googleauth/base_client.rb
+- lib/googleauth/bearer_token.rb
 - lib/googleauth/client_id.rb
 - lib/googleauth/compute_engine.rb
 - lib/googleauth/credentials.rb
 - lib/googleauth/credentials_loader.rb
 - lib/googleauth/default_credentials.rb
+- lib/googleauth/errors.rb
 - lib/googleauth/external_account.rb
 - lib/googleauth/external_account/aws_credentials.rb
 - lib/googleauth/external_account/base_credentials.rb
@@ -170,6 +175,7 @@ files:
 - lib/googleauth/oauth2/sts_client.rb
 - lib/googleauth/scope_util.rb
 - lib/googleauth/service_account.rb
+- lib/googleauth/service_account_jwt_header.rb
 - lib/googleauth/signet.rb
 - lib/googleauth/stores/file_token_store.rb
 - lib/googleauth/stores/redis_token_store.rb
@@ -192,14 +198,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Google Auth Library for Ruby
 test_files: []