googleauth 0.8.1 → 0.16.0

data/Gemfile

@@ -8,18 +8,18 @@ group :development do
   gem "coveralls", "~> 0.7"
   gem "fakefs", "~> 0.6"
   gem "fakeredis", "~> 0.5"
-  gem "google-style", "~> 0.2"
+  gem "google-style", "~> 1.25.1"
   gem "logging", "~> 2.0"
+  gem "minitest", "~> 5.14"
+  gem "minitest-focus", "~> 1.1"
   gem "rack-test", "~> 0.6"
-  gem "rake", "~> 10.0"
+  gem "rake", "~> 13.0"
   gem "redis", "~> 3.2"
   gem "rspec", "~> 3.0"
   gem "simplecov", "~> 0.9"
   gem "sinatra"
-  gem "webmock", "~> 1.21"
+  gem "webmock", "~> 3.8"
 end
 
-platforms :jruby do
-  group :development do
-  end
-end
+gem "faraday", ">= 0.17.3", "< 2.0"
+gem "gems", "~> 1.2"

data/README.md

@@ -1,15 +1,13 @@
 # Google Auth Library for Ruby
 
 <dl>
-  <dt>Homepage</dt><dd><a href="http://www.github.com/google/google-auth-library-ruby">http://www.github.com/google/google-auth-library-ruby</a></dd>
+  <dt>Homepage</dt><dd><a href="http://www.github.com/googleapis/google-auth-library-ruby">http://www.github.com/googleapis/google-auth-library-ruby</a></dd>
   <dt>Authors</dt><dd><a href="mailto:temiola@google.com">Tim Emiola</a></dd>
   <dt>Copyright</dt><dd>Copyright © 2015 Google, Inc.</dd>
   <dt>License</dt><dd>Apache 2.0</dd>
 </dl>
 
 [![Gem Version](https://badge.fury.io/rb/googleauth.svg)](http://badge.fury.io/rb/googleauth)
-[![Build Status](https://secure.travis-ci.org/google/google-auth-library-ruby.svg)](http://travis-ci.org/google/google-auth-library-ruby)
-[![Coverage Status](https://coveralls.io/repos/google/google-auth-library-ruby/badge.svg)](https://coveralls.io/r/google/google-auth-library-ruby)
 
 ## Description
 
@@ -180,18 +178,18 @@ access and refresh tokens. Two storage implementations are included:
 *   Google::Auth::Stores::RedisTokenStore
 
 Custom storage implementations can also be used. See
-[token_store.rb](lib/googleauth/token_store.rb) for additional details.
+[token_store.rb](https://googleapis.dev/ruby/googleauth/latest/Google/Auth/TokenStore.html) for additional details.
 
 ## Supported Ruby Versions
 
-This library is currently supported on Ruby 1.9+.
+This library is supported on Ruby 2.5+.
 
-However, Ruby 2.4 or later is strongly recommended, as earlier releases have
-reached or are nearing end-of-life. After March 31, 2019, Google will provide
-official support only for Ruby versions that are considered current and
-supported by Ruby Core (that is, Ruby versions that are either in normal
-maintenance or in security maintenance).
-See https://www.ruby-lang.org/en/downloads/branches/ for further details.
+Google provides official support for Ruby versions that are actively supported
+by Ruby Core—that is, Ruby versions that are either in normal maintenance or in
+security maintenance, and not end of life. Currently, this means Ruby 2.5 and
+later. Older versions of Ruby _may_ still work, but are unsupported and not
+recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
+about the Ruby support schedule.
 
 ## License
 
@@ -210,7 +208,6 @@ hesitate to
 [ask questions](http://stackoverflow.com/questions/tagged/google-auth-library-ruby)
 about the client or APIs on [StackOverflow](http://stackoverflow.com).
 
-[google-apis-ruby-client]: (https://github.com/google/google-api-ruby-client)
-[application default credentials]: (https://developers.google.com/accounts/docs/application-default-credentials)
-[contributing]: https://github.com/google/google-auth-library-ruby/tree/master/CONTRIBUTING.md
-[copying]: https://github.com/google/google-auth-library-ruby/tree/master/COPYING
+[application default credentials]: https://developers.google.com/accounts/docs/application-default-credentials
+[contributing]: https://github.com/googleapis/google-auth-library-ruby/tree/master/.github/CONTRIBUTING.md
+[copying]: https://github.com/googleapis/google-auth-library-ruby/tree/master/COPYING

data/Rakefile

@@ -1,18 +1,40 @@
 # -*- ruby -*-
+require "json"
 require "bundler/gem_tasks"
 
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+require "rake/testtask"
+
+desc "Run tests."
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+desc "Run integration tests."
+Rake::TestTask.new("integration") do |t|
+  t.libs << "integration"
+  t.test_files = FileList["integration/**/*_test.rb"]
+  t.warning = false
+end
+
 task :ci do
   header "Using Ruby - #{RUBY_VERSION}"
   sh "bundle exec rubocop"
+  Rake::Task["test"].invoke
+  Rake::Task["integration"].invoke
   sh "bundle exec rspec"
 end
 
-task :release, :tag do |_t, args|
+task :release_gem, :tag do |_t, args|
   tag = args[:tag]
   raise "You must provide a tag to release." if tag.nil?
 
   # Verify the tag format "vVERSION"
-  m = tag.match(/v(?<version>\S*)/)
+  m = tag.match /v(?<version>\S*)/
   raise "Tag #{tag} does not match the expected format." if m.nil?
 
   version = m[:version]
@@ -33,17 +55,24 @@ task :release, :tag do |_t, args|
     sh "bundle exec rake build"
   end
 
-  path_to_be_pushed = "pkg/#{version}.gem"
+  path_to_be_pushed = "pkg/googleauth-#{version}.gem"
+  gem_was_published = nil
   if File.file? path_to_be_pushed
     begin
-      ::Gems.push File.new(path_to_be_pushed)
+      response = ::Gems.push File.new(path_to_be_pushed)
+      puts response
+      raise unless response.include? "Successfully registered gem:"
+      gem_was_published = true
       puts "Successfully built and pushed googleauth for version #{version}"
     rescue StandardError => e
+      gem_was_published = false
       puts "Error while releasing googleauth version #{version}: #{e.message}"
     end
   else
     raise "Cannot build googleauth for version #{version}"
   end
+
+  Rake::Task["kokoro:publish_docs"].invoke if gem_was_published
 end
 
 namespace :kokoro do
@@ -63,6 +92,14 @@ namespace :kokoro do
     Rake::Task["ci"].invoke
   end
 
+  task :post do
+    require_relative "rakelib/link_checker.rb"
+
+    link_checker = LinkChecker.new
+    link_checker.run
+    exit link_checker.exit_status
+  end
+
   task :nightly do
     Rake::Task["ci"].invoke
   end
@@ -75,7 +112,13 @@ namespace :kokoro do
                 .first.split("(").last.split(")").first || "0.1.0"
     end
     Rake::Task["kokoro:load_env_vars"].invoke
-    Rake::Task["release"].invoke "v/#{version}"
+    Rake::Task["release_gem"].invoke "v#{version}"
+  end
+
+  task :publish_docs do
+    require_relative "rakelib/devsite_builder.rb"
+
+    DevsiteBuilder.new(__dir__).publish
   end
 end
 

data/googleauth.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |gem|
   gem.version       = Google::Auth::VERSION
   gem.authors       = ["Tim Emiola"]
   gem.email         = "temiola@google.com"
-  gem.homepage      = "https://github.com/google/google-auth-library-ruby"
+  gem.homepage      = "https://github.com/googleapis/google-auth-library-ruby"
   gem.summary       = "Google Auth Library for Ruby"
   gem.license       = "Apache-2.0"
   gem.description   = <<-DESCRIPTION
@@ -24,12 +24,16 @@ Gem::Specification.new do |gem|
     File.basename f
   end
   gem.require_paths = ["lib"]
+
   gem.platform      = Gem::Platform::RUBY
+  gem.required_ruby_version = ">= 2.5"
 
-  gem.add_dependency "faraday", "~> 0.12"
+  gem.add_dependency "faraday", ">= 0.17.3", "< 2.0"
   gem.add_dependency "jwt", ">= 1.4", "< 3.0"
   gem.add_dependency "memoist", "~> 0.16"
   gem.add_dependency "multi_json", "~> 1.11"
   gem.add_dependency "os", ">= 0.9", "< 2.0"
-  gem.add_dependency "signet", "~> 0.7"
+  gem.add_dependency "signet", "~> 0.14"
+
+  gem.add_development_dependency "yard", "~> 0.9"
 end

data/integration/helper.rb

@@ -0,0 +1,31 @@
+# Copyright 2020 Google LLC
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require "minitest/autorun"
+require "minitest/focus"
+require "googleauth"

data/integration/id_tokens/key_source_test.rb

@@ -0,0 +1,74 @@
+# Copyright 2020 Google LLC
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require "helper"
+
+describe Google::Auth::IDTokens do
+  describe "key source" do
+    let(:legacy_oidc_key_source) {
+      Google::Auth::IDTokens::X509CertHttpKeySource.new "https://www.googleapis.com/oauth2/v1/certs"
+    }
+    let(:oidc_key_source) { Google::Auth::IDTokens.oidc_key_source }
+    let(:iap_key_source) { Google::Auth::IDTokens.iap_key_source }
+
+    it "Gets real keys from the OAuth2 V1 cert URL" do
+      keys = legacy_oidc_key_source.refresh_keys
+      refute_empty keys
+      keys.each do |key|
+        assert_kind_of OpenSSL::PKey::RSA, key.key
+        refute key.key.private?
+        assert_equal "RS256", key.algorithm
+      end
+    end
+
+    it "Gets real keys from the OAuth2 V3 cert URL" do
+      keys = oidc_key_source.refresh_keys
+      refute_empty keys
+      keys.each do |key|
+        assert_kind_of OpenSSL::PKey::RSA, key.key
+        refute key.key.private?
+        assert_equal "RS256", key.algorithm
+      end
+    end
+
+    it "Gets the same keys from the OAuth2 V1 and V3 cert URLs" do
+      keys_v1 = legacy_oidc_key_source.refresh_keys.map(&:key).map(&:export).sort
+      keys_v3 = oidc_key_source.refresh_keys.map(&:key).map(&:export).sort
+      assert_equal keys_v1, keys_v3
+    end
+
+    it "Gets real keys from the IAP public key URL" do
+      keys = iap_key_source.refresh_keys
+      refute_empty keys
+      keys.each do |key|
+        assert_kind_of OpenSSL::PKey::EC, key.key
+        assert_equal "ES256", key.algorithm
+      end
+    end
+  end
+end

data/lib/googleauth.rb

@@ -31,5 +31,6 @@ require "googleauth/application_default"
 require "googleauth/client_id"
 require "googleauth/credentials"
 require "googleauth/default_credentials"
+require "googleauth/id_tokens"
 require "googleauth/user_authorizer"
 require "googleauth/web_user_authorizer"

data/lib/googleauth/application_default.rb

@@ -47,7 +47,7 @@ module Google
     #
     # Use this to obtain the Application Default Credentials for accessing
     # Google APIs.  Application Default Credentials are described in detail
-    # at http://goo.gl/IUuyuX.
+    # at https://cloud.google.com/docs/authentication/production.
     #
     # If supplied, scope is used to create the credentials instance, when it can
     # be applied.  E.g, on google compute engine and for user credentials the
@@ -75,7 +75,7 @@ module Google
         GCECredentials.unmemoize_all
         raise NOT_FOUND_ERROR
       end
-      GCECredentials.new
+      GCECredentials.new scope: scope
     end
   end
 end

data/lib/googleauth/compute_engine.rb

@@ -51,30 +51,47 @@ module Google
     class GCECredentials < Signet::OAuth2::Client
       # The IP Address is used in the URIs to speed up failures on non-GCE
       # systems.
-      COMPUTE_AUTH_TOKEN_URI = "http://169.254.169.254/computeMetadata/v1/"\
-      "instance/service-accounts/default/token".freeze
+      DEFAULT_METADATA_HOST = "169.254.169.254".freeze
+
+      # @private Unused and deprecated
+      COMPUTE_AUTH_TOKEN_URI =
+        "http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token".freeze
+      # @private Unused and deprecated
+      COMPUTE_ID_TOKEN_URI =
+        "http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/identity".freeze
+      # @private Unused and deprecated
       COMPUTE_CHECK_URI = "http://169.254.169.254".freeze
 
       class << self
         extend Memoist
 
+        def metadata_host
+          ENV.fetch "GCE_METADATA_HOST", DEFAULT_METADATA_HOST
+        end
+
+        def compute_check_uri
+          "http://#{metadata_host}".freeze
+        end
+
+        def compute_auth_token_uri
+          "#{compute_check_uri}/computeMetadata/v1/instance/service-accounts/default/token".freeze
+        end
+
+        def compute_id_token_uri
+          "#{compute_check_uri}/computeMetadata/v1/instance/service-accounts/default/identity".freeze
+        end
+
         # Detect if this appear to be a GCE instance, by checking if metadata
-        # is available
+        # is available.
         def on_gce? options = {}
+          # TODO: This should use google-cloud-env instead.
           c = options[:connection] || Faraday.default_connection
-          resp = c.get COMPUTE_CHECK_URI do |req|
-            # Comment from: oauth2client/client.py
-            #
-            # Note: the explicit `timeout` below is a workaround. The underlying
-            # issue is that resolving an unknown host on some networks will take
-            # 20-30 seconds; making this timeout short fixes the issue, but
-            # could lead to false negatives in the event that we are on GCE, but
-            # the metadata resolution was particularly slow. The latter case is
-            # "unlikely".
-            req.options.timeout = 0.1
+          headers = { "Metadata-Flavor" => "Google" }
+          resp = c.get compute_check_uri, nil, headers do |req|
+            req.options.timeout = 1.0
+            req.options.open_timeout = 0.1
           end
           return false unless resp.status == 200
-          return false unless resp.headers.key? "Metadata-Flavor"
           resp.headers["Metadata-Flavor"] == "Google"
         rescue Faraday::TimeoutError, Faraday::ConnectionFailed
           false
@@ -88,17 +105,25 @@ module Google
       def fetch_access_token options = {}
         c = options[:connection] || Faraday.default_connection
         retry_with_error do
-          headers = { "Metadata-Flavor" => "Google" }
-          resp = c.get COMPUTE_AUTH_TOKEN_URI, nil, headers
+          uri = target_audience ? GCECredentials.compute_id_token_uri : GCECredentials.compute_auth_token_uri
+          query = target_audience ? { "audience" => target_audience, "format" => "full" } : {}
+          query[:scopes] = Array(scope).join "," if scope
+          resp = c.get uri, query, "Metadata-Flavor" => "Google"
           case resp.status
           when 200
-            Signet::OAuth2.parse_credentials(resp.body,
-                                             resp.headers["content-type"])
+            content_type = resp.headers["content-type"]
+            if content_type == "text/html"
+              { (target_audience ? "id_token" : "access_token") => resp.body }
+            else
+              Signet::OAuth2.parse_credentials resp.body, content_type
+            end
+          when 403, 500
+            msg = "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
+            raise Signet::UnexpectedStatusError, msg
           when 404
             raise Signet::AuthorizationError, NO_METADATA_SERVER_ERROR
           else
-            msg = "Unexpected error code #{resp.status}" \
-              "#{UNEXPECTED_ERROR_SUFFIX}"
+            msg = "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
             raise Signet::AuthorizationError, msg
           end
         end

data/lib/googleauth/credentials.rb

@@ -35,63 +35,382 @@ require "googleauth/credentials_loader"
 
 module Google
   module Auth
-    # This class is intended to be inherited by API-specific classes
-    # which overrides the SCOPE constant.
-    class Credentials
+    ##
+    # Credentials is a high-level base class used by Google's API client
+    # libraries to represent the authentication when connecting to an API.
+    # In most cases, it is subclassed by API-specific credential classes that
+    # can be instantiated by clients.
+    #
+    # ## Options
+    #
+    # Credentials classes are configured with options that dictate default
+    # values for parameters such as scope and audience. These defaults are
+    # expressed as class attributes, and may differ from endpoint to endpoint.
+    # Normally, an API client will provide subclasses specific to each
+    # endpoint, configured with appropriate values.
+    #
+    # Note that these options inherit up the class hierarchy. If a particular
+    # options is not set for a subclass, its superclass is queried.
+    #
+    # Some older users of this class set options via constants. This usage is
+    # deprecated. For example, instead of setting the `AUDIENCE` constant on
+    # your subclass, call the `audience=` method.
+    #
+    # ## Example
+    #
+    #     class MyCredentials < Google::Auth::Credentials
+    #       # Set the default scope for these credentials
+    #       self.scope = "http://example.com/my_scope"
+    #     end
+    #
+    #     # creds is a credentials object suitable for Google API clients
+    #     creds = MyCredentials.default
+    #     creds.scope  # => ["http://example.com/my_scope"]
+    #
+    #     class SubCredentials < MyCredentials
+    #       # Override the default scope for this subclass
+    #       self.scope = "http://example.com/sub_scope"
+    #     end
+    #
+    #     creds2 = SubCredentials.default
+    #     creds2.scope  # => ["http://example.com/sub_scope"]
+    #
+    class Credentials # rubocop:disable Metrics/ClassLength
+      ##
+      # The default token credential URI to be used when none is provided during initialization.
       TOKEN_CREDENTIAL_URI = "https://oauth2.googleapis.com/token".freeze
+
+      ##
+      # The default target audience ID to be used when none is provided during initialization.
       AUDIENCE = "https://oauth2.googleapis.com/token".freeze
-      SCOPE = [].freeze
-      PATH_ENV_VARS = [].freeze
-      JSON_ENV_VARS = [].freeze
-      DEFAULT_PATHS = [].freeze
 
+      @audience = @scope = @target_audience = @env_vars = @paths = @token_credential_uri = nil
+
+      ##
+      # The default token credential URI to be used when none is provided during initialization.
+      # The URI is the authorization server's HTTP endpoint capable of issuing tokens and
+      # refreshing expired tokens.
+      #
+      # @return [String]
+      #
+      def self.token_credential_uri
+        lookup_auth_param :token_credential_uri do
+          lookup_local_constant :TOKEN_CREDENTIAL_URI
+        end
+      end
+
+      ##
+      # Set the default token credential URI to be used when none is provided during initialization.
+      #
+      # @param [String] new_token_credential_uri
+      #
+      def self.token_credential_uri= new_token_credential_uri
+        @token_credential_uri = new_token_credential_uri
+      end
+
+      ##
+      # The default target audience ID to be used when none is provided during initialization.
+      # Used only by the assertion grant type.
+      #
+      # @return [String]
+      #
+      def self.audience
+        lookup_auth_param :audience do
+          lookup_local_constant :AUDIENCE
+        end
+      end
+
+      ##
+      # Sets the default target audience ID to be used when none is provided during initialization.
+      #
+      # @param [String] new_audience
+      #
+      def self.audience= new_audience
+        @audience = new_audience
+      end
+
+      ##
+      # The default scope to be used when none is provided during initialization.
+      # A scope is an access range defined by the authorization server.
+      # The scope can be a single value or a list of values.
+      #
+      # Either {#scope} or {#target_audience}, but not both, should be non-nil.
+      # If {#scope} is set, this credential will produce access tokens.
+      # If {#target_audience} is set, this credential will produce ID tokens.
+      #
+      # @return [String, Array<String>, nil]
+      #
+      def self.scope
+        lookup_auth_param :scope do
+          vals = lookup_local_constant :SCOPE
+          vals ? Array(vals).flatten.uniq : nil
+        end
+      end
+
+      ##
+      # Sets the default scope to be used when none is provided during initialization.
+      #
+      # Either {#scope} or {#target_audience}, but not both, should be non-nil.
+      # If {#scope} is set, this credential will produce access tokens.
+      # If {#target_audience} is set, this credential will produce ID tokens.
+      #
+      # @param [String, Array<String>, nil] new_scope
+      #
+      def self.scope= new_scope
+        new_scope = Array new_scope unless new_scope.nil?
+        @scope = new_scope
+      end
+
+      ##
+      # The default final target audience for ID tokens, to be used when none
+      # is provided during initialization.
+      #
+      # Either {#scope} or {#target_audience}, but not both, should be non-nil.
+      # If {#scope} is set, this credential will produce access tokens.
+      # If {#target_audience} is set, this credential will produce ID tokens.
+      #
+      # @return [String, nil]
+      #
+      def self.target_audience
+        lookup_auth_param :target_audience
+      end
+
+      ##
+      # Sets the default final target audience for ID tokens, to be used when none
+      # is provided during initialization.
+      #
+      # Either {#scope} or {#target_audience}, but not both, should be non-nil.
+      # If {#scope} is set, this credential will produce access tokens.
+      # If {#target_audience} is set, this credential will produce ID tokens.
+      #
+      # @param [String, nil] new_target_audience
+      #
+      def self.target_audience= new_target_audience
+        @target_audience = new_target_audience
+      end
+
+      ##
+      # The environment variables to search for credentials. Values can either be a file path to the
+      # credentials file, or the JSON contents of the credentials file.
+      # The env_vars will never be nil. If there are no vars, the empty array is returned.
+      #
+      # @return [Array<String>]
+      #
+      def self.env_vars
+        env_vars_internal || []
+      end
+
+      ##
+      # @private
+      # Internal recursive lookup for env_vars.
+      #
+      def self.env_vars_internal
+        lookup_auth_param :env_vars, :env_vars_internal do
+          # Pull values when PATH_ENV_VARS or JSON_ENV_VARS constants exists.
+          path_env_vars = lookup_local_constant :PATH_ENV_VARS
+          json_env_vars = lookup_local_constant :JSON_ENV_VARS
+          (Array(path_env_vars) + Array(json_env_vars)).flatten.uniq if path_env_vars || json_env_vars
+        end
+      end
+
+      ##
+      # Sets the environment variables to search for credentials.
+      # Setting to `nil` "unsets" the value, and defaults to the superclass
+      # (or to the empty array if there is no superclass).
+      #
+      # @param [String, Array<String>, nil] new_env_vars
+      #
+      def self.env_vars= new_env_vars
+        new_env_vars = Array new_env_vars unless new_env_vars.nil?
+        @env_vars = new_env_vars
+      end
+
+      ##
+      # The file paths to search for credentials files.
+      # The paths will never be nil. If there are no paths, the empty array is returned.
+      #
+      # @return [Array<String>]
+      #
+      def self.paths
+        paths_internal || []
+      end
+
+      ##
+      # @private
+      # Internal recursive lookup for paths.
+      #
+      def self.paths_internal
+        lookup_auth_param :paths, :paths_internal do
+          # Pull in values if the DEFAULT_PATHS constant exists.
+          vals = lookup_local_constant :DEFAULT_PATHS
+          vals ? Array(vals).flatten.uniq : nil
+        end
+      end
+
+      ##
+      # Set the file paths to search for credentials files.
+      # Setting to `nil` "unsets" the value, and defaults to the superclass
+      # (or to the empty array if there is no superclass).
+      #
+      # @param [String, Array<String>, nil] new_paths
+      #
+      def self.paths= new_paths
+        new_paths = Array new_paths unless new_paths.nil?
+        @paths = new_paths
+      end
+
+      ##
+      # @private
+      # Return the given parameter value, defaulting up the class hierarchy.
+      #
+      # First returns the value of the instance variable, if set.
+      # Next, calls the given block if provided. (This is generally used to
+      # look up legacy constant-based values.)
+      # Otherwise, calls the superclass method if present.
+      # Returns nil if all steps fail.
+      #
+      # @param name [Symbol] The parameter name
+      # @param method_name [Symbol] The lookup method name, if different
+      # @return [Object] The value
+      #
+      def self.lookup_auth_param name, method_name = name
+        val = instance_variable_get "@#{name}".to_sym
+        val = yield if val.nil? && block_given?
+        return val unless val.nil?
+        return superclass.send method_name if superclass.respond_to? method_name
+        nil
+      end
+
+      ##
+      # @private
+      # Return the value of the given constant if it is defined directly in
+      # this class, or nil if not.
+      #
+      # @param [Symbol] Name of the constant
+      # @return [Object] The value
+      #
+      def self.lookup_local_constant name
+        const_defined?(name, false) ? const_get(name) : nil
+      end
+
+      ##
+      # The Signet::OAuth2::Client object the Credentials instance is using.
+      #
+      # @return [Signet::OAuth2::Client]
+      #
       attr_accessor :client
-      attr_reader   :project_id
 
-      # Delegate client methods to the client object.
+      ##
+      # Identifier for the project the client is authenticating with.
+      #
+      # @return [String]
+      #
+      attr_reader :project_id
+
+      ##
+      # Identifier for a separate project used for billing/quota, if any.
+      #
+      # @return [String,nil]
+      #
+      attr_reader :quota_project_id
+
+      # @private Delegate client methods to the client object.
       extend Forwardable
+
+      ##
+      # @!attribute [r] token_credential_uri
+      #   @return [String] The token credential URI. The URI is the authorization server's HTTP
+      #     endpoint capable of issuing tokens and refreshing expired tokens.
+      #
+      # @!attribute [r] audience
+      #   @return [String] The target audience ID when issuing assertions. Used only by the
+      #     assertion grant type.
+      #
+      # @!attribute [r] scope
+      #   @return [String, Array<String>] The scope for this client. A scope is an access range
+      #     defined by the authorization server. The scope can be a single value or a list of values.
+      #
+      # @!attribute [r] target_audience
+      #   @return [String] The final target audience for ID tokens returned by this credential.
+      #
+      # @!attribute [r] issuer
+      #   @return [String] The issuer ID associated with this client.
+      #
+      # @!attribute [r] signing_key
+      #   @return [String, OpenSSL::PKey] The signing key associated with this client.
+      #
+      # @!attribute [r] updater_proc
+      #   @return [Proc] Returns a reference to the {Signet::OAuth2::Client#apply} method,
+      #     suitable for passing as a closure.
+      #
       def_delegators :@client,
                      :token_credential_uri, :audience,
-                     :scope, :issuer, :signing_key, :updater_proc
+                     :scope, :issuer, :signing_key, :updater_proc, :target_audience
 
-      # rubocop:disable Metrics/AbcSize
+      ##
+      # Creates a new Credentials instance with the provided auth credentials, and with the default
+      # values configured on the class.
+      #
+      # @param [String, Hash, Signet::OAuth2::Client] keyfile
+      #   The keyfile can be provided as one of the following:
+      #
+      #   * The path to a JSON keyfile (as a +String+)
+      #   * The contents of a JSON keyfile (as a +Hash+)
+      #   * A +Signet::OAuth2::Client+ object
+      # @param [Hash] options
+      #   The options for configuring the credentials instance. The following is supported:
+      #
+      #   * +:scope+ - the scope for the client
+      #   * +"project_id"+ (and optionally +"project"+) - the project identifier for the client
+      #   * +:connection_builder+ - the connection builder to use for the client
+      #   * +:default_connection+ - the default connection to use for the client
+      #
       def initialize keyfile, options = {}
-        scope = options[:scope]
         verify_keyfile_provided! keyfile
         @project_id = options["project_id"] || options["project"]
-        if keyfile.is_a? Signet::OAuth2::Client
-          @client = keyfile
-          @project_id ||= keyfile.project_id if keyfile.respond_to? :project_id
-        elsif keyfile.is_a? Hash
-          hash = stringify_hash_keys keyfile
-          hash["scope"] ||= scope
-          @client = init_client hash, options
-          @project_id ||= (hash["project_id"] || hash["project"])
+        @quota_project_id = options["quota_project_id"]
+        case keyfile
+        when Signet::OAuth2::Client
+          update_from_signet keyfile
+        when Hash
+          update_from_hash keyfile, options
         else
-          verify_keyfile_exists! keyfile
-          json = JSON.parse ::File.read(keyfile)
-          json["scope"] ||= scope
-          @project_id ||= (json["project_id"] || json["project"])
-          @client = init_client json, options
+          update_from_filepath keyfile, options
         end
         CredentialsLoader.warn_if_cloud_sdk_credentials @client.client_id
         @project_id ||= CredentialsLoader.load_gcloud_project_id
         @client.fetch_access_token!
+        @env_vars = nil
+        @paths = nil
+        @scope = nil
       end
-      # rubocop:enable Metrics/AbcSize
 
-      # Returns the default credentials checking, in this order, the path env
-      # evironment variables, json environment variables, default paths. If the
-      # previously stated locations do not contain keyfile information,
-      # this method defaults to use the application default.
+      ##
+      # Creates a new Credentials instance with auth credentials acquired by searching the
+      # environment variables and paths configured on the class, and with the default values
+      # configured on the class.
+      #
+      # The auth credentials are searched for in the following order:
+      #
+      # 1. configured environment variables (see {Credentials.env_vars})
+      # 2. configured default file paths (see {Credentials.paths})
+      # 3. application default (see {Google::Auth.get_application_default})
+      #
+      # @param [Hash] options
+      #   The options for configuring the credentials instance. The following is supported:
+      #
+      #   * +:scope+ - the scope for the client
+      #   * +"project_id"+ (and optionally +"project"+) - the project identifier for the client
+      #   * +:connection_builder+ - the connection builder to use for the client
+      #   * +:default_connection+ - the default connection to use for the client
+      #
+      # @return [Credentials]
+      #
       def self.default options = {}
-        # First try to find keyfile file from environment variables.
-        client = from_path_vars options
+        # First try to find keyfile file or json from environment variables.
+        client = from_env_vars options
 
-        # Second try to find keyfile json from environment variables.
-        client ||= from_json_vars options
-
-        # Third try to find keyfile file from known file paths.
+        # Second try to find keyfile file from known file paths.
         client ||= from_default_paths options
 
         # Finally get instantiated client from Google::Auth
@@ -99,49 +418,68 @@ module Google
         client
       end
 
-      def self.from_path_vars options
-        self::PATH_ENV_VARS
-          .map { |v| ENV[v] }
-          .compact
-          .select { |p| ::File.file? p }
-          .each do |file|
-            return new file, options
-          end
-        nil
-      end
-
-      def self.from_json_vars options
-        json = lambda do |v|
-          unless ENV[v].nil?
-            begin
-              JSON.parse ENV[v]
-            rescue StandardError
-              nil
+      ##
+      # @private Lookup Credentials from environment variables.
+      def self.from_env_vars options
+        env_vars.each do |env_var|
+          str = ENV[env_var]
+          next if str.nil?
+          io =
+            if ::File.file? str
+              ::StringIO.new ::File.read str
+            else
+              json = ::JSON.parse str rescue nil
+              json ? ::StringIO.new(str) : nil
             end
-          end
+          next if io.nil?
+          return from_io io, options
         end
-        self::JSON_ENV_VARS.map(&json).compact.each { |hash| return new hash, options }
         nil
       end
 
+      ##
+      # @private Lookup Credentials from default file paths.
       def self.from_default_paths options
-        self::DEFAULT_PATHS
-          .select { |p| ::File.file? p }
-          .each do |file|
-            return new file, options
-          end
+        paths.each do |path|
+          next unless path && ::File.file?(path)
+          io = ::StringIO.new ::File.read path
+          return from_io io, options
+        end
         nil
       end
 
+      ##
+      # @private Lookup Credentials using Google::Auth.get_application_default.
       def self.from_application_default options
-        scope = options[:scope] || self::SCOPE
-        client = Google::Auth.get_application_default scope
+        scope = options[:scope] || self.scope
+        auth_opts = {
+          token_credential_uri:   options[:token_credential_uri] || token_credential_uri,
+          audience:               options[:audience] || audience,
+          target_audience:        options[:target_audience] || target_audience,
+          enable_self_signed_jwt: options[:enable_self_signed_jwt] && options[:scope].nil?
+        }
+        client = Google::Auth.get_application_default scope, auth_opts
         new client, options
       end
-      private_class_method :from_path_vars,
-                           :from_json_vars,
+
+      # @private Read credentials from a JSON stream.
+      def self.from_io io, options
+        creds_input = {
+          json_key_io:            io,
+          scope:                  options[:scope] || scope,
+          target_audience:        options[:target_audience] || target_audience,
+          enable_self_signed_jwt: options[:enable_self_signed_jwt] && options[:scope].nil?,
+          token_credential_uri:   options[:token_credential_uri] || token_credential_uri,
+          audience:               options[:audience] || audience
+        }
+        client = Google::Auth::DefaultCredentials.make_creds creds_input
+        new client
+      end
+
+      private_class_method :from_env_vars,
                            :from_default_paths,
-                           :from_application_default
+                           :from_application_default,
+                           :from_io
 
       protected
 
@@ -166,22 +504,58 @@ module Google
 
       # returns a new Hash with string keys instead of symbol keys.
       def stringify_hash_keys hash
-        Hash[hash.map { |k, v| [k.to_s, v] }]
+        hash.to_h.transform_keys(&:to_s)
       end
 
+      # rubocop:disable Metrics/AbcSize
+
       def client_options options
         # Keyfile options have higher priority over constructor defaults
-        options["token_credential_uri"] ||= self.class::TOKEN_CREDENTIAL_URI
-        options["audience"] ||= self.class::AUDIENCE
-        options["scope"] ||= self.class::SCOPE
+        options["token_credential_uri"] ||= self.class.token_credential_uri
+        options["audience"] ||= self.class.audience
+        options["scope"] ||= self.class.scope
+        options["target_audience"] ||= self.class.target_audience
+
+        if !Array(options["scope"]).empty? && options["target_audience"]
+          raise ArgumentError, "Cannot specify both scope and target_audience"
+        end
 
+        needs_scope = options["target_audience"].nil?
         # client options for initializing signet client
         { token_credential_uri: options["token_credential_uri"],
           audience:             options["audience"],
-          scope:                Array(options["scope"]),
+          scope:                (needs_scope ? Array(options["scope"]) : nil),
+          target_audience:      options["target_audience"],
           issuer:               options["client_email"],
           signing_key:          OpenSSL::PKey::RSA.new(options["private_key"]) }
       end
+
+      # rubocop:enable Metrics/AbcSize
+
+      def update_from_signet client
+        @project_id ||= client.project_id if client.respond_to? :project_id
+        @quota_project_id ||= client.quota_project_id if client.respond_to? :quota_project_id
+        @client = client
+      end
+
+      def update_from_hash hash, options
+        hash = stringify_hash_keys hash
+        hash["scope"] ||= options[:scope]
+        hash["target_audience"] ||= options[:target_audience]
+        @project_id ||= (hash["project_id"] || hash["project"])
+        @quota_project_id ||= hash["quota_project_id"]
+        @client = init_client hash, options
+      end
+
+      def update_from_filepath path, options
+        verify_keyfile_exists! path
+        json = JSON.parse ::File.read(path)
+        json["scope"] ||= options[:scope]
+        json["target_audience"] ||= options[:target_audience]
+        @project_id ||= (json["project_id"] || json["project"])
+        @quota_project_id ||= json["quota_project_id"]
+        @client = init_client json, options
+      end
     end
   end
 end