standard_id-google 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40c4313fc9b3b04605a0a36353aedfbec7cfe109f1fdd3471455c28a2c908fc8
-  data.tar.gz: 21cf43e45c1f071ad0aec27c322c42e6ff719494da7941ee7f24b9f6a80d8cae
+  metadata.gz: 41656bb0ca1e58c41e45f5d1e293b9d6d172c83fa2aeb759be169c121ddb344d
+  data.tar.gz: fb852f913672f0ee5afd16927b5a4c5d36a4d6a46d81c39c17f89faed26edabb
 SHA512:
-  metadata.gz: 7630091992ad0beaf567eee9e89acdcdf73625b85119a0e5ace6e209b4301f974dfe69d4efa3b679e7db7affcb93bf7028940c4f21c51e526cad8c87a58b618c
-  data.tar.gz: 29a6a81e3224960ec686fd3e700a49ea1868e4ea19643ec5e1cfa3986c4c1b80f5e407bcdedd2bdbe8839b723f0ab5e49700fbbfb173e8d157777417bb355c1f
+  metadata.gz: 7d1182bfbb9b6fde3ffc787140920cef1c1fde07b4d3bf83ed9285101f061e66b3d7eb3793484b1e5e22aa932edf073412f957eb00371544146c9139876e413d
+  data.tar.gz: 5a60c09f63ca31495364b6d99904121e7424f3f82e49b1278f0e4640a82a41193971a2c7846f0a634d089092741d29f2db34f03697325460af1bb6c4706f673e

data/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-26
+
+### Changed
+
+- **`verify_id_token` now verifies Google ID tokens locally (default: `:jwks`).**
+  Signatures are checked against Google's JWKS at
+  `https://www.googleapis.com/oauth2/v3/certs`, using RS256 only. The JWKS
+  response is cached in-process (TTL 3600 s) with a kid-miss refresh subject to
+  a 60 s minimum interval, mirroring the sibling `standard_id-apple` provider.
+  The token stays within the process after the initial key fetch: no token
+  material is sent to Google.
+  Claims verified locally: algorithm (RS256 only — `alg:none` and `alg:HS256`
+  are rejected), expiry (with 60 s clock-skew leeway), issuer (`accounts.google.com`
+  or `https://accounts.google.com`), audience (configured client ID), nonce
+  (timing-safe), and `hd` when `google_hosted_domains` is set.
+- **`jwt` gem added as a runtime dependency** (`>= 2.7, < 4`). It was already a
+  transitive dependency via `standard_id-apple` in most installations.
+
+### Deprecated
+
+- **`config.google_id_token_verification = :tokeninfo`** (new opt-in).
+  The pre-0.8.0 behaviour of POSTing the raw ID token to Google's tokeninfo
+  endpoint is available for one release as an explicit opt-in. Set
+  `config.social.google_id_token_verification = :tokeninfo` to keep the old
+  path. **The `:tokeninfo` fallback will be removed in 0.9.0.**
+
+### Upgrade
+
+- No action required for apps that do not set `google_id_token_verification`.
+  The JWKS path is a drop-in replacement: the same claims are returned in the
+  same shape.
+- Apps running in network-restricted environments that block outbound HTTPS to
+  `googleapis.com` should either open that connection or set `:tokeninfo` while
+  they plan the migration.
+
 ## [0.7.0] - 2026-10-06
 
 ### Added

data/lib/standard_id/google/providers/google.rb

@@ -1,5 +1,7 @@
 require "json"
+require "jwt"
 require "net/http"
+require "openssl"
 
 module StandardId
   module Providers
@@ -12,12 +14,24 @@ module StandardId
       # developers.google.com/identity/protocols/oauth2). The legacy
       # www.googleapis.com/oauth2/v3/tokeninfo host is no longer used.
       TOKEN_INFO_ENDPOINT = "https://oauth2.googleapis.com/tokeninfo".freeze
