googleauth - Module Google::Auth::IDTokens (v1.12.0)

Reference documentation and code samples for the googleauth module Google::Auth::IDTokens.

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"

Methods

.iap_key_source

def self.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

.oidc_key_source

def self.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

.verify_iap

def self.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.

.verify_oidc

def self.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.

Constants

OIDC_ISSUERS

value: ["accounts.google.com", "https://accounts.google.com"].freeze
A list of issuers expected for Google OIDC-issued tokens.

IAP_ISSUERS

value: ["https://cloud.google.com/iap"].freeze
A list of issuers expected for Google IAP-issued tokens.

OAUTH2_V3_CERTS_URL

value: "https://www.googleapis.com/oauth2/v3/certs";
The URL for Google OAuth2 V3 public certs

IAP_JWK_URL

value: "https://www.gstatic.com/iap/verify/public_key-jwk";
The URL for Google IAP public keys