googleauth 0.17.1 → 1.7.0

data/lib/googleauth/external_account/base_credentials.rb

@@ -0,0 +1,158 @@
+# 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/base_client"
+require "googleauth/helpers/connection"
+require "googleauth/oauth2/sts_client"
+
+module Google
+  # Module Auth provides classes that provide Google-specific authorization
+  # used to access Google APIs.
+  module Auth
+    module ExternalAccount
+      # Authenticates requests using External Account credentials, such
+      # as those provided by the AWS provider or OIDC provider like Azure, etc.
+      module BaseCredentials
+        # Contains all methods needed for all external account credentials.
+        # Other credentials should call `base_setup` during initialization
+        # And should define the :retrieve_subject_token! method
+
+        # External account JSON type identifier.
+        EXTERNAL_ACCOUNT_JSON_TYPE = "external_account".freeze
+        # The token exchange grant_type used for exchanging credentials.
+        STS_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange".freeze
+        # The token exchange requested_token_type. This is always an access_token.
+        STS_REQUESTED_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token".freeze
+        # Default IAM_SCOPE
+        IAM_SCOPE = ["https://www.googleapis.com/auth/iam".freeze].freeze
+
+        include Google::Auth::BaseClient
+        include Helpers::Connection
+
+        attr_reader :expires_at
+        attr_accessor :access_token
+
+        def expires_within? seconds
+          # This method is needed for BaseClient
+          @expires_at && @expires_at - Time.now.utc < seconds
+        end
+
+        def expires_at= new_expires_at
+          @expires_at = normalize_timestamp new_expires_at
+        end
+
+        def fetch_access_token! _options = {}
+          # This method is needed for BaseClient
+          response = exchange_token
+
+          if @service_account_impersonation_url
+            impersonated_response = get_impersonated_access_token response["access_token"]
+            self.expires_at = impersonated_response["expireTime"]
+            self.access_token = impersonated_response["accessToken"]
+          else
+            # Extract the expiration time in seconds from the response and calculate the actual expiration time
+            # and then save that to the expiry variable.
+            self.expires_at = Time.now.utc + response["expires_in"].to_i
+            self.access_token = response["access_token"]
+          end
+
+          notify_refresh_listeners
+        end
+
+        # Retrieves the subject token using the credential_source object.
+        # @return [string]
+        #     The retrieved subject token.
+        #
+        def retrieve_subject_token!
+          raise NotImplementedError
+        end
+
+        # Returns whether the credentials represent a workforce pool (True) or
+        # workload (False) based on the credentials' audience.
+        #
+        # @return [bool]
+        #     true if the credentials represent a workforce pool.
+        #     false if they represent a workload.
+        def is_workforce_pool?
+          pattern = "//iam\.googleapis\.com/locations/[^/]+/workforcePools/"
+          /#{pattern}/.match?(@audience || "")
+        end
+
+        private
+
+        def token_type
+          # This method is needed for BaseClient
+          :access_token
+        end
+
+        def base_setup options
+          self.default_connection = options[:connection]
+
+          @audience = options[:audience]
+          @scope = options[:scope] || IAM_SCOPE
+          @subject_token_type = options[:subject_token_type]
+          @token_url = options[:token_url]
+          @token_info_url = options[:token_info_url]
+          @service_account_impersonation_url = options[:service_account_impersonation_url]
+          @service_account_impersonation_options = options[:service_account_impersonation_options] || {}
+          @client_id = options[:client_id]
+          @client_secret = options[:client_secret]
+          @quota_project_id = options[:quota_project_id]
+          @project_id = nil
+          @workforce_pool_user_project = options[:workforce_pool_user_project]
+
+          @expires_at = nil
+          @access_token = nil
+
+          @sts_client = Google::Auth::OAuth2::STSClient.new(
+            token_exchange_endpoint: @token_url,
+            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."
+        end
+
+        def exchange_token
+          additional_options = nil
+          if @client_id.nil? && @workforce_pool_user_project
+            additional_options = { userProject: @workforce_pool_user_project }
+          end
+          @sts_client.exchange_token(
+            audience: @audience,
+            grant_type: STS_GRANT_TYPE,
+            subject_token: retrieve_subject_token!,
+            subject_token_type: @subject_token_type,
+            scopes: @service_account_impersonation_url ? IAM_SCOPE : @scope,
+            requested_token_type: STS_REQUESTED_TOKEN_TYPE,
+            additional_options: additional_options
+          )
+        end
+
+        def get_impersonated_access_token token, _options = {}
+          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 })
+          end
+
+          if response.status != 200
+            raise "Service account impersonation failed with status #{response.status}"
+          end
+
+          MultiJson.load response.body
+        end
+      end
+    end
+  end
+end

data/lib/googleauth/external_account/external_account_utils.rb

@@ -0,0 +1,103 @@
+# 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/base_client"
+require "googleauth/helpers/connection"
+require "googleauth/oauth2/sts_client"
+
+module Google
+  # Module Auth provides classes that provide Google-specific authorization
+  # used to access Google APIs.
+  module Auth
+    module ExternalAccount
+      # Authenticates requests using External Account credentials, such
+      # as those provided by the AWS provider or OIDC provider like Azure, etc.
+      module ExternalAccountUtils
+        # Cloud resource manager URL used to retrieve project information.
+        CLOUD_RESOURCE_MANAGER = "https://cloudresourcemanager.googleapis.com/v1/projects/".freeze
+
+        ##
+        # Retrieves the project ID corresponding to the workload identity or workforce pool.
+        # For workforce pool credentials, it returns the project ID corresponding to the workforce_pool_user_project.
+        # When not determinable, None is returned.
+        #
+        # The resource may not have permission (resourcemanager.projects.get) to
+        # 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.
+        #
+        def project_id
+          return @project_id unless @project_id.nil?
+          project_number = self.project_number || @workforce_pool_user_project
+
+          # if we missing either project number or scope, we won't retrieve project_id
+          return nil if project_number.nil? || @scope.nil?
+
+          url = "#{CLOUD_RESOURCE_MANAGER}#{project_number}"
+          response = connection.get url do |req|
+            req.headers["Authorization"] = "Bearer #{@access_token}"
+            req.headers["Content-Type"] = "application/json"
+          end
+
+          if response.status == 200
+            response_data = MultiJson.load response.body, symbolize_names: true
+            @project_id = response_data[:projectId]
+          end
+
+          @project_id
+        end
+
+        ##
+        # Retrieve the project number corresponding to workload identity pool
+        # STS audience pattern:
+        #     `//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/...`
+        #
+        # @return [string, nil]
+        #
+        def project_number
+          segments = @audience.split "/"
+          idx = segments.index "projects"
+          return nil if idx.nil? || idx + 1 == segments.size
+          segments[idx + 1]
+        end
+
+        def normalize_timestamp time
+          case time
+          when NilClass
+            nil
+          when Time
+            time
+          when String
+            Time.parse time
+          else
+            raise "Invalid time value #{time}"
+          end
+        end
+
+        def service_account_email
+          return nil if @service_account_impersonation_url.nil?
+          start_idx = @service_account_impersonation_url.rindex "/"
+          end_idx = @service_account_impersonation_url.index ":generateAccessToken"
+          if start_idx != -1 && end_idx != -1 && start_idx < end_idx
+            start_idx += 1
+            return @service_account_impersonation_url[start_idx..end_idx]
+          end
+          nil
+        end
+      end
+    end
+  end
+end

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