+      # Google's JWKS endpoint for local ID token signature verification.
+      JWKS_URI = "https://www.googleapis.com/oauth2/v3/certs".freeze
       VALID_ISSUERS = ["accounts.google.com", "https://accounts.google.com"].freeze
       DEFAULT_SCOPE = "openid email profile".freeze
       AUTHORIZATION_PARAM_DEFAULTS = {
         scope: DEFAULT_SCOPE
       }.freeze
 
+      # Google's signing keys rotate rarely; an unknown `kid` forces an early
+      # refetch (see #fetch_jwk), so a long TTL costs nothing on rotation.
+      JWKS_CACHE_TTL = 3600
+      # Floor between forced refetches, so a stream of ID tokens carrying
+      # made-up `kid`s cannot turn this process into a request amplifier
+      # against Google.
+      JWKS_MIN_REFRESH_INTERVAL = 60
+      # Accepted clock drift for exp/iat, matching the sibling Apple provider.
+      CLOCK_SKEW_SECONDS = 60
+
       # Pre-0.5.0 install generators wired the fields to these variables.
       # Still read, with a deprecation warning, when the canonical variable
       # (GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET) is unset and the host never
@@ -27,6 +41,9 @@ module StandardId
         google_client_secret: "GOOGLE_OAUTH_CLIENT_SECRET"
       }.freeze
 
+      @jwks_mutex = Mutex.new
+      @jwks_cache = nil
+
       class << self
         def provider_name
           "google"
@@ -107,8 +124,8 @@ module StandardId
         # enabled provider shows the web sign-in button, and the web flow's
         # code exchange needs the secret — without it the user authenticates
         # with Google and only then does the callback fail. The native
-        # id_token and access_token flows verify through Google's tokeninfo
-        # endpoint and need only the client ID.
+        # id_token and access_token flows verify through Google's JWKS (or
+        # tokeninfo) and need only the client ID.
         #
         # ENV fallbacks (standard_id >= 0.42): GOOGLE_CLIENT_ID and
         # GOOGLE_CLIENT_SECRET; the pre-0.5.0 GOOGLE_OAUTH_* names are read as
@@ -121,7 +138,15 @@ module StandardId
             google_hosted_domains: { type: :any, default: -> { [] }, env: false },
             # StandardId::Google.staff_policy settings.
             google_require_for_staff: { type: :boolean, default: true },
-            google_staff_predicate: { type: :any, default: nil, env: false }
+            google_staff_predicate: { type: :any, default: nil, env: false },
+            # ID token verification mode:
+            #   :jwks (default) — verify the signature locally against Google's
+            #     JWKS at #{JWKS_URI}. More reliable (no network round-trip for
+            #     every auth) and keeps the token within the process.
+            #   :tokeninfo — POST the raw token to Google's tokeninfo endpoint
+            #     (legacy behaviour, pre-0.8.0). Kept for one release as an
+            #     explicit opt-in. Will be removed in 0.9.0.
+            google_id_token_verification: { type: :string, default: "jwks", env: false }
           }
         end
 
@@ -176,42 +201,27 @@ module StandardId
           end
         end
 
-        # Verifies through Google's tokeninfo endpoint, which checks the
-        # signature and expiry; the audience, issuer and nonce are checked
-        # here. Needs only the client ID.
+        # Verifies a Google ID token and returns its claims.
+        #
+        # Default mode (:jwks): verifies the signature locally against
+        # Google's JWKS, keeping the token within the process. Signature,
+        # algorithm (RS256 only), expiry, issuer and audience are all checked
+        # here; no network call is required after the keys are cached.
+        #
+        # Fallback mode (:tokeninfo): POSTs the raw token to Google's
+        # tokeninfo endpoint, which checks signature + expiry server-side;
+        # audience, issuer and nonce are checked here. Kept for one release as
+        # config.google_id_token_verification = :tokeninfo. Will be removed in
+        # 0.9.0.
         def verify_id_token(id_token:, nonce: nil)
           rescue_to_oauth_error do
             raise StandardId::InvalidRequestError, "Google id_token is missing" if id_token.blank?
 
