googleauth 1.14.0 → 1.15.1

data/lib/googleauth/id_tokens.rb

@@ -160,8 +160,8 @@ module Google
         #     checking is performed. Default is to check against {OIDC_ISSUERS}.
         #
         # @return [Hash] The decoded token payload.
-        # @raise [KeySourceError] if the key source failed to obtain public keys
-        # @raise [VerificationError] if the token verification failed.
+        # @raise [Google::Auth::IDTokens::KeySourceError] if the key source failed to obtain public keys
+        # @raise [Google::Auth::IDTokens::VerificationError] if the token verification failed.
         #     Additional data may be available in the error subclass and message.
         #
         def verify_oidc token,
@@ -197,8 +197,8 @@ module Google
         #     checking is performed. Default is to check against {IAP_ISSUERS}.
         #
         # @return [Hash] The decoded token payload.
-        # @raise [KeySourceError] if the key source failed to obtain public keys
-        # @raise [VerificationError] if the token verification failed.
+        # @raise [Google::Auth::IDTokens::KeySourceError] if the key source failed to obtain public keys
+        # @raise [Google::Auth::IDTokens::VerificationError] if the token verification failed.
         #     Additional data may be available in the error subclass and message.
         #
         def verify_iap token,

data/lib/googleauth/impersonated_service_account.rb

@@ -12,8 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "googleauth/signet"
 require "googleauth/base_client"
+require "googleauth/errors"
 require "googleauth/helpers/connection"
 
 module Google
@@ -191,6 +191,20 @@ module Google
         self.class.new options
       end
 
+      # The principal behind the credentials. This class allows custom source credentials type
+      # that might not implement `principal`, in which case `:unknown` is returned.
+      #
+      # @private
+      # @return [String, Symbol] The string representation of the principal,
+      #     the token type in lieu of the principal, or :unknown if source principal is unknown.
+      def principal
+        if @source_credentials.respond_to? :principal
+          @source_credentials.principal
+        else
+          :unknown
+        end
+      end
+
       private
 
       # Generates a new impersonation access token by exchanging the source credentials' token
@@ -200,21 +214,16 @@ module Google
       # for an impersonation token using the specified impersonation URL. The generated token and
       # its expiration time are cached for subsequent use.
       #
+      # @private
       # @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.
+      # @raise [Google::Auth::UnexpectedStatusError] If the response status is 403 or 500.
+      # @raise [Google::Auth::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
+        auth_header = prepare_auth_header
+        resp = make_impersonation_request auth_header
 
         case resp.status
         when 200
@@ -223,14 +232,51 @@ module Google
           @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
+          handle_error_response resp, UnexpectedStatusError
         else
-          msg = "Unexpected error code #{resp.status}.\n #{resp.env.response_body} #{ERROR_SUFFIX}"
-          raise Signet::AuthorizationError, msg
+          handle_error_response resp, AuthorizationError
+        end
+      end
+
+      # Prepares the authorization header for the impersonation request
+      # by fetching a token from source credentials.
+      #
+      # @private
+      # @return [Hash] The authorization header with the source credentials' token
+      def prepare_auth_header
+        auth_header = {}
+        @source_credentials.updater_proc.call auth_header
+        auth_header
+      end
+
+      # Makes the HTTP request to the impersonation endpoint.
+      #
+      # @private
+      # @param [Hash] auth_header The authorization header containing the source token
+      # @return [Faraday::Response] The HTTP response from the impersonation endpoint
+      def make_impersonation_request auth_header
+        connection.post @impersonation_url do |req|
+          req.headers.merge! auth_header
+          req.headers["Content-Type"] = "application/json"
+          req.body = MultiJson.dump({ scope: @scope })
         end
       end
 
+      # Creates and raises an appropriate error based on the response.
+      #
+      # @private
+      # @param [Faraday::Response] resp The HTTP response
+      # @param [Class] error_class The error class to instantiate
+      # @raise [StandardError] The appropriate error with details
+      def handle_error_response resp, error_class
+        msg = "Unexpected error code #{resp.status}.\n #{resp.env.response_body} #{ERROR_SUFFIX}"
+        raise error_class.with_details(
+          msg,
+          credential_type_name: self.class.name,
+          principal: principal
+        )
+      end
+
       # Setter for the expires_at value that makes sure it is converted
       # to Time object.
       def expires_at= new_expires_at
@@ -249,7 +295,7 @@ module Google
       #
       # @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.
