googleauth 1.3.0 → 1.8.1

data/lib/googleauth/external_account/identity_pool_credentials.rb

@@ -0,0 +1,118 @@
+# Copyright 2023 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 "time"
+require "googleauth/external_account/base_credentials"
+require "googleauth/external_account/external_account_utils"
+
+module Google
+  # Module Auth provides classes that provide Google-specific authorization used to access Google APIs.
+  module Auth
+    module ExternalAccount
+      # This module handles the retrieval of credentials from Google Cloud by utilizing the any 3PI
+      # provider then exchanging the credentials for a short-lived Google Cloud access token.
+      class IdentityPoolCredentials
+        include Google::Auth::ExternalAccount::BaseCredentials
+        include Google::Auth::ExternalAccount::ExternalAccountUtils
+        extend CredentialsLoader
+
+        # Will always be nil, but method still gets used.
+        attr_reader :client_id
+
+        # 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.
+        #
+        def initialize options = {}
+          base_setup options
+
+          @audience = options[:audience]
+          @credential_source = options[:credential_source] || {}
+          @credential_source_file = @credential_source[:file]
+          @credential_source_url = @credential_source[:url]
+          @credential_source_headers = @credential_source[:headers] || {}
+          @credential_source_format = @credential_source[:format] || {}
+          @credential_source_format_type = @credential_source_format[:type] || "text"
+          validate_credential_source
+        end
+
+        # Implementation of BaseCredentials retrieve_subject_token!
+        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
+              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}"
+            end
+          end
+          raise "Missing subject_token in the credential_source file/response." unless token
+          token
+        end
+
+        private
+
+        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'"
+          end
+          unless ["json", "text"].include? @credential_source_format_type
+            raise "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"
+          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'."
+          end
+          return unless (@credential_source_file || @credential_source_url).nil?
+          raise "Missing credential_source. A 'file' or 'url' must be provided."
+        end
+
+        def token_data
+          @credential_source_file.nil? ? url_data : file_data
+        end
+
+        def file_data
+          raise "File #{@credential_source_file} was not found." unless File.exist? @credential_source_file
+          content = File.read @credential_source_file, encoding: "utf-8"
+          [content, @credential_source_file]
+        end
+
+        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}"
+          end
+          raise "Unable to retrieve Identity Pool subject token #{response.body}" unless response.success?
+          [response.body, @credential_source_url]
+        end
+      end
+    end
+  end
+end

data/lib/googleauth/external_account/pluggable_credentials.rb

@@ -0,0 +1,156 @@
+# Copyright 2023 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 "open3"
+require "time"
+require "googleauth/external_account/base_credentials"
+require "googleauth/external_account/external_account_utils"
+
+module Google
+  # Module Auth provides classes that provide Google-specific authorization used to access Google APIs.
+  module Auth
+    module ExternalAccount
+      # This module handles the retrieval of credentials from Google Cloud by utilizing the any 3PI
+      # provider then exchanging the credentials for a short-lived Google Cloud access token.
+      class PluggableAuthCredentials
+        # constant for pluggable auth enablement in environment variable.
+        ENABLE_PLUGGABLE_ENV = "GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES".freeze
+        EXECUTABLE_SUPPORTED_MAX_VERSION = 1
+        EXECUTABLE_TIMEOUT_MILLIS_DEFAULT = 30 * 1000
+        EXECUTABLE_TIMEOUT_MILLIS_LOWER_BOUND = 5 * 1000
+        EXECUTABLE_TIMEOUT_MILLIS_UPPER_BOUND = 120 * 1000
+        ID_TOKEN_TYPE = ["urn:ietf:params:oauth:token-type:jwt", "urn:ietf:params:oauth:token-type:id_token"].freeze
+
+        include Google::Auth::ExternalAccount::BaseCredentials
+        include Google::Auth::ExternalAccount::ExternalAccountUtils
+        extend CredentialsLoader
+
+        # Will always be nil, but method still gets used.
+        attr_reader :client_id
+
+        # 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.
+        #
+        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?
+          @credential_source_executable_command = @credential_source_executable[:command]
+          if @credential_source_executable_command.nil?
+            raise "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."
+          end
+          @credential_source_executable_output_file = @credential_source_executable[:output_file]
+        end
+
+        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') " \
+                  "to run."
+          end
+          # check output file first
+          subject_token = load_subject_token_from_output_file
+          return subject_token unless subject_token.nil?
+          # environment variable injection
+          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
+          parse_subject_token response
+        end
+
+        private
+
+        def load_subject_token_from_output_file
+          return nil if @credential_source_executable_output_file.nil?
+          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
+          rescue StandardError
+            return nil
+          end
+          begin
+            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
+          end
+          subject_token
+        end
+
+        def parse_subject_token response
+          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."
+            end
+            raise "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."
+          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."
+        end
+
+        def validate_response_schema response
+          raise "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]}."
+          end
+          raise "The executable response is missing the success field." if response[:success].nil?
+        end
+
+        def inject_environment_variables
+          env = ENV.to_h
+          env["GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE"] = @audience
+          env["GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE"] = @subject_token_type
+          env["GOOGLE_EXTERNAL_ACCOUNT_INTERACTIVE"] = "0" # only non-interactive mode we support.
+          unless @service_account_impersonation_url.nil?
+            env["GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL"] = service_account_email
+          end
+          unless @credential_source_executable_output_file.nil?
+            env["GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE"] = @credential_source_executable_output_file
+          end
+          env
+        end
+
+        def subprocess_with_timeout environment_vars, command, timeout_seconds
+          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}"
+            end
+            output
+          end
+        end
+      end
+    end
+  end
+end