-            response = HttpClient.post_form(TOKEN_INFO_ENDPOINT, id_token: id_token)
-            raise StandardId::InvalidRequestError, "Invalid Google ID token: invalid or expired" unless response.is_a?(Net::HTTPSuccess)
-
-            token_info = JSON.parse(response.body)
-
-            unless token_info["aud"].present? && token_info["aud"] == credentials[:client_id]
-              raise StandardId::InvalidRequestError, "Invalid Google ID token audience"
-            end
-
-            unless VALID_ISSUERS.include?(token_info["iss"])
-              raise StandardId::InvalidRequestError, "Invalid Google ID token issuer"
+            if tokeninfo_verification?
+              verify_id_token_via_tokeninfo(id_token: id_token, nonce: nonce)
+            else
+              verify_id_token_via_jwks(id_token: id_token, nonce: nonce)
             end
-
-            # Constant-time, and the error never echoes either value.
-            verify_nonce!(expected: nonce, actual: token_info["nonce"])
-
-            enforce_hosted_domain!(token_info) if pinned?
-
-            {
-              "hd" => token_info["hd"],
-              "sub" => token_info["sub"],
-              "email" => token_info["email"],
-              "email_verified" => token_info["email_verified"],
-              "name" => token_info["name"],
-              "given_name" => token_info["given_name"],
-              "family_name" => token_info["family_name"],
-              "picture" => token_info["picture"],
-              "locale" => token_info["locale"]
-            }.compact
           end
         end
 
@@ -230,8 +240,150 @@ module StandardId
           end
         end
 
+        # Drop the in-process JWKS cache (tests, or after a known rotation).
+        def reset_jwks_cache!
+          @jwks_mutex.synchronize { @jwks_cache = nil }
+        end
+
         private
 
