googleauth 1.14.0 → 1.17.0

data/lib/googleauth/external_account/aws_credentials.rb

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 require "time"
+require "json"
+require "googleauth/errors"
 require "googleauth/external_account/base_credentials"
 require "googleauth/external_account/external_account_utils"
 
@@ -106,17 +108,32 @@ module Google
 
         private
 
+        # Retrieves an IMDSv2 session token or returns a cached token if valid
+        #
+        # @return [String] The IMDSv2 session token
+        # @raise [Google::Auth::CredentialsError] If the token URL is missing or there's an error retrieving the token
         def imdsv2_session_token
           return @imdsv2_session_token unless imdsv2_session_token_invalid?
-          raise "IMDSV2 token url must be provided" if @imdsv2_session_token_url.nil?
+          if @imdsv2_session_token_url.nil?
+            raise CredentialsError.with_details(
+              "IMDSV2 token url must be provided",
+              credential_type_name: self.class.name,
+              principal: principal
+            )
+          end
           begin
             response = connection.put @imdsv2_session_token_url do |req|
               req.headers["x-aws-ec2-metadata-token-ttl-seconds"] = IMDSV2_TOKEN_EXPIRATION_IN_SECONDS.to_s
             end
+            raise Faraday::Error unless response.success?
           rescue Faraday::Error => e
-            raise "Fetching AWS IMDSV2 token error: #{e}"
+            raise CredentialsError.with_details(
+              "Fetching AWS IMDSV2 token error: #{e}",
+              credential_type_name: self.class.name,
+              principal: principal
+            )
           end
-          raise Faraday::Error unless response.success?
+
           @imdsv2_session_token = response.body
           @imdsv2_session_token_expiry = Time.now + IMDSV2_TOKEN_EXPIRATION_IN_SECONDS
           @imdsv2_session_token
@@ -127,6 +144,14 @@ module Google
           @imdsv2_session_token_expiry.nil? || @imdsv2_session_token_expiry < Time.now
         end
 
+        # Makes a request to an AWS resource endpoint
+        #
+        # @param [String] url The AWS endpoint URL
+        # @param [String] name Resource name for error messages
+        # @param [Hash, nil] data Optional data to send in POST requests
+        # @param [Hash] headers Optional request headers
+        # @return [Faraday::Response] The successful response
+        # @raise [Google::Auth::CredentialsError] If the request fails
         def get_aws_resource url, name, data: nil, headers: {}
           begin
             headers["x-aws-ec2-metadata-token"] = imdsv2_session_token
@@ -136,11 +161,14 @@ module Google
                        else
                          connection.get url, nil, headers
                        end
-
             raise Faraday::Error unless response.success?
             response
           rescue Faraday::Error
-            raise "Failed to retrieve AWS #{name}."
+            raise CredentialsError.with_details(
+              "Failed to retrieve AWS #{name}.",
+              credential_type_name: self.class.name,
+              principal: principal
+            )
           end
         end
 
@@ -181,9 +209,16 @@ module Google
         # Retrieves the AWS role currently attached to the current AWS workload by querying the AWS metadata server.
         # This is needed for the AWS metadata server security credentials endpoint in order to retrieve the AWS security
         # credentials needed to sign requests to AWS APIs.
+        #
+        # @return [String] The AWS role name
+        # @raise [Google::Auth::CredentialsError] If the credential verification URL is not set or if the request fails
         def fetch_metadata_role_name
           unless @credential_verification_url
-            raise "Unable to determine the AWS metadata server security credentials endpoint"
+            raise CredentialsError.with_details(
+              "Unable to determine the AWS metadata server security credentials endpoint",
+              credential_type_name: self.class.name,
+              principal: principal
+            )
           end
 
           get_aws_resource(@credential_verification_url, "IAM Role").body
@@ -192,14 +227,25 @@ module Google
         # Retrieves the AWS security credentials required for signing AWS requests from the AWS metadata server.
         def fetch_metadata_security_credentials role_name
           response = get_aws_resource "#{@credential_verification_url}/#{role_name}", "credentials"