+      # @raise [Google::Auth::CredentialsError] If the input is not a Time, String, or nil.
       def normalize_timestamp time
         case time
         when NilClass
@@ -259,7 +305,8 @@ module Google
         when String
           Time.parse time
         else
-          raise "Invalid time value #{time}"
+          message = "Invalid time value #{time}"
+          raise CredentialsError.with_details(message, credential_type_name: self.class.name, principal: principal)
         end
       end
 

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,10 +21,17 @@ 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"],

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

@@ -41,6 +41,10 @@ module Google
       attr_reader :project_id
       attr_reader :quota_project_id
 
+      # @private
+      # @type [::String] The type name for this credential.
+      CREDENTIAL_TYPE_NAME = "service_account".freeze
+
       def 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
@@ -51,23 +55,22 @@ module Google
 
       # 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,
                             :audience, :token_credential_uri
         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, 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
+        private_key, client_email, project_id, quota_project_id, universe_domain =
+          if json_key_io
+            CredentialsLoader.load_and_verify_json_key_type json_key_io, CREDENTIAL_TYPE_NAME
+            read_json_key json_key_io
+          else
+            creds_from_env
+          end
         project_id ||= CredentialsLoader.load_gcloud_project_id
 
         new(token_credential_uri:   token_credential_uri || TOKEN_CRED_URI,
@@ -110,6 +113,9 @@ module Google
       # 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?('"')
@@ -164,6 +170,13 @@ module Google
         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
@@ -179,6 +192,20 @@ module Google
         alt.logger = logger
         alt.apply! a_hash
       end
+
+      # @private
+      # Loads service account credential details from environment variables.
+      #
+      # @return [Array<String, String, String, nil, nil>] An array containing private_key,
+      #   client_email, project_id, quota_project_id, and universe_domain.
+      def self.creds_from_env
+        private_key = unescape ENV[CredentialsLoader::PRIVATE_KEY_VAR]
+        client_email = ENV[CredentialsLoader::CLIENT_EMAIL_VAR]
+        project_id = ENV[CredentialsLoader::PROJECT_ID_VAR]
+        [private_key, client_email, project_id, nil, nil]
+      end
+
+      private_class_method :creds_from_env
     end
   end
 end

data/lib/googleauth/service_account_jwt_header.rb

@@ -47,7 +47,7 @@ module Google
 
       # Create a ServiceAccountJwtHeaderCredentials.
       #
-      # @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
@@ -56,7 +56,7 @@ module Google
 
       # Initializes a ServiceAccountJwtHeaderCredentials.
       #
-      # @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
       def initialize options = {}
         json_key_io = options[:json_key_io]
         if json_key_io
@@ -159,6 +159,13 @@ module Google
         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

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
@@ -38,21 +39,29 @@ module Google
       attr_reader :project_id
       attr_reader :quota_project_id
 
+      # @private
+      # @type [::String] The type name for this credential.
+      CREDENTIAL_TYPE_NAME = "authorized_user".freeze
+
       # 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
-        user_creds = read_json_key json_key_io if json_key_io
-        user_creds ||= {
-          "client_id"     => ENV[CredentialsLoader::CLIENT_ID_VAR],
-          "client_secret" => ENV[CredentialsLoader::CLIENT_SECRET_VAR],
-          "refresh_token" => ENV[CredentialsLoader::REFRESH_TOKEN_VAR],
-          "project_id"    => ENV[CredentialsLoader::PROJECT_ID_VAR],
-          "quota_project_id" => nil,
-          "universe_domain" => nil
-        }
+        user_creds = if json_key_io
+                       CredentialsLoader.load_and_verify_json_key_type json_key_io, CREDENTIAL_TYPE_NAME
+                       read_json_key json_key_io
+                     else
+                       {
+                         "client_id"     => ENV[CredentialsLoader::CLIENT_ID_VAR],
+                         "client_secret" => ENV[CredentialsLoader::CLIENT_SECRET_VAR],
+                         "refresh_token" => ENV[CredentialsLoader::REFRESH_TOKEN_VAR],
+                         "project_id"    => ENV[CredentialsLoader::PROJECT_ID_VAR],
+                         "quota_project_id" => nil,
+                         "universe_domain" => nil
+                       }
+                     end
         new(token_credential_uri: TOKEN_CRED_URI,
             client_id:            user_creds["client_id"],
             client_secret:        user_creds["client_secret"],
@@ -64,13 +73,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 +118,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 +133,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 +176,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.14.0".freeze
+    VERSION = "1.15.1".freeze
   end
 end