Skip to content

Latest commit

 

History

History
152 lines (103 loc) · 6.37 KB

Errors.md

File metadata and controls

152 lines (103 loc) · 6.37 KB

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

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

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