-          MultiJson.load response.body
+          JSON.parse response.body
         end
 
+        # Reads the name of the AWS region from the environment
+        #
+        # @return [String] The name of the AWS region
+        # @raise [Google::Auth::CredentialsError] If the region is not set in the environment
+        #   and the region_url was not set in credentials source
         def region
           @region = ENV[CredentialsLoader::AWS_REGION_VAR] || ENV[CredentialsLoader::AWS_DEFAULT_REGION_VAR]
 
           unless @region
-            raise "region_url or region must be set for external account credentials" unless @region_url
+            unless @region_url
+              raise CredentialsError.with_details(
+                "region_url or region must be set for external account credentials",
+                credential_type_name: self.class.name,
+                principal: principal
+              )
+            end
 
             @region ||= get_aws_resource(@region_url, "region").body[0..-2]
           end
@@ -220,23 +266,45 @@ module Google
           @region_name = region_name
         end
 
-        # Generates the signed request for the provided HTTP request for calling
-        # an AWS API. This follows the steps described at:
+        # Generates an AWS signature version 4 signed request.
+        #
+        # Creates a signed request following the AWS Signature Version 4 process, which
+        # provides secure authentication for AWS API calls. The process includes creating
+        # canonical request strings, calculating signatures using the AWS credentials, and
+        # building proper authorization headers.
+        #
+        # For detailed information on the signing process, see:
         # https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html
         #
-        # @param [Hash[string, string]] aws_security_credentials
-        #     A dictionary containing the AWS security credentials.
-        # @param [string] url
-        #     The AWS service URL containing the canonical URI and query string.
-        # @param [string] method
-        #     The HTTP method used to call this API.
+        # @param [Hash] aws_credentials The AWS security credentials with the following keys:
+        #   @option aws_credentials [String] :access_key_id The AWS access key ID
+        #   @option aws_credentials [String] :secret_access_key The AWS secret access key
+        #   @option aws_credentials [String, nil] :session_token Optional AWS session token
+        # @param [Hash] original_request The request to sign with the following keys:
+        #   @option original_request [String] :url The AWS service URL (must be HTTPS)
+        #   @option original_request [String] :method The HTTP method (GET, POST, etc.)
+        #   @option original_request [Hash, nil] :headers Optional request headers
+        #   @option original_request [String, nil] :data Optional request payload
+        #
+        # @return [Hash] The signed request with the following keys:
+        #   * :url - The original URL as a string
+        #   * :headers - A hash of headers with the authorization header added
+        #   * :method - The HTTP method
+        #   * :data - The request payload (if present)
         #
-        # @return [hash{string => string}]
-        #     The AWS signed request dictionary object.
+        # @raise [Google::Auth::CredentialsError] If the AWS service URL is invalid
         #
         def generate_signed_request aws_credentials, original_request
           uri = Addressable::URI.parse original_request[:url]
-          raise "Invalid AWS service URL" unless uri.hostname && uri.scheme == "https"
+          unless uri.hostname && uri.scheme == "https"
+            # NOTE: We use AwsCredentials name but can't access its principal since AwsRequestSigner
+            # is a separate class and not a credential object with access to the audience
+            raise CredentialsError.with_details(
+              "Invalid AWS service URL",
+              credential_type_name: AwsCredentials.name,
+              principal: "aws"
+            )
+          end
           service_name = uri.host.split(".").first
 
           datetime = Time.now.utc.strftime "%Y%m%dT%H%M%SZ"

data/lib/googleauth/external_account/base_credentials.rb

@@ -12,7 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.require "time"
 
+require "json"
 require "googleauth/base_client"
+require "googleauth/errors"
 require "googleauth/helpers/connection"
 require "googleauth/oauth2/sts_client"
 
@@ -89,6 +91,14 @@ module Google
           %r{/iam\.googleapis\.com/locations/[^/]+/workforcePools/}.match?(@audience || "")
         end
 
