googleauth 1.8.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 888e57705b33e87158d060b7b1569e54e00000428de35f979e7ffc9456cbb7b3
-  data.tar.gz: ac341b6c481df125091c1465b56642173591f5698baff6f4806b05216eca8802
+  metadata.gz: 34a8ff0141f7866d8f253bea4adbdd406c8aab873c7f18be6ac78ee981e16a39
+  data.tar.gz: 1191ce29114f13eb0d855ef46502015eb309cf694bd053171614b15d571e15f7
 SHA512:
-  metadata.gz: 0e9d2fd50c39bf83e86f9f31bbddb897d28ce908be1214849926c45ce7ad2fa0d8f48d70a01acc84c9fa49ddf1a3a3c0c5a87b9bdf1d3ae1b9430b739e709c67
-  data.tar.gz: f92483b4971ecc9d48a0b3656a76c694974c6b60153d6ea5ff0f1dd6c544da51b924aedbfa71956db2c1dada98a6cdaa632bb6f38c663e384acc8ebb3af8d1d2
+  metadata.gz: 9286311e4de659c8820cdbdfb4ae48f1a3b0c519c66208a3c3f56a3a1079597b10306d6ab8aef05687df347262f26c75af63c4cbeac7570162829d926edf0317
+  data.tar.gz: 43954778b73cf95537a29a2317abe5b22eebfc3336e560657ec580542df9a7e9f42513968d27fc2b13621b0da0aa8fb8510ef59c9170bad611b0bd5b86f16888

data/CHANGELOG.md

@@ -1,5 +1,122 @@
 # 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
+
+* 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
+
+* improve ADC related error and warning messages ([#452](https://github.com/googleapis/google-auth-library-ruby/issues/452)) 
+
 ### 1.8.0 (2023-09-07)
 
 #### Features

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

@@ -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,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,15 +14,16 @@
 
 require "googleauth/compute_engine"
 require "googleauth/default_credentials"
+require "googleauth/errors"
 
 module Google
   # Module Auth provides classes that provide Google-specific authorization
   # used to access Google APIs.
   module Auth
     NOT_FOUND_ERROR = <<~ERROR_MESSAGE.freeze
-      Could not load the default credentials. Browse to
-      https://cloud.google.com/docs/authentication/provide-credentials-adc
-      for more information
+      Your credentials were not found. To set up Application Default
+      Credentials for your environment, see
+      https://cloud.google.com/docs/authentication/external/set-up-adc
     ERROR_MESSAGE
 
     module_function
@@ -50,16 +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?
-      unless GCECredentials.on_gce? options
-        # Clear cache of the result of GCECredentials.on_gce?
-        GCECredentials.reset_cache
-        raise NOT_FOUND_ERROR
-      end
+      raise InitializationError, NOT_FOUND_ERROR unless GCECredentials.on_gce? options
       GCECredentials.new options.merge(scope: scope)
     end
   end