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 https://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

.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:



128
129
130
 
# File 'lib/googleauth/id_tokens.rb', line 128

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:



118
119
120
 
# File 'lib/googleauth/id_tokens.rb', line 118

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.

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

    The expected issuer. 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.



204
205
206
207
208
209
210
211
212
213
 
# File 'lib/googleauth/id_tokens.rb', line 204

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.

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

    The expected issuer. 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.



167
168
169
170
171
172
173
174
175
176
 
# File 'lib/googleauth/id_tokens.rb', line 167

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