data/lib/googleauth/external_account.rb

@@ -0,0 +1,93 @@
+# Copyright 2022 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 "time"
+require "uri"
+require "googleauth/credentials_loader"
+require "googleauth/external_account/aws_credentials"
+require "googleauth/external_account/identity_pool_credentials"
+require "googleauth/external_account/pluggable_credentials"
+
+module Google
+  # Module Auth provides classes that provide Google-specific authorization
+  # used to access Google APIs.
+  module Auth
+    # Authenticates requests using External Account credentials, such
+    # as those provided by the AWS provider.
+    module ExternalAccount
+      # Provides an entrypoint for all Exernal Account credential classes.
+      class Credentials
+        # The subject token type used for AWS external_account credentials.
+        AWS_SUBJECT_TOKEN_TYPE = "urn:ietf:params:aws:token-type:aws4_request".freeze
+        MISSING_CREDENTIAL_SOURCE = "missing credential source for external account".freeze
+        INVALID_EXTERNAL_ACCOUNT_TYPE = "credential source is not supported external account type".freeze
+
+        # Create a ExternalAccount::Credentials
+        #
+        # @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
+
+          raise "A json file is required for external account credentials." unless json_key_io
+          user_creds = read_json_key json_key_io
+
+          # AWS credentials is determined by aws subject token type
+          return make_aws_credentials user_creds, scope if user_creds[:subject_token_type] == AWS_SUBJECT_TOKEN_TYPE
+
+          raise MISSING_CREDENTIAL_SOURCE if user_creds[:credential_source].nil?
+          user_creds[:scope] = scope
+          make_external_account_credentials user_creds
+        end
+
+        # Reads the required fields from the JSON.
+        def self.read_json_key json_key_io
+          json_key = MultiJson.load json_key_io.read, symbolize_keys: true
+          wanted = [
+            :audience, :subject_token_type, :token_url, :credential_source
+          ]
+          wanted.each do |key|
+            raise "the json is missing the #{key} field" unless json_key.key? key
+          end
+          json_key
+        end
+
+        class << self
+          private
+
+          def make_aws_credentials user_creds, scope
+            Google::Auth::ExternalAccount::AwsCredentials.new(
+              audience: user_creds[:audience],
+              scope: scope,
+              subject_token_type: user_creds[:subject_token_type],
+              token_url: user_creds[:token_url],
+              credential_source: user_creds[:credential_source],
+              service_account_impersonation_url: user_creds[:service_account_impersonation_url]
+            )
+          end
+
+          def make_external_account_credentials user_creds
+            unless user_creds[:credential_source][:file].nil? && user_creds[:credential_source][:url].nil?
+              return Google::Auth::ExternalAccount::IdentityPoolCredentials.new user_creds
+            end
+            unless user_creds[:credential_source][:executable].nil?
+              return Google::Auth::ExternalAccount::PluggableAuthCredentials.new user_creds
+            end
+            raise INVALID_EXTERNAL_ACCOUNT_TYPE
+          end
+        end
+      end
+    end
+  end
+end

