googleauth 1.8.1 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37795e56189392a97d5941b4982730ffa2ee1dd53ec63593bbb7f5ad50be044e
-  data.tar.gz: 72d6b584c89c321698485bda1e4aef33f361ed35da4762bd22b5dc4634556f8f
+  metadata.gz: 9e2eef22c1062f2fd2216760e90a1af9ece1b99838bccea486a7b4ce43be9734
+  data.tar.gz: 1e60ef4856de1e4f7a3d423f3953e5e39f86c7002216ad2d98ee46ec88aaaf25
 SHA512:
-  metadata.gz: 1dcfc8f1e8e65f9b4b27c4933e71faffd2998d11766307cf464d0551d5f37e41c266e840a340a9aba41d49f44d05005006077526851b1b33e277ce3155d16370
-  data.tar.gz: f036b3403998c93f41eae33c472ad714758e6c6d06e9a1b197b53d118d182c2abb9caf40636ff63c152e2186642430de824e7929dcd2978cd358a5bd03194c1c
+  metadata.gz: d5a87f962d04eb59c9ae083a4d3c46fd54ef4d4c53f0571b3952f6d1a9d30e3af89fb2c50e04b118e301097850c9985c713968dc29c62c5d388d0d8a4c3d306d
+  data.tar.gz: fae67434766ed2d4bb67e2c7ba2784a9397843110c28d96368d368b1dd30229a1ea83c5ee05e70a712446781e67ca84149fbaa72dd4239eb349d6943ff42b9b3

data/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Release History
 