+        # For external account credentials, the principal is
+        # represented by the audience, such as a workforce pool
+        # @private
+        # @return [String] the GCP principal, e.g. a workforce pool
+        def principal
+          @audience
+        end
+
         private
 
         def token_type
@@ -96,6 +106,8 @@ module Google
           :access_token
         end
 
+        # A common method for Other credentials to call during initialization
+        # @raise [Google::Auth::InitializationError] If workforce_pool_user_project is incorrectly set
         def base_setup options
           self.default_connection = options[:connection]
 
@@ -121,9 +133,11 @@ module Google
             connection: default_connection
           )
           return unless @workforce_pool_user_project && !is_workforce_pool?
-          raise "workforce_pool_user_project should not be set for non-workforce pool credentials."
+          raise InitializationError, "workforce_pool_user_project should not be set for non-workforce pool credentials."
         end
 
+        # Exchange tokens at STS endpoint
+        # @raise [Google::Auth::AuthorizationError] If the token exchange request fails
         def exchange_token
           additional_options = nil
           if @client_id.nil? && @workforce_pool_user_project
@@ -140,6 +154,12 @@ module Google
           }
           log_token_request token_request
           @sts_client.exchange_token token_request
+        rescue Google::Auth::AuthorizationError => e
+          raise Google::Auth::AuthorizationError.with_details(
+            e.message,
+            credential_type_name: self.class.name,
+            principal: principal
+          )
         end
 
         def log_token_request token_request
@@ -160,19 +180,29 @@ module Google
           end
         end
 
+        # Exchanges a token for an impersonated service account access token
+        #
+        # @param [String] token The token to exchange
+        # @param [Hash] _options Additional options (not used)
+        # @return [Hash] The response containing the impersonated access token
+        # @raise [Google::Auth::CredentialsError] If the impersonation request fails
         def get_impersonated_access_token token, _options = {}
           log_impersonated_token_request token
           response = connection.post @service_account_impersonation_url do |req|
             req.headers["Authorization"] = "Bearer #{token}"
             req.headers["Content-Type"] = "application/json"
-            req.body = MultiJson.dump({ scope: @scope })
+            req.body = JSON.generate({ scope: @scope })
           end
 
           if response.status != 200
-            raise "Service account impersonation failed with status #{response.status}"
+            raise CredentialsError.with_details(
+              "Service account impersonation failed with status #{response.status}",
+              credential_type_name: self.class.name,
+              principal: principal
+            )
           end
 
-          MultiJson.load response.body
+          JSON.parse response.body
         end
 
         def log_impersonated_token_request original_token

data/lib/googleauth/external_account/external_account_utils.rb

@@ -12,7 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.require "time"
 
+require "json"
 require "googleauth/base_client"
+require "googleauth/errors"
 require "googleauth/helpers/connection"
 require "googleauth/oauth2/sts_client"
 
@@ -36,8 +38,8 @@ module Google
         # call this API or the required scopes may not be selected:
         # https://cloud.google.com/resource-manager/reference/rest/v1/projects/get#authorization-scopes
         #
-        # @return [string,nil]
-        #     The project ID corresponding to the workload identity pool or workforce pool if determinable.
+        # @return [String, nil] The project ID corresponding to the workload identity
+        #   pool or workforce pool if determinable
         #
         def project_id
           return @project_id unless @project_id.nil?
@@ -53,7 +55,7 @@ module Google
           end
 
           if response.status == 200
-            response_data = MultiJson.load response.body, symbolize_names: true
+            response_data = JSON.parse response.body, symbolize_names: true
             @project_id = response_data[:projectId]
           end
 
@@ -65,7 +67,8 @@ module Google
         # STS audience pattern:
         #     `//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/...`
         #
-        # @return [string, nil]
+        # @return [String, nil] The project number extracted from the audience string,
+        #   or nil if it cannot be determined
         #
         def project_number
           segments = @audience.split "/"
@@ -74,6 +77,11 @@ module Google
           segments[idx + 1]
         end
 