data/lib/googleauth/helpers/connection.rb

@@ -0,0 +1,35 @@
+# Copyright 2023 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 "faraday"
+
+module Google
+  # Module Auth provides classes that provide Google-specific authorization
+  # used to access Google APIs.
+  module Auth
+    # Helpers provides utility methods for Google::Auth.
+    module Helpers
+      # Connection provides a Faraday connection for use with Google::Auth.
+      module Connection
+        module_function
+
+        attr_accessor :default_connection
+
+        def connection
+          @default_connection || Faraday.default_connection
+        end
+      end
+    end
+  end
+end

data/lib/googleauth/id_tokens.rb

@@ -153,7 +153,7 @@ module Google
         #     one of the provided values, or the verification will fail with
         #     {Google::Auth::IDToken::AuthorizedPartyMismatchError}. If `nil`
         #     (the default), no azp checking is performed.
-        # @param aud [String,Array<String>,nil] The expected audience. At least
+        # @param iss [String,Array<String>,nil] The expected issuer. At least
         #     one `iss` field in the token must match at least one of the
         #     provided issuers, or the verification will fail with
         #     {Google::Auth::IDToken::IssuerMismatchError}. If `nil`, no issuer
@@ -191,7 +191,7 @@ module Google
         #     one of the provided values, or the verification will fail with
         #     {Google::Auth::IDToken::AuthorizedPartyMismatchError}. If `nil`
         #     (the default), no azp checking is performed.
-        # @param aud [String,Array<String>,nil] The expected audience. At least
+        # @param iss [String,Array<String>,nil] The expected issuer. At least
         #     one `iss` field in the token must match at least one of the
         #     provided issuers, or the verification will fail with
         #     {Google::Auth::IDToken::IssuerMismatchError}. If `nil`, no issuer

data/lib/googleauth/oauth2/sts_client.rb

@@ -0,0 +1,109 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "googleauth/helpers/connection"
+
+module Google
+  module Auth
+    module OAuth2
+      # OAuth 2.0 Token Exchange Spec.
+      # This module defines a token exchange utility based on the
+      # [OAuth 2.0 Token Exchange](https://tools.ietf.org/html/rfc8693) spec. This will be mainly
+      # used to exchange external credentials for GCP access tokens in workload identity pools to
+      # access Google APIs.
+      # The implementation will support various types of client authentication as allowed in the spec.
+      #
+      # A deviation on the spec will be for additional Google specific options that cannot be easily
+      # mapped to parameters defined in the RFC.
+      # The returned dictionary response will be based on the [rfc8693 section 2.2.1]
+      # (https://tools.ietf.org/html/rfc8693#section-2.2.1) spec JSON response.
+      #
+      class STSClient
+        include Helpers::Connection
+
+        URLENCODED_HEADERS = { "Content-Type": "application/x-www-form-urlencoded" }.freeze
+
+        # Create a new instance of the STSClient.
+        #
+        # @param [String] token_exchange_endpoint
+        #  The token exchange endpoint.
+        def initialize options = {}
+          raise "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
+
+        # Exchanges the provided token for another type of token based on the
+        # rfc8693 spec
+        #
+        # @param [Faraday instance] connection
+        # A callable faraday instance used to make HTTP requests.
+        # @param [String] grant_type
+        #   The OAuth 2.0 token exchange grant type.
+        # @param [String] subject_token
+        #   The OAuth 2.0 token exchange subject token.
+        # @param [String] subject_token_type
+        #   The OAuth 2.0 token exchange subject token type.
+        # @param [String] resource
+        #   The optional OAuth 2.0 token exchange resource field.
+        # @param [String] audience
+        #   The optional OAuth 2.0 token exchange audience field.
+        # @param [Array<String>] scopes
+        #   The optional list of scopes to use.
+        # @param [String] requested_token_type
+        #   The optional OAuth 2.0 token exchange requested token type.
+        # @param additional_headers (Hash<String,String>):
+        #   The optional additional headers to pass to the token exchange endpoint.
+        #
+        # @return [Hash] A hash containing the token exchange response.
+        def exchange_token options = {}
+          missing_required_opts = [:grant_type, :subject_token, :subject_token_type] - options.keys
+          unless missing_required_opts.empty?
+            raise ArgumentError, "Missing required options: #{missing_required_opts.join ', '}"
+          end
+
+          # TODO: Add the ability to add authentication to the headers
+          headers = URLENCODED_HEADERS.dup.merge(options[:additional_headers] || {})
+
+          request_body = make_request options
+
+          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}"
+          end
+
+          MultiJson.load response.body
+        end
+
+        private
+
+        def make_request options = {}
+          request_body = {
+            grant_type: options[:grant_type],
+            audience: options[:audience],
+            scope: Array(options[:scopes])&.join(" ") || [],
+            requested_token_type: options[:requested_token_type],
+            subject_token: options[:subject_token],
+            subject_token_type: options[:subject_token_type]
+          }
+          unless options[:additional_options].nil?
+            request_body[:options] = CGI.escape MultiJson.dump(options[:additional_options], symbolize_name: true)
+          end
+          request_body
+        end
+      end
+    end
+  end
+end

