1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
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
```
|