+        # Normalizes a timestamp value to a Time object
+        #
+        # @param time [Time, String, nil] The timestamp to normalize
+        # @return [Time, nil] The normalized timestamp or nil if input is nil
+        # @raise [Google::Auth::CredentialsError] If the time value is not nil, Time, or String
         def normalize_timestamp time
           case time
           when NilClass
@@ -83,10 +91,14 @@ module Google
           when String
             Time.parse time
           else
-            raise "Invalid time value #{time}"
+            raise CredentialsError, "Invalid time value #{time}"
           end
         end
 
+        # Extracts the service account email from the impersonation URL
+        #
+        # @return [String, nil] The service account email extracted from the
+        #   service_account_impersonation_url, or nil if it cannot be determined
         def service_account_email
           return nil if @service_account_impersonation_url.nil?
           start_idx = @service_account_impersonation_url.rindex "/"

data/lib/googleauth/external_account/identity_pool_credentials.rb

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 require "time"
+require "json"
+require "googleauth/errors"
 require "googleauth/external_account/base_credentials"
 require "googleauth/external_account/external_account_utils"
 
@@ -32,10 +34,12 @@ module Google
 
         # Initialize from options map.
         #
-        # @param [string] audience
-        # @param [hash{symbol => value}] credential_source
-        #     credential_source is a hash that contains either source file or url.
-        #     credential_source_format is either text or json. To define how we parse the credential response.
+        # @param [Hash] options Configuration options
+        # @option options [String] :audience The audience for the token
+        # @option options [Hash{Symbol => Object}] :credential_source A hash containing either source file or url.
+        #     credential_source_format is either text or json to define how to parse the credential response.
+        # @raise [Google::Auth::InitializationError] If credential_source format is invalid, field_name is missing,
+        #     contains ambiguous sources, or is missing required fields
         #
         def initialize options = {}
           base_setup options
@@ -51,65 +55,87 @@ module Google
         end
 
         # Implementation of BaseCredentials retrieve_subject_token!
+        #
+        # @return [String] The subject token
+        # @raise [Google::Auth::CredentialsError] If the token can't be parsed from JSON or is missing
         def retrieve_subject_token!
           content, resource_name = token_data
           if @credential_source_format_type == "text"
             token = content
           else
             begin
-              response_data = MultiJson.load content, symbolize_keys: true
+              response_data = JSON.parse content, symbolize_names: true
               token = response_data[@credential_source_field_name.to_sym]
             rescue StandardError
-              raise "Unable to parse subject_token from JSON resource #{resource_name} " \
-                    "using key #{@credential_source_field_name}"
+              raise CredentialsError, "Unable to parse subject_token from JSON resource #{resource_name} " \
+                                      "using key #{@credential_source_field_name}"
             end
           end
-          raise "Missing subject_token in the credential_source file/response." unless token
+          raise CredentialsError, "Missing subject_token in the credential_source file/response." unless token
           token
         end
 
         private
 
+        # Validates input
+        #
+        # @raise [Google::Auth::InitializationError] If credential_source format is invalid, field_name is missing,
+        #     contains ambiguous sources, or is missing required fields
         def validate_credential_source
           # `environment_id` is only supported in AWS or dedicated future external account credentials.
           unless @credential_source[:environment_id].nil?
-            raise "Invalid Identity Pool credential_source field 'environment_id'"
+            raise InitializationError, "Invalid Identity Pool credential_source field 'environment_id'"
           end
           unless ["json", "text"].include? @credential_source_format_type
-            raise "Invalid credential_source format #{@credential_source_format_type}"
+            raise InitializationError, "Invalid credential_source format #{@credential_source_format_type}"
           end
           # for JSON types, get the required subject_token field name.
           @credential_source_field_name = @credential_source_format[:subject_token_field_name]
           if @credential_source_format_type == "json" && @credential_source_field_name.nil?
