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 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 {Google::Auth::IDTokens::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"

Constants

IAP_ISSUERS

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

@return [Array<String>]

IAP_JWK_URL

The URL for Google IAP public keys

@return [String]

OAUTH2_V3_CERTS_URL

The URL for Google OAuth2 V3 public certs

@return [String]

OIDC_ISSUERS

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

@return [Array<String>]

Public Class Methods

forget_sources!() click to toggle source

Reset all convenience key sources. Used for testing. @private

# File lib/googleauth/id_tokens.rb, line 136
def forget_sources!
  @oidc_key_source = @iap_key_source = nil
  self
end
iap_key_source() click to toggle source

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

@return [Google::Auth::IDTokens::JwkHttpKeySource]

# File lib/googleauth/id_tokens.rb, line 128
def iap_key_source
  @iap_key_source ||= JwkHttpKeySource.new IAP_JWK_URL
end
oidc_key_source() click to toggle source

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

@return [Google::Auth::IDTokens::JwkHttpKeySource]

# 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) click to toggle source

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

@param token [String] The ID token to verify @param aud [String,Array<String>,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.

@param azp [String,Array<String>,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.

@param aud [String,Array<String>,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}.

@return [Hash] The decoded token payload. @raise [KeySourceError] if the key source failed to obtain public keys @raise [VerificationError] if the token verification failed.

Additional data may be available in the error subclass and message.
# File lib/googleauth/id_tokens.rb, line 205
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) click to toggle source

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

@param token [String] The ID token to verify @param aud [String,Array<String>,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.

@param azp [String,Array<String>,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.

@param aud [String,Array<String>,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}.

@return [Hash] The decoded token payload. @raise [KeySourceError] if the key source failed to obtain public keys @raise [VerificationError] if the token verification failed.

Additional data may be available in the error subclass and message.
# 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