data/lib/googleauth/scope_util.rb

@@ -18,27 +18,60 @@ require "multi_json"
 
 module Google
   module Auth
-    # Small utility for normalizing scopes into canonical form
+    ##
+    # Small utility for normalizing scopes into canonical form.
+    #
+    # The canonical form of scopes is as an array of strings, each in the form
+    # of a full URL. This utility converts space-delimited scope strings into
+    # this form, and handles a small number of common aliases.
+    #
+    # This is used by UserRefreshCredentials to verify that a credential grants
+    # a requested scope.
+    #
     module ScopeUtil
+      ##
+      # Aliases understood by this utility
+      #
       ALIASES = {
         "email"   => "https://www.googleapis.com/auth/userinfo.email",
         "profile" => "https://www.googleapis.com/auth/userinfo.profile",
         "openid"  => "https://www.googleapis.com/auth/plus.me"
       }.freeze
 
+      ##
+      # Normalize the input, which may be an array of scopes or a whitespace-
+      # delimited scope string. The output is always an array, even if a single
+      # scope is input.
+      #
+      # @param scope [String,Array<String>] Input scope(s)
+      # @return [Array<String>] An array of scopes in canonical form.
+      #
       def self.normalize scope
         list = as_array scope
         list.map { |item| ALIASES[item] || item }
       end
 
+      ##
+      # Ensure the input is an array. If a single string is passed in, splits
+      # it via whitespace. Does not interpret aliases.
+      #
+      # @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
+      #
       def self.as_array scope
         case scope
         when Array
+          scope.each do |item|
+            unless item.is_a? String
+              raise ArgumentError, "Invalid scope value: #{item.inspect}. Must be string or array"
+            end
+          end
           scope
         when String
           scope.split
         else
-          raise "Invalid scope value. Must be string or array"
+          raise ArgumentError, "Invalid scope value: #{scope.inspect}. Must be string or array"
         end
       end
     end

data/lib/googleauth/service_account.rb

@@ -130,7 +130,7 @@ module Google
     # cf [Application Default Credentials](https://cloud.google.com/docs/authentication/production)
     class ServiceAccountJwtHeaderCredentials
       JWT_AUD_URI_KEY = :jwt_aud_uri
-      AUTH_METADATA_KEY = Signet::OAuth2::AUTH_METADATA_KEY
+      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
@@ -192,8 +192,6 @@ module Google
         proc { |a_hash, opts = {}| apply a_hash, opts }
       end
 
-      protected
-
       # Creates a jwt uri token.
       def new_jwt_token jwt_aud_uri = nil, options = {}
         now = Time.new