+        # True when the host has opted into the :tokeninfo fallback.
+        def tokeninfo_verification?
+          StandardId.config.google_id_token_verification.to_s == "tokeninfo"
+        end
+
+        # Local JWKS-based verification. RS256 only. The token never leaves
+        # the process after the keys are cached.
+        def verify_id_token_via_jwks(id_token:, nonce: nil)
+          _unverified_payload, header = JWT.decode(id_token, nil, false)
+          kid = header["kid"]
+          raise StandardId::InvalidRequestError, "Invalid Google ID token: header has no kid" if kid.blank?
+
+          jwk = fetch_jwk(kid: kid)
+          creds = credentials
+
+          # RS256 is the only algorithm Google uses for ID tokens. Enforcing
+          # it here blocks alg:none and alg:HS256 attacks even if the JWKS
+          # call is somehow poisoned.
+          verified_payload, = JWT.decode(
+            id_token,
+            jwk.public_key,
+            true,
+            algorithms: ["RS256"],
+            verify_expiration: true,
+            leeway: CLOCK_SKEW_SECONDS
+          )
+
+          # Issuer and audience are checked manually for robustness across
+          # JWT gem minor versions and to keep error messages consistent.
+          unless VALID_ISSUERS.include?(verified_payload["iss"])
+            raise StandardId::InvalidRequestError, "Invalid Google ID token issuer"
+          end
+
+          # Support the multiple-client-id case: if the config carries an
+          # array, any member may match.
+          allowed = Array(creds[:client_id])
+          unless allowed.include?(verified_payload["aud"])
+            raise StandardId::InvalidRequestError, "Invalid Google ID token audience"
+          end
+
+          # Constant-time, and the error never echoes either value.
+          verify_nonce!(expected: nonce, actual: verified_payload["nonce"])
+
+          enforce_hosted_domain!(verified_payload) if pinned?
+
+          extract_id_token_claims(verified_payload)
+        rescue JWT::DecodeError => e
+          raise StandardId::InvalidRequestError, "Invalid Google ID token: #{e.message}"
+        end
+
+        # Legacy tokeninfo path. Kept as an explicit opt-in for one release.
+        # Deprecated: will be removed in 0.9.0.
+        def verify_id_token_via_tokeninfo(id_token:, nonce: nil)
+          response = HttpClient.post_form(TOKEN_INFO_ENDPOINT, id_token: id_token)
+          raise StandardId::InvalidRequestError, "Invalid Google ID token: invalid or expired" unless response.is_a?(Net::HTTPSuccess)
+
+          token_info = JSON.parse(response.body)
+
+          unless token_info["aud"].present? && token_info["aud"] == credentials[:client_id]
+            raise StandardId::InvalidRequestError, "Invalid Google ID token audience"
+          end
+
+          unless VALID_ISSUERS.include?(token_info["iss"])
+            raise StandardId::InvalidRequestError, "Invalid Google ID token issuer"
+          end
+
+          # Constant-time, and the error never echoes either value.
+          verify_nonce!(expected: nonce, actual: token_info["nonce"])
+
+          enforce_hosted_domain!(token_info) if pinned?
+
+          extract_id_token_claims(token_info)
+        end
+
+        # Pull the canonical set of ID token claims from a verified payload.
+        def extract_id_token_claims(claims)
+          {
+            "hd" => claims["hd"],
+            "sub" => claims["sub"],
+            "email" => claims["email"],
+            "email_verified" => claims["email_verified"],
+            "name" => claims["name"],
+            "given_name" => claims["given_name"],
+            "family_name" => claims["family_name"],
+            "picture" => claims["picture"],
+            "locale" => claims["locale"]
+          }.compact
+        end
+
+        # Look `kid` up in Google's JWKS, served from an in-process cache
+        # (JWKS_CACHE_TTL). An unknown `kid` refetches once — Google may have
+        # rotated — subject to JWKS_MIN_REFRESH_INTERVAL.
+        def fetch_jwk(kid:)
+          jwk_data = find_jwk(jwks_keys, kid) || find_jwk(jwks_keys(refresh: true), kid)
+          raise StandardId::InvalidRequestError, "Invalid Google ID token: signing key not found in Google's JWKS" unless jwk_data
+
+          JWT::JWK.import(jwk_data)
+        end
+
+        def find_jwk(keys, kid)
+          keys.find { |key| key["kid"] == kid }
+        end
+
+        def jwks_keys(refresh: false)
+          @jwks_mutex.synchronize do
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            cache = @jwks_cache
+
+            stale = cache.nil? || now - cache[:fetched_at] > JWKS_CACHE_TTL
+            forced = refresh && cache && now - cache[:fetched_at] >= JWKS_MIN_REFRESH_INTERVAL
+            if stale || forced
+              @jwks_cache = cache = { keys: download_jwks, fetched_at: now }
+            end
+
+            cache[:keys]
+          end
+        end
+
+        # Fetched through StandardId::HttpClient's connection setup, so the
+        # request gets its timeouts and its private/internal-address guard.
+        # HttpClient has no public plain GET (only get_with_bearer, which would
+        # send an empty Authorization header), hence the two private calls.
+        def download_jwks
+          rescue_to_oauth_error("Failed to fetch Google JWKS") do
+            uri, resolved_ip = HttpClient.send(:validate_url!, JWKS_URI)
+            response = HttpClient.send(:start_connection, uri, resolved_ip: resolved_ip) do |http|
+              http.request(Net::HTTP::Get.new(uri))
+            end
+            raise StandardId::OAuthError, "Failed to fetch Google JWKS: HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+            keys = JSON.parse(response.body)["keys"]
+            raise StandardId::OAuthError, "Failed to fetch Google JWKS: response has no keys" unless keys.is_a?(Array)
+
+            keys
+          end
+        end
+
         # Pins sign-in to the configured Workspace domains, on the claims of
         # a verified ID token: `hd` must be one of them (an exact,
         # case-insensitive match; consumer accounts have no `hd`), the email

data/lib/standard_id/google/version.rb

@@ -2,6 +2,6 @@
 
 module StandardId
   module Google
-    VERSION = "0.7.0"
+    VERSION = "0.8.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id-google
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -23,6 +23,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: standard_id
   requirement: !ruby/object:Gem::Requirement