Module: Google::Auth::IDTokens

Defined in:
lib/googleauth/id_tokens.rb,
lib/googleauth/id_tokens/errors.rb,
lib/googleauth/id_tokens/verifier.rb,
lib/googleauth/id_tokens/key_sources.rb

Overview

## Verifying Google ID tokens

This module verifies ID tokens issued by Google. This can be used to authenticate signed-in users using OpenID Connect. See developers.google.com/identity/sign-in/web/backend-auth for more information.

### Basic usage

To verify an ID token issued by Google accounts:

payload = Google::Auth::IDTokens.verify_oidc the_token,
                                             aud: "my-app-client-id"

If verification succeeds, you will receive the token’s payload as a hash. If verification fails, an exception (normally a subclass of VerificationError) will be raised.

To verify an ID token issued by the Google identity-aware proxy (IAP):

payload = Google::Auth::IDTokens.verify_iap the_token,
                                            aud: "my-app-client-id"

These methods will automatically download and cache the Google public keys necessary to verify these tokens. They will also automatically verify the issuer (‘iss`) field for their respective types of ID tokens.

### Advanced usage

If you want to provide your own public keys, either by pointing at a custom URI or by providing the key data directly, use the Verifier class and pass in a key source.

To point to a custom URI that returns a JWK set:

source = Google::Auth::IDTokens::JwkHttpKeySource.new "https://example.com/jwk"
verifier = Google::Auth::IDTokens::Verifier.new key_source: source
payload = verifier.verify the_token, aud: "my-app-client-id"

To provide key data directly:

jwk_data = {
  keys: [
    {
      alg: "ES256",
      crv: "P-256",
      kid: "LYyP2g",
      kty: "EC",
      use: "sig",
      x: "SlXFFkJ3JxMsXyXNrqzE3ozl_0913PmNbccLLWfeQFU",
      y: "GLSahrZfBErmMUcHP0MGaeVnJdBwquhrhQ8eP05NfCI"
    }
  ]
}
source = Google::Auth::IDTokens::StaticKeySource.from_jwk_set jwk_data
verifier = Google::Auth::IDTokens::Verifier key_source: source
payload = verifier.verify the_token, aud: "my-app-client-id"

Defined Under Namespace

Classes: AggregateKeySource, AudienceMismatchError, AuthorizedPartyMismatchError, ExpiredTokenError, HttpKeySource, IssuerMismatchError, JwkHttpKeySource, KeyInfo, KeySourceError, SignatureError, StaticKeySource, VerificationError, Verifier, X509CertHttpKeySource

Constant Summary collapse

OIDC_ISSUERS =

A list of issuers expected for Google OIDC-issued tokens.

Returns:

  • (Array<String>) 
["accounts.google.com", "https://accounts.google.com"].freeze
IAP_ISSUERS =

A list of issuers expected for Google IAP-issued tokens.

Returns:

  • (Array<String>) 
["https://cloud.google.com/iap"].freeze
OAUTH2_V3_CERTS_URL =

The URL for Google OAuth2 V3 public certs

Returns:

  • (String) 
"https://www.googleapis.com/oauth2/v3/certs"
IAP_JWK_URL =

The URL for Google IAP public keys

Returns:

  • (String) 
"https://www.gstatic.com/iap/verify/public_key-jwk"

Class Method Summary collapse

Class Method Details

.forget_sources! ⇒ Object

Reset all convenience key sources. Used for testing.



150
151
152
153
 
# File 'lib/googleauth/id_tokens.rb', line 150

def forget_sources!
  @oidc_key_source = @iap_key_source = nil
  self
end

.iap_key_source ⇒ Google::Auth::IDTokens::JwkHttpKeySource

The key source providing public keys that can be used to verify ID tokens issued by Google IAP.

Returns:



142
143
144
 
# File 'lib/googleauth/id_tokens.rb', line 142

def iap_key_source
  @iap_key_source ||= JwkHttpKeySource.new IAP_JWK_URL
end

.oidc_key_source ⇒ Google::Auth::IDTokens::JwkHttpKeySource

The key source providing public keys that can be used to verify ID tokens issued by Google OIDC.

Returns:



132
133
134
 
# File 'lib/googleauth/id_tokens.rb', line 132

def oidc_key_source
  @oidc_key_source ||= JwkHttpKeySource.new OAUTH2_V3_CERTS_URL
end

.verify_iap(token, aud: nil, azp: nil, iss: IAP_ISSUERS) ⇒ Hash

A convenience method that verifies a token allegedly issued by Google IAP.

Parameters:

  • token (String) —

    The ID token to verify

  • aud (String, Array<String>, nil) (defaults to: nil) —

    The expected audience. At least one ‘aud` field in the token must match at least one of the provided audiences, or the verification will fail with Google::Auth::IDToken::AudienceMismatchError. If `nil` (the default), no audience checking is performed.

  • azp (String, Array<String>, nil) (defaults to: nil) —

    The expected authorized party (azp). At least one ‘azp` field in the token must match at least one of the provided values, or the verification will fail with Google::Auth::IDToken::AuthorizedPartyMismatchError. If `nil` (the default), no azp checking is performed.

  • aud (String, Array<String>, nil) (defaults to: nil) —

    The expected audience. At least one ‘iss` field in the token must match at least one of the provided issuers, or the verification will fail with Google::Auth::IDToken::IssuerMismatchError. If `nil`, no issuer checking is performed. Default is to check against IAP_ISSUERS.

Returns:

  • (Hash) —

    The decoded token payload.

Raises:

  • (KeySourceError) —

    if the key source failed to obtain public keys

  • (VerificationError) —

    if the token verification failed. Additional data may be available in the error subclass and message.



219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/googleauth/id_tokens.rb', line 219

def verify_iap token,
               aud: nil,
               azp: nil,
               iss: IAP_ISSUERS

  verifier = Verifier.new key_source: iap_key_source,
                          aud:        aud,
                          azp:        azp,
                          iss:        iss
  verifier.verify token
end

.verify_oidc(token, aud: nil, azp: nil, iss: OIDC_ISSUERS) ⇒ Hash

A convenience method that verifies a token allegedly issued by Google OIDC.

Parameters:

  • token (String) —

    The ID token to verify

  • aud (String, Array<String>, nil) (defaults to: nil) —

    The expected audience. At least one ‘aud` field in the token must match at least one of the provided audiences, or the verification will fail with Google::Auth::IDToken::AudienceMismatchError. If `nil` (the default), no audience checking is performed.

  • azp (String, Array<String>, nil) (defaults to: nil) —

    The expected authorized party (azp). At least one ‘azp` field in the token must match at least one of the provided values, or the verification will fail with Google::Auth::IDToken::AuthorizedPartyMismatchError. If `nil` (the default), no azp checking is performed.

  • aud (String, Array<String>, nil) (defaults to: nil) —

    The expected audience. At least one ‘iss` field in the token must match at least one of the provided issuers, or the verification will fail with Google::Auth::IDToken::IssuerMismatchError. If `nil`, no issuer checking is performed. Default is to check against OIDC_ISSUERS.

Returns:

  • (Hash) —

    The decoded token payload.

Raises:

  • (KeySourceError) —

    if the key source failed to obtain public keys

  • (VerificationError) —

    if the token verification failed. Additional data may be available in the error subclass and message.



181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/googleauth/id_tokens.rb', line 181

def verify_oidc token,
                aud: nil,
                azp: nil,
                iss: OIDC_ISSUERS

  verifier = Verifier.new key_source: oidc_key_source,
                          aud:        aud,
                          azp:        azp,
                          iss:        iss
  verifier.verify token
end