-            raise "Missing subject_token_field_name for JSON credential_source format"
+            raise InitializationError, "Missing subject_token_field_name for JSON credential_source format"
           end
           # check file or url must be fulfilled and mutually exclusiveness.
           if @credential_source_file && @credential_source_url
-            raise "Ambiguous credential_source. 'file' is mutually exclusive with 'url'."
+            raise InitializationError, "Ambiguous credential_source. 'file' is mutually exclusive with 'url'."
           end
           return unless (@credential_source_file || @credential_source_url).nil?
-          raise "Missing credential_source. A 'file' or 'url' must be provided."
+          raise InitializationError, "Missing credential_source. A 'file' or 'url' must be provided."
         end
 
         def token_data
           @credential_source_file.nil? ? url_data : file_data
         end
 
+        # Reads data from a file source
+        #
+        # @return [Array(String, String)] The file content and file path
+        # @raise [Google::Auth::CredentialsError] If the source file doesn't exist
         def file_data
-          raise "File #{@credential_source_file} was not found." unless File.exist? @credential_source_file
+          unless File.exist? @credential_source_file
+            raise CredentialsError,
+                  "File #{@credential_source_file} was not found."
+          end
           content = File.read @credential_source_file, encoding: "utf-8"
           [content, @credential_source_file]
         end
 
+        # Fetches data from a URL source
+        #
+        # @return [Array(String, String)] The response body and URL
+        # @raise [Google::Auth::CredentialsError] If there's an error retrieving data from the URL
+        #   or if the response is not successful
         def url_data
           begin
             response = connection.get @credential_source_url do |req|
               req.headers.merge! @credential_source_headers
             end
           rescue Faraday::Error => e
-            raise "Error retrieving from credential url: #{e}"
+            raise CredentialsError, "Error retrieving from credential url: #{e}"
+          end
+          unless response.success?
+            raise CredentialsError,
+                  "Unable to retrieve Identity Pool subject token #{response.body}"
           end
-          raise "Unable to retrieve Identity Pool subject token #{response.body}" unless response.success?
           [response.body, @credential_source_url]
         end
       end

data/lib/googleauth/external_account/pluggable_credentials.rb

@@ -14,6 +14,8 @@
 
 require "open3"
 require "time"
+require "json"
+require "googleauth/errors"
 require "googleauth/external_account/base_credentials"
 require "googleauth/external_account/external_account_utils"
 
@@ -41,34 +43,43 @@ module Google
 
         # Initialize from options map.
         #
-        # @param [string] audience
-        # @param [hash{symbol => value}] credential_source
-        #     credential_source is a hash that contains either source file or url.
-        #     credential_source_format is either text or json. To define how we parse the credential response.
-        #
+        # @param [Hash] options Configuration options
+        # @option options [String] :audience Audience for the token
+        # @option options [Hash] :credential_source Credential source configuration that contains executable
+        #   configuration
+        # @raise [Google::Auth::InitializationError] If executable source, command is missing, or timeout is invalid
         def initialize options = {}
           base_setup options
 
           @audience = options[:audience]
           @credential_source = options[:credential_source] || {}
           @credential_source_executable = @credential_source[:executable]
-          raise "Missing excutable source. An 'executable' must be provided" if @credential_source_executable.nil?
+          if @credential_source_executable.nil?
+            raise InitializationError,
+                  "Missing excutable source. An 'executable' must be provided"
+          end
           @credential_source_executable_command = @credential_source_executable[:command]
           if @credential_source_executable_command.nil?
-            raise "Missing command field. Executable command must be provided."
+            raise InitializationError, "Missing command field. Executable command must be provided."
           end
           @credential_source_executable_timeout_millis = @credential_source_executable[:timeout_millis] ||
                                                          EXECUTABLE_TIMEOUT_MILLIS_DEFAULT
           if @credential_source_executable_timeout_millis < EXECUTABLE_TIMEOUT_MILLIS_LOWER_BOUND ||
              @credential_source_executable_timeout_millis > EXECUTABLE_TIMEOUT_MILLIS_UPPER_BOUND