+### 1.14.0 (2025-03-14)
+
+#### Features
+
+* add API key credentials ([#520](https://github.com/googleapis/google-auth-library-ruby/issues/520)) 
+* Add Bearer token credentials 
+* add BearerToken credentials ([#522](https://github.com/googleapis/google-auth-library-ruby/issues/522)) 
+* Update minimum Ruby version to 3.0 ([#527](https://github.com/googleapis/google-auth-library-ruby/issues/527)) 
+#### Bug Fixes
+
+* Eliminated the "attribute accessor as module_function" warning ([#519](https://github.com/googleapis/google-auth-library-ruby/issues/519)) 
+* Get the project_id from gcloud ([#479](https://github.com/googleapis/google-auth-library-ruby/issues/479)) 
+* logger configuration in service account JWT header ([#525](https://github.com/googleapis/google-auth-library-ruby/issues/525)) 
+
+### 1.13.1 (2025-01-24)
+
+#### Bug Fixes
+
+* Signet client subclasses no longer make the update! method private ([#516](https://github.com/googleapis/google-auth-library-ruby/issues/516)) 
+
+### 1.13.0 (2025-01-22)
+
+#### Features
+
+* create impersonated service credentials ([#499](https://github.com/googleapis/google-auth-library-ruby/issues/499)) 
+#### Documentation
+
+* Include note about validating externally-provided credentials ([#512](https://github.com/googleapis/google-auth-library-ruby/issues/512)) 
+
+### 1.12.2 (2024-12-19)
+
+#### Bug Fixes
+
+* GCECredentials lazily fetches from the metadata server to ensure a universe domain is known ([#509](https://github.com/googleapis/google-auth-library-ruby/issues/509)) 
+
+### 1.12.1 (2024-12-17)
+
+#### Bug Fixes
+
+* Restored previous behavior where the apply! method returns the auth header ([#506](https://github.com/googleapis/google-auth-library-ruby/issues/506)) 
+
+### 1.12.0 (2024-12-05)
+
+#### Features
+
+* provided opt-in debug logging ([#490](https://github.com/googleapis/google-auth-library-ruby/issues/490)) 
+
+### 1.11.2 (2024-10-23)
+
+#### Bug Fixes
+
+* Temporarily disable universe domain query from GCE metadata server ([#493](https://github.com/googleapis/google-auth-library-ruby/issues/493)) 
+* Use updated metadata path for universe-domain ([#496](https://github.com/googleapis/google-auth-library-ruby/issues/496)) 
+
+### 1.11.1 (2024-10-04)
+
+#### Bug Fixes
+
+* Fixed parsing of expiration timestamp from ID tokens ([#492](https://github.com/googleapis/google-auth-library-ruby/issues/492)) 
+* Use NoMethodError instead of NotImplementedError for unimplemented base class methods ([#487](https://github.com/googleapis/google-auth-library-ruby/issues/487)) 
+
+### 1.11.0 (2024-02-09)
+
+#### Features
+
+* Deprecate the positional argument for callback_uri, and introduce keyword argument instead ([#475](https://github.com/googleapis/google-auth-library-ruby/issues/475)) 
+
+### 1.10.0 (2024-02-08)
+
+#### Features
+
+* add PKCE to 3 Legged OAuth exchange ([#471](https://github.com/googleapis/google-auth-library-ruby/issues/471)) 
+#### Bug Fixes
+
+* Client library credentials provide correct self-signed JWT and external account behavior when loading from a file path or JSON data ([#474](https://github.com/googleapis/google-auth-library-ruby/issues/474)) 
+* Prioritize universe domain specified in GCECredentials arguments over metadata-fetched value ([#472](https://github.com/googleapis/google-auth-library-ruby/issues/472)) 
+
+### 1.9.2 (2024-01-25)
+
+#### Bug Fixes
+
+* Prevent access tokens from being fetched at service account construction in the self-signed-jwt case ([#467](https://github.com/googleapis/google-auth-library-ruby/issues/467)) 
+
+### 1.9.1 (2023-12-12)
+
+#### Bug Fixes
+
+* update expires_in for cached metadata-retrieved tokens ([#464](https://github.com/googleapis/google-auth-library-ruby/issues/464)) 
+
+### 1.9.0 (2023-12-07)
+
+#### Features
+
+* Include universe_domain in credentials ([#460](https://github.com/googleapis/google-auth-library-ruby/issues/460)) 
+* Use google-cloud-env for more robust Metadata Service access ([#459](https://github.com/googleapis/google-auth-library-ruby/issues/459)) 
+
 ### 1.8.1 (2023-09-19)
 
 #### Documentation

data/README.md

@@ -64,6 +64,15 @@ well as a web variant tailored toward Rack-based applications.
 The authorizers are intended for authorization use cases. For sign-on,
 see [Google Identity Platform](https://developers.google.com/identity/)
 
+## Important notes
+
+If you accept a credential configuration (credential JSON/File/Stream) from an
+external source for authentication to Google Cloud, you must validate it before
+providing it to any Google API or library. Providing an unvalidated credential
+configuration to Google APIs can compromise the security of your systems and data.
+For more information, refer to [Validate credential configurations from external
+sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
+
 ### Example (Web)
 
 ```ruby
@@ -97,6 +106,45 @@ get('/oauth2callback') do
 end
 ```
 
+### Example (Web with PKCE)
+
+Proof Key for Code Exchange (PKCE) is an [RFC](https://www.rfc-editor.org/rfc/rfc7636) that aims to prevent malicious operating system processes from hijacking an OAUTH 2.0 exchange. PKCE mitigates the above vulnerability by including `code_challenge` and `code_challenge_method` parameters in the Authorization Request and a `code_verifier` parameter in the Access Token Request.
+
+```ruby
+require 'googleauth'
+require 'googleauth/web_user_authorizer'
+require 'googleauth/stores/redis_token_store'
+require 'redis'
+
+client_id = Google::Auth::ClientId.from_file('/path/to/client_secrets.json')
+scope = ['https://www.googleapis.com/auth/drive']
+token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)
+authorizer = Google::Auth::WebUserAuthorizer.new(
+  client_id, scope, token_store, '/oauth2callback')
+
+
+get('/authorize') do
+  # NOTE: Assumes the user is already authenticated to the app
+  user_id = request.session['user_id']
+  # User needs to take care of generating the code_verifier and storing it in
+  # the session.
+  request.session['code_verifier'] ||= Google::Auth::WebUserAuthorizer.generate_code_verifier
+  authorizer.code_verifier = request.session['code_verifier']
+  credentials = authorizer.get_credentials(user_id, request)
+  if credentials.nil?
+    redirect authorizer.get_authorization_url(login_hint: user_id, request: request)
+  end
+  # Credentials are valid, can call APIs
+  # ...
+end
+
+get('/oauth2callback') do
+  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(
+    request)
+  redirect target_url
+end
+```
+
 ### Example (Command Line) [Deprecated]
 
 The Google Auth OOB flow has been discontiued on January 31, 2023. The OOB flow is a legacy flow that is no longer considered secure. To continue using Google Auth, please migrate your applications to a more secure flow. For more information on how to do this, please refer to this [OOB Migration](https://developers.google.com/identity/protocols/oauth2/resources/oob-migration) guide.
@@ -217,7 +265,7 @@ Custom storage implementations can also be used. See
 
 ## Supported Ruby Versions
 
-This library is supported on Ruby 2.6+.
+This library is supported on Ruby 3.0+.
 
 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

data/lib/googleauth/api_key.rb

@@ -0,0 +1,155 @@
+# Copyright 2025 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/base_client"
+require "googleauth/credentials_loader"
+
+module Google
+  module Auth
+    ##
+    # Implementation of Google API Key authentication.
+    #
+    # API Keys are text strings. They don't have an associated JSON file.
+    #
+    # The end-user is managing their API Keys directly, not via
+    # an authentication library.
+    #
+    # API Keys provide project information for an API request.
+    # API Keys don't reference an IAM principal, they do not expire,
+    # and cannot be refreshed.
+    #
+    class APIKeyCredentials
+      include Google::Auth::BaseClient
+
+      # @private Authorization header key
+      API_KEY_HEADER = "x-goog-api-key".freeze
+
+      # @private Environment variable containing API key
+      API_KEY_VAR = "GOOGLE_API_KEY".freeze
+
+      # @return [String] The API key
+      attr_reader :api_key
+
+      # @return [String] The universe domain of the universe
+      #   this API key is for
+      attr_accessor :universe_domain
+
+      class << self
+        # Creates an APIKeyCredentials from the environment.
+        # Checks the ENV['GOOGLE_API_KEY'] variable.
+        #
+        # @param [String] _scope
+        #  The scope to use for OAuth. Not used by API key auth.
+        # @param [Hash] options
+        #  The options to pass to the credentials instance
+        #
+        # @return [Google::Auth::APIKeyCredentials, nil]
+        #  Credentials if the API key environment variable is present,
+        #  nil otherwise
+        def from_env _scope = nil, options = {}
+          api_key = ENV[API_KEY_VAR]
+          return nil if api_key.nil? || api_key.empty?
+          new options.merge(api_key: api_key)
+        end
+
+        # Create the APIKeyCredentials.
+        #
+        # @param [Hash] options The credentials options
+        # @option options [String] :api_key
+        #   The API key to use for authentication
+        # @option options [String] :universe_domain
+        #   The universe domain of the universe this API key
+        #   belongs to (defaults to googleapis.com)
+        # @return [Google::Auth::APIKeyCredentials]
+        def make_creds options = {}
+          new options
+        end
+      end
+
+      # Initialize the APIKeyCredentials.
+      #
+      # @param [Hash] options The credentials options
+      # @option options [String] :api_key
+      #   The API key to use for authentication
+      # @option options [String] :universe_domain
+      #   The universe domain of the universe this API key
+      #   belongs to (defaults to googleapis.com)
+      def initialize options = {}
+        raise ArgumentError, "API key must be provided" if options[:api_key].nil? || options[:api_key].empty?
+        @api_key = options[:api_key]
+        @universe_domain = options[:universe_domain] || "googleapis.com"
+      end
+
+      # Determines if the credentials object has expired.
+      # Since API keys don't expire, this always returns false.
+      #
+      # @param [Fixnum] _seconds
+      #  The optional timeout in seconds since the last refresh
+      # @return [Boolean]
+      #  True if the token has expired, false otherwise.
+      def expires_within? _seconds
+        false
+      end
+
+      # Creates a duplicate of these credentials.
+      #
+      # @param [Hash] options Additional options for configuring the credentials
+      # @return [Google::Auth::APIKeyCredentials]
+      def duplicate options = {}
+        self.class.new(
+          api_key: options[:api_key] || @api_key,
+          universe_domain: options[:universe_domain] || @universe_domain
+        )
+      end
+
+      # Updates the provided hash with the API Key header.
+      #
+      # The `apply!` method modifies the provided hash in place, adding the
+      # `x-goog-api-key` header with the API Key value.
+      #
+      # The API Key is hashed before being logged for security purposes.
+      #
+      # NB: this method typically would be called through `updater_proc`.
+      # Some older clients call it directly though, so it has to be public.
+      #
+      # @param [Hash] a_hash The hash to which the API Key header should be added.
+      #   This is typically a hash representing the request headers.  This hash
+      #   will be modified in place.
+      # @param [Hash] _opts  Additional options (currently not used).  Included
+      #   for consistency with the `BaseClient` interface.
+      # @return [Hash] The modified hash (the same hash passed as the `a_hash`
+      #   argument).
+      def apply! a_hash, _opts = {}
+        a_hash[API_KEY_HEADER] = @api_key
+        logger&.debug do
+          hash = Digest::SHA256.hexdigest @api_key
+          Google::Logging::Message.from message: "Sending API key auth token. (sha256:#{hash})"
+        end
+        a_hash
+      end
+
+      protected
+
+      # The token type should be :api_key
+      def token_type
+        :api_key
+      end
+
+      # We don't need to fetch access tokens for API key auth
+      def fetch_access_token! _options = {}
+        nil
+      end
+    end
+  end
+end

data/lib/googleauth/application_default.rb

@@ -55,11 +55,7 @@ module Google
               DefaultCredentials.from_well_known_path(scope, options) ||
               DefaultCredentials.from_system_default_path(scope, options)
       return creds unless creds.nil?
-      unless GCECredentials.on_gce? options
-        # Clear cache of the result of GCECredentials.on_gce?
-        GCECredentials.reset_cache
-        raise NOT_FOUND_ERROR
-      end
+      raise NOT_FOUND_ERROR unless GCECredentials.on_gce? options
       GCECredentials.new options.merge(scope: scope)
     end
   end

data/lib/googleauth/base_client.rb

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "google/logging/message"
+
 module Google
   # Module Auth provides classes that provide Google-specific authorization
   # used to access Google APIs.
@@ -29,7 +31,14 @@ module Google
         # fetch the access token there is currently not one, or if the client
         # has expired
         fetch_access_token! opts if needs_access_token?
-        a_hash[AUTH_METADATA_KEY] = "Bearer #{send token_type}"
+        token = send token_type
+        a_hash[AUTH_METADATA_KEY] = "Bearer #{token}"
+        logger&.debug do
+          hash = Digest::SHA256.hexdigest token
+          Google::Logging::Message.from message: "Sending auth token. (sha256:#{hash})"
+        end
+
+        a_hash[AUTH_METADATA_KEY]
       end
 
       # Returns a clone of a_hash updated with the authentication token
@@ -63,17 +72,20 @@ module Google
       end
 
       def expires_within?
-        raise NotImplementedError
+        raise NoMethodError, "expires_within? not implemented"
       end
 
+      # The logger used to log operations on this client, such as token refresh.
+      attr_accessor :logger
+
       private
 
       def token_type
-        raise NotImplementedError
+        raise NoMethodError, "token_type not implemented"
       end
 
       def fetch_access_token!
-        raise NotImplementedError
+        raise NoMethodError, "fetch_access_token! not implemented"
       end
     end
   end

data/lib/googleauth/bearer_token.rb

@@ -0,0 +1,148 @@
+# Copyright 2025 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/base_client"
+
+module Google
+  module Auth
+    ##
+    # Implementation of Bearer Token authentication scenario.
+    #
+    # Bearer tokens are strings representing an authorization grant.
+    # They can be OAuth2 ("ya.29") tokens, JWTs, IDTokens -- anything
+    # that is sent as a `Bearer` in an `Authorization` header.
+    #
+    # Not all 'authentication' strings can be used with this class,
+    # e.g. an API key cannot since API keys are sent in a
+    # `x-goog-api-key` header or as a query parameter.
+    #
+    # This class should be used when the end-user is managing the
+    # authentication token separately, e.g. with a separate service.
+    # This means that tasks like tracking the lifetime of and
+    # refreshing the token are outside the scope of this class.
+    #
+    # There is no JSON representation for this type of credentials.
+    # If the end-user has credentials in JSON format they should typically
+    # use the corresponding credentials type, e.g. ServiceAccountCredentials
+    # with the service account JSON.
+    #
+    class BearerTokenCredentials
+      include Google::Auth::BaseClient
+
+      # @private Authorization header name
+      AUTH_METADATA_KEY = Google::Auth::BaseClient::AUTH_METADATA_KEY
+
+      # @return [String] The token to be sent as a part of Bearer claim
+      attr_reader :token
+      # The following aliasing is needed for BaseClient since it sends :token_type
+      alias bearer_token token
+
+      # @return [Time, nil] The token expiration time provided by the end-user.
+      attr_reader :expires_at
+
+      # @return [String] The universe domain of the universe
+      #   this token is for
+      attr_accessor :universe_domain
+
+      class << self
+        # Create the BearerTokenCredentials.
+        #
+        # @param [Hash] options The credentials options
+        # @option options [String] :token The bearer token to use.
+        # @option options [Time, Numeric, nil] :expires_at The token expiration time provided by the end-user.
+        #   Optional, for the end-user's convenience. Can be a Time object, a number of seconds since epoch.
+        #   If `expires_at` is `nil`, it is treated as "token never expires".
+        # @option options [String] :universe_domain The universe domain of the universe
+        #   this token is for (defaults to googleapis.com)
+        # @return [Google::Auth::BearerTokenCredentials]
+        def make_creds options = {}
+          new options
+        end
+      end
+
+      # Initialize the BearerTokenCredentials.
+      #
+      # @param [Hash] options The credentials options
+      # @option options [String] :token The bearer token to use.
+      # @option options [Time, Numeric, nil] :expires_at The token expiration time provided by the end-user.
+      #   Optional, for the end-user's convenience. Can be a Time object, a number of seconds since epoch.
+      #   If `expires_at` is `nil`, it is treated as "token never expires".
+      # @option options [String] :universe_domain The universe domain of the universe
+      #   this token is for (defaults to googleapis.com)
+      def initialize options = {}
+        raise ArgumentError, "Bearer token must be provided" if options[:token].nil? || options[:token].empty?
+        @token = options[:token]
+        @expires_at = case options[:expires_at]
+                      when Time
+                        options[:expires_at]
+                      when Numeric
+                        Time.at options[:expires_at]
+                      end
+
+        @universe_domain = options[:universe_domain] || "googleapis.com"
+      end
+
+      # Determines if the credentials object has expired.
+      #
+      # @param [Numeric] seconds The optional timeout in seconds.
+      # @return [Boolean] True if the token has expired, false otherwise, or
+      #   if the expires_at was not provided.
+      def expires_within? seconds
+        return false if @expires_at.nil? # Treat nil expiration as "never expires"
+        Time.now + seconds >= @expires_at
+      end
+
+      # Creates a duplicate of these credentials.
+      #
+      # @param [Hash] options Additional options for configuring the credentials
+      # @option options [String] :token The bearer token to use.
+      # @option options [Time, Numeric] :expires_at The token expiration time. Can be a Time
+      #   object or a number of seconds since epoch.
+      # @option options [String] :universe_domain The universe domain (defaults to googleapis.com)
+      # @return [Google::Auth::BearerTokenCredentials]
+      def duplicate options = {}
+        self.class.new(
+          token: options[:token] || @token,
+          expires_at: options[:expires_at] || @expires_at,
+          universe_domain: options[:universe_domain] || @universe_domain
+        )
+      end
+
+      protected
+
+      ##
+      # BearerTokenCredentials do not support fetching a new token.
+      #
+      # If the token has an expiration time and is expired, this method will
+      # raise an error.
+      #
+      # @param [Hash] _options Options for fetching a new token (not used).
+      # @return [nil] Always returns nil.
+      # @raise [StandardError] If the token is expired.
+      def fetch_access_token! _options = {}
+        if @expires_at && Time.now >= @expires_at
+          raise "Bearer token has expired."
+        end
+
+        nil
+      end
+
+      private
+
+      def token_type
+        :bearer_token
+      end
+    end
+  end
+end