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"