-            raise "Timeout must be between 5 and 120 seconds."
+            raise InitializationError, "Timeout must be between 5 and 120 seconds."
           end
           @credential_source_executable_output_file = @credential_source_executable[:output_file]
         end
 
+        # Retrieves the subject token using the credential_source object.
+        #
+        # @return [String] The retrieved subject token
+        # @raise [Google::Auth::CredentialsError] If executables are not allowed, if token retrieval fails,
+        #   or if the token is invalid
         def retrieve_subject_token!
           unless ENV[ENABLE_PLUGGABLE_ENV] == "1"
-            raise "Executables need to be explicitly allowed (set GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES to '1') " \
+            raise CredentialsError,
+                  "Executables need to be explicitly allowed (set GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES to '1') " \
                   "to run."
           end
           # check output file first
@@ -78,7 +89,7 @@ module Google
           env = inject_environment_variables
           output = subprocess_with_timeout env, @credential_source_executable_command,
                                            @credential_source_executable_timeout_millis
-          response = MultiJson.load output, symbolize_keys: true
+          response = JSON.parse output, symbolize_names: true
           parse_subject_token response
         end
 
@@ -89,7 +100,7 @@ module Google
           return nil unless File.exist? @credential_source_executable_output_file
           begin
             content = File.read @credential_source_executable_output_file, encoding: "utf-8"
-            response = MultiJson.load content, symbolize_keys: true
+            response = JSON.parse content, symbolize_names: true
           rescue StandardError
             return nil
           end
@@ -97,7 +108,7 @@ module Google
             subject_token = parse_subject_token response
           rescue StandardError => e
             return nil if e.message.match(/The token returned by the executable is expired/)
-            raise e
+            raise CredentialsError, e.message
           end
           subject_token
         end
@@ -106,25 +117,29 @@ module Google
           validate_response_schema response
           unless response[:success]
             if response[:code].nil? || response[:message].nil?
-              raise "Error code and message fields are required in the response."
+              raise CredentialsError, "Error code and message fields are required in the response."
             end
-            raise "Executable returned unsuccessful response: code: #{response[:code]}, message: #{response[:message]}."
+            raise CredentialsError,
+                  "Executable returned unsuccessful response: code: #{response[:code]}, message: #{response[:message]}."
           end
           if response[:expiration_time] && response[:expiration_time] < Time.now.to_i
-            raise "The token returned by the executable is expired."
+            raise CredentialsError, "The token returned by the executable is expired."
+          end
+          if response[:token_type].nil?
+            raise CredentialsError,
+                  "The executable response is missing the token_type field."
           end
-          raise "The executable response is missing the token_type field." if response[:token_type].nil?
           return response[:id_token] if ID_TOKEN_TYPE.include? response[:token_type]
           return response[:saml_response] if response[:token_type] == "urn:ietf:params:oauth:token-type:saml2"
-          raise "Executable returned unsupported token type."
+          raise CredentialsError, "Executable returned unsupported token type."
         end
 
         def validate_response_schema response
-          raise "The executable response is missing the version field." if response[:version].nil?
+          raise CredentialsError, "The executable response is missing the version field." if response[:version].nil?
           if response[:version] > EXECUTABLE_SUPPORTED_MAX_VERSION
-            raise "Executable returned unsupported version #{response[:version]}."
+            raise CredentialsError, "Executable returned unsupported version #{response[:version]}."
           end
-          raise "The executable response is missing the success field." if response[:success].nil?
+          raise CredentialsError, "The executable response is missing the success field." if response[:success].nil?
         end
 
         def inject_environment_variables
@@ -145,7 +160,8 @@ module Google
           Timeout.timeout timeout_seconds do
             output, error, status = Open3.capture3 environment_vars, command
             unless status.success?
-              raise "Executable exited with non-zero return code #{status.exitstatus}. Error: #{output}, #{error}"
+              raise CredentialsError,
+                    "Executable exited with non-zero return code #{status.exitstatus}. Error: #{output}, #{error}"
             end
             output
           end