googleauth 1.13.1 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d8ca5b2b0c7f4ce54f7971d8de2f23f3ee0837d08d7d3c568c503308fcf82ab
-  data.tar.gz: d5f8b8fd2fcb4fef4240db58bf90f54a8bfd021c550a7bc9063c9087285f3921
+  metadata.gz: 34a8ff0141f7866d8f253bea4adbdd406c8aab873c7f18be6ac78ee981e16a39
+  data.tar.gz: 1191ce29114f13eb0d855ef46502015eb309cf694bd053171614b15d571e15f7
 SHA512:
-  metadata.gz: 6a4de2b23f4dc0310a18568e0618c5d81fad54dfc8d57fe3c27b954c4bd21272fcc467c2c313f98f80fa127eab11ebe0d0fc55ceed7e6c5439764500e334df49
-  data.tar.gz: f4aff68138105ea19875bb7a51d4b6ced9ec2e7185ce725eca205ea1dc11beb9e6019c9dd89449866598ca6e4d3abb06b91f277f34e51ac7726d79a39fc40c67
+  metadata.gz: 9286311e4de659c8820cdbdfb4ae48f1a3b0c519c66208a3c3f56a3a1079597b10306d6ab8aef05687df347262f26c75af63c4cbeac7570162829d926edf0317
+  data.tar.gz: 43954778b73cf95537a29a2317abe5b22eebfc3336e560657ec580542df9a7e9f42513968d27fc2b13621b0da0aa8fb8510ef59c9170bad611b0bd5b86f16888

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Release History
 
+### 1.15.0 (2025-08-25)
+
+#### Features
+
+* add typed errors to authentication library ([#533](https://github.com/googleapis/google-auth-library-ruby/issues/533)) 
+* Support for JWT 3.x ([#542](https://github.com/googleapis/google-auth-library-ruby/issues/542)) 
+#### Bug Fixes
+
+* fix incorrect error and apply some code complexity refactoring ([#529](https://github.com/googleapis/google-auth-library-ruby/issues/529)) 
+* support Pathname for cred loading ([#537](https://github.com/googleapis/google-auth-library-ruby/issues/537)) 
+#### Documentation
+
+* add summary documentation on credentials types and improve YARD comments 
+* add summary documentation on credentials types and improve YARD comments ([#530](https://github.com/googleapis/google-auth-library-ruby/issues/530)) 
+
+### 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

data/Credentials.md

@@ -0,0 +1,106 @@
+# Introduction
+
+The closest thing to a base credentials class is the `BaseClient` module. 
+It includes functionality common to most credentials, such as applying authentication tokens to request headers, managing token expiration and refresh, handling logging, and providing updater procs for API clients.
+
+Many credentials classes inherit from `Signet::OAuth2::Client` (`lib/googleauth/signet.rb`) class which provides OAuth-based authentication.
+The `Signet::OAuth2::Client` includes the `BaseClient` functionality.
+
+Most credential types either inherit from `Signet::OAuth2::Client` or include the `BaseClient` module directly.
+
+Notably, `Google::Auth::Credentials` (`lib/googleauth/credentials.rb`) is not a base type or a credentials type per se. It is a wrapper for other credential classes
+that exposes common initialization functionality, such as creating credentials from environment variables, default paths, or application defaults. It is used and subclassed by Google's API client libraries.
+
+# List of credentials types
+
+## Simple Authentication (non-OAuth)
+
+**Google::Auth::APIKeyCredentials** - `lib/googleauth/api_key.rb`
+   - Includes `Google::Auth::BaseClient` module
+   - Implements Google API Key authentication
+   - API Keys are text strings that don't have an associated JSON file
+   - API Keys provide project information but don't reference an IAM principal
+   - They do not expire and cannot be refreshed
+   - Can be loaded from the `GOOGLE_API_KEY` environment variable
+
+2. **Google::Auth::BearerTokenCredentials** - `lib/googleauth/bearer_token.rb`
+   - Includes `Google::Auth::BaseClient` module
+   - Implements Bearer Token authentication
+   - Bearer tokens are strings representing an authorization grant
+   - Can be OAuth2 tokens, JWTs, ID tokens, or any token sent as a `Bearer` in an `Authorization` header
+   - Used when the end-user is managing the token separately (e.g., with another service)
+   - Token lifetime tracking and refresh are outside this class's scope
+   - No JSON representation for this type of credentials
+
+## GCP-Specialized authentication
+
+3. **Google::Auth::GCECredentials < Signet::OAuth2::Client** - `lib/googleauth/compute_engine.rb`
+   - For obtaining authentication tokens from GCE metadata server
+   - Used automatically when code is running on Google Compute Engine
+   - Fetches tokens from the metadata server with no additional configuration needed
+
+4. **Google::Auth::IAMCredentials < Signet::OAuth2::Client** - `lib/googleauth/iam.rb`
+   - For IAM-based authentication (e.g. service-to-service)
+   - Implements authentication-as-a-service for systems already authenticated
+   - Exchanges existing credentials for a short-lived access token
+
+## Service Account Authentication
+
+5. **Google::Auth::ServiceAccountCredentials < Signet::OAuth2::Client** - `lib/googleauth/service_account.rb`
+   - Authenticates requests using Service Account credentials via an OAuth access token
+   - Created from JSON key file downloaded from Google Cloud Console
+   - Supports both OAuth access tokens and self-signed JWT authentication
+   - Can specify scopes for access token requests
+
+6. **Google::Auth::ServiceAccountJwtHeaderCredentials** - `lib/googleauth/service_account_jwt_header.rb`
+   - Authenticates using Service Account credentials with JWT headers
+   - Typically used via `ServiceAccountCredentials` and not by itself
+   - Creates JWT directly for making authenticated calls
+   - Does not require a round trip to the authorization server
+   - Doesn't support OAuth scopes - uses audience (target API) instead
+
+7. **Google::Auth::ImpersonatedServiceAccountCredentials < Signet::OAuth2::Client** - `lib/googleauth/impersonated_service_account.rb`
+   - For service account impersonation
+   - Allows a GCP principal identified by a set of source credentials to impersonate a service account
+   - Useful for delegation of authority and managing permissions across service accounts
+   - Source credentials must have the Service Account Token Creator role on the target
+
+## User Authentication
+
+8. **Google::Auth::UserRefreshCredentials < Signet::OAuth2::Client** - `lib/googleauth/user_refresh.rb`
+   - For user refresh token authentication (from 3-legged OAuth flow)
+   - Authenticates on behalf of a user who has authorized the application
+   - Handles token refresh when original access token expires
+   - Typically obtained through web or installed application flow
+
+`Google::Auth::UserAuthorizer` (`lib/googleauth/user_authorizer.rb`) and `Google::Auth::WebUserAuthorizer` (`lib/googleauth/web_user_authorizer.rb`)
+ are used to facilitate user authentication. The `UserAuthorizer` handles interactive 3-Legged-OAuth2 (3LO) user consent authorization for command-line applications.
+ The `WebUserAuthorizer` is a variation of UserAuthorizer adapted for Rack-based web applications that manages OAuth state and provides callback handling.
+
+## External Account Authentication
+  `Google::Auth::ExternalAccount::Credentials` (`lib/googleauth/external_account.rb`) is not a credentials type, it is a module
+  that procides an entry point for External Account credentials. It also serves as a factory that creates appropriate credential
+  types based on credential source (similar to `Google::Auth::get_application_default`).
+  It is included in all External Account credentials types, and it itself includes `Google::Auth::BaseClient` module so all External
+  Account credentials types include `Google::Auth::BaseClient`.
+
+9. **Google::Auth::ExternalAccount::AwsCredentials** - `lib/googleauth/external_account/aws_credentials.rb`
+     - Includes `Google::Auth::BaseClient` module
+     - Includes `ExternalAccount::BaseCredentials` module
+     - Uses AWS credentials to authenticate to Google Cloud
+     - Exchanges temporary AWS credentials for Google access tokens
+     - Used for workloads running on AWS that need to access Google Cloud
+
+10. **Google::Auth::ExternalAccount::IdentityPoolCredentials** - `lib/googleauth/external_account/identity_pool_credentials.rb`
+     - Includes `Google::Auth::BaseClient` module
+     - Includes `ExternalAccount::BaseCredentials` module
+     - Authenticates using external identity pool
+     - Exchanges external identity tokens for Google access tokens
+     - Supports file-based and URL-based credential sources
+
+11. **Google::Auth::ExternalAccount::PluggableCredentials** - `lib/googleauth/external_account/pluggable_credentials.rb`
+     - Includes `Google::Auth::BaseClient` module
+     - Includes `ExternalAccount::BaseCredentials` module
+     - Supports executable-based credential sources
+     - Executes external programs to retrieve credentials
+     - Allows for custom authentication mechanisms via external executables

data/Errors.md

@@ -0,0 +1,152 @@
+# Error Handling in Google Auth Library for Ruby
+
+## Overview
+
+The Google Auth Library for Ruby provides a structured approach to error handling. This document explains the error hierarchy, how to access detailed error information, and provides examples of handling errors effectively.
+
+## Error Hierarchy
+
+The Google Auth Library has two main error hierarchies: the core authentication errors and the specialized ID token flow errors.
+
+### Core Authentication Errors
+
+These errors are used throughout the main library for general authentication and credential operations:
+
+```
+Google::Auth::Error (module)
+  ├── Google::Auth::InitializationError (class)
+  └── Google::Auth::DetailedError (module)
+      ├── Google::Auth::CredentialsError (class)
+      ├── Google::Auth::AuthorizationError (class)
+      ├── Google::Auth::UnexpectedStatusError (class)
+      └── Google::Auth::ParseError (class)
+```
+
+### ID Token Errors
+
+These specialized errors are used specifically for ID token flow. They also include the `Google::Auth::Error` module, allowing them to be caught with the same error handling as the core authentication errors:
+
+```
+Google::Auth::Error (module)
+  ├── Google::Auth::IDTokens::KeySourceError (class)
+  └── Google::Auth::IDTokens::VerificationError (class)
+      ├── ExpiredTokenError (class)
+      ├── SignatureError (class)
+      ├── IssuerMismatchError (class)
+      ├── AudienceMismatchError (class)
+      └── AuthorizedPartyMismatchError (class)
+```
+
+### Error Module Types
+
+- **`Google::Auth::Error`**: Base module that all Google Auth errors include. Use this to catch any error from the library.
+
+- **`Google::Auth::DetailedError`**: Extends `Error` to include detailed information about the credential that caused the error, including the credential type and principal.
+
+## Core Authentication Error Classes
+
+- **`InitializationError`**: Raised during credential initialization when required parameters are missing or invalid.
+
+- **`CredentialsError`**: Generic error raised during authentication flows.
+
+- **`AuthorizationError`**: Raised when a remote server refuses to authorize the client. Inherits from `Signet::AuthorizationError`. Is being raised where `Signet::AuthorizationError` was raised previously.
+
+- **`UnexpectedStatusError`**: Raised when a server returns an unexpected HTTP status code. Inherits from `Signet::UnexpectedStatusError`. Is being raised where `Signet::UnexpectedStatusError` was raised previously.
+
+- **`ParseError`**: Raised when the client fails to parse a value from a response. Inherits from `Signet::ParseError`. Is being raised where `Signet::ParseError` was raised previously.
+
+## Detailed Error Information
+
+Errors that include the `DetailedError` module provide additional context about what went wrong:
+
+- **`credential_type_name`**: The class name of the credential that raised the error (e.g., `"Google::Auth::ServiceAccountCredentials"`)
+
+- **`principal`**: The identity associated with the credentials (e.g., an email address for service accounts, `:api_key` for API key credentials)
+
+### Example: Catching and Handling Core Errors
+
+```ruby
+begin
+  credentials = Google::Auth::ServiceAccountCredentials.make_creds(
+    json_key_io: File.open("your-key.json")
+  )
+  # Use credentials...
+rescue Google::Auth::InitializationError => e
+  puts "Failed to initialize credentials: #{e.message}"
+  # e.g., Missing required fields in the service account key file
+rescue Google::Auth::DetailedError => e
+  puts "Authorization failed: #{e.message}"
+  puts "Credential type: #{e.credential_type_name}"
+  puts "Principal: #{e.principal}"
+  # e.g., Invalid or revoked service account
+rescue Google::Auth::Error => e
+  puts "Unknown Google Auth error: #{e.message}"
+end
+```
+
+## Backwards compatibility
+
+Some classes in the Google Auth Library raise standard Ruby `ArgumentError` and `TypeError`. These errors are preserved for backward compatibility, however the new code will raise `Google::Auth::InitializationError` instead.
+
+## ID Token Verification
+
+The Google Auth Library includes functionality for verifying ID tokens through the `Google::Auth::IDTokens` namespace. These operations have their own specialized error classes that also include the `Google::Auth::Error` module, allowing them to be caught with the same error handling as other errors in the library.
+
+### ID Token Error Classes
+
+- **`KeySourceError`**: Raised when the library fails to obtain the keys needed to verify a token, typically from a JWKS (JSON Web Key Set) endpoint.
+
+- **`VerificationError`**: Base class for all errors related to token verification failures.
+
+- **`ExpiredTokenError`**: Raised when a token has expired according to its expiration time claim (`exp`).
+
+- **`SignatureError`**: Raised when a token's signature cannot be verified, indicating it might be tampered with or corrupted.
+
+- **`IssuerMismatchError`**: Raised when a token's issuer (`iss` claim) doesn't match the expected issuer.
+
+- **`AudienceMismatchError`**: Raised when a token's audience (`aud` claim) doesn't match the expected audience.
+
+- **`AuthorizedPartyMismatchError`**: Raised when a token's authorized party (`azp` claim) doesn't match the expected client ID.
+
+### Example: Handling ID Token Verification Errors
+
+```ruby
+require "googleauth/id_tokens"
+
+begin
+  # Verify the provided ID token
+  payload = Google::Auth::IDTokens.verify_oidc(
+    id_token,
+    audience: "expected-audience-12345.apps.googleusercontent.com"
+  )
+  
+  # Use the verified token payload
+  user_email = payload["email"]
+  
+rescue Google::Auth::IDTokens::ExpiredTokenError => e
+  puts "The token has expired. Please obtain a new one."
+
+rescue Google::Auth::IDTokens::SignatureError => e
+  puts "Invalid token signature."
+
+rescue Google::Auth::IDTokens::IssuerMismatchError => e
+  puts "Invalid token issuer."
+
+rescue Google::Auth::IDTokens::AudienceMismatchError => e
+  puts "This token is not intended for this application (invalid audience)."
+  
+rescue Google::Auth::IDTokens::AuthorizedPartyMismatchError => e
+  puts "Invalid token authorized party."
+
+rescue Google::Auth::IDTokens::VerificationError => e
+  puts "Token verification failed: #{e.message}"
+  # Generic verification error handling
+  
+rescue Google::Auth::IDTokens::KeySourceError => e
+  puts "Unable to retrieve verification keys: #{e.message}"
+  
+rescue Google::Auth::Error => e
+  puts "Unknown Google Auth error: #{e.message}"
+  # This will catch any Google Auth error
+end
+```

data/README.md

@@ -265,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,164 @@
+# 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)
+      # @raise [ArgumentError] If the API key is nil or empty
+      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
+
+      # For credentials that are initialized with a token without a principal,
+      # the type of that token should be returned as a principal instead
+      # @private
+      # @return [Symbol] the token type in lieu of the principal
+      def principal
+        token_type
+      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

@@ -14,6 +14,7 @@
 
 require "googleauth/compute_engine"
 require "googleauth/default_credentials"
+require "googleauth/errors"
 
 module Google
   # Module Auth provides classes that provide Google-specific authorization
@@ -50,12 +51,13 @@ module Google
     #       connection to use for token refresh requests.
     #     * `:connection` The connection to use to determine whether GCE
     #       metadata credentials are available.
+    # @raise [Google::Auth::InitializationError] If the credentials cannot be found
     def get_application_default scope = nil, options = {}
       creds = DefaultCredentials.from_env(scope, options) ||
               DefaultCredentials.from_well_known_path(scope, options) ||
               DefaultCredentials.from_system_default_path(scope, options)
       return creds unless creds.nil?
-      raise NOT_FOUND_ERROR unless GCECredentials.on_gce? options
+      raise InitializationError, NOT_FOUND_ERROR unless GCECredentials.on_gce? options
       GCECredentials.new options.merge(scope: scope)
     end
   end

data/lib/googleauth/base_client.rb

@@ -78,6 +78,11 @@ module Google
       # The logger used to log operations on this client, such as token refresh.
       attr_accessor :logger
 
+      # @private
+      def principal
+        raise NoMethodError, "principal not implemented"
+      end
+
       private
 
       def token_type

data/lib/googleauth/bearer_token.rb

@@ -0,0 +1,162 @@
+# 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/errors"
+
+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)
+      # @raise [ArgumentError] If the bearer token is nil or empty
+      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
+
+      # For credentials that are initialized with a token without a principal,
+      # the type of that token should be returned as a principal instead
+      # @private
+      # @return [Symbol] the token type in lieu of the principal
+      def principal
+        token_type
+      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 [Google::Auth::CredentialsError] If the token is expired.
+      def fetch_access_token! _options = {}
+        if @expires_at && Time.now >= @expires_at
+          raise CredentialsError.with_details(
+            "Bearer token has expired.",
+            credential_type_name: self.class.name,
+            principal: principal
+          )
+        end
+
+        nil
+      end
+
+      private
+
+      def token_type
+        :bearer_token
+      end
+    end
+  end
+end