standard_id-google 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 459021f16aaa8a5fa33bfcf4e1cbf310d9fe2873a8e899db7934325f605869d8
-  data.tar.gz: 929ccecf7bf0e0e1dac6488582d2996c065fb089a75d59fbaae3bb8e79a3a0e1
+  metadata.gz: 40c4313fc9b3b04605a0a36353aedfbec7cfe109f1fdd3471455c28a2c908fc8
+  data.tar.gz: 21cf43e45c1f071ad0aec27c322c42e6ff719494da7941ee7f24b9f6a80d8cae
 SHA512:
-  metadata.gz: d8e1379e1de46a1cd29ae97a5e44640132cfa4d7d4756249ff6b3ac67df7a3a1562c59cb72227d201d9d443124579f95028bd1326c9a88de05a289ddb5519cd8
-  data.tar.gz: 8229c09170a9f4b8a76d02fc4b262d0d1d63516a9db56597beb1a3e724713ee496e54cedf60ae1ce5859c6683d047cfe67153ed0a7fcbf9d12f584fc213b56c4
+  metadata.gz: 7630091992ad0beaf567eee9e89acdcdf73625b85119a0e5ace6e209b4301f974dfe69d4efa3b679e7db7affcb93bf7028940c4f21c51e526cad8c87a58b618c
+  data.tar.gz: 29a6a81e3224960ec686fd3e700a49ea1868e4ea19643ec5e1cfa3986c4c1b80f5e407bcdedd2bdbe8839b723f0ab5e49700fbbfb173e8d157777417bb355c1f

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-06
+
+### Added
+
+- **Pin sign-in to Google Workspace domains: `social.google_hosted_domains`.**
+  An array of domains (default empty: nothing changes). While set, every
+  Google login, on the web code flow and the native `id_token` flow alike,
+  must present a verified ID token whose `hd` claim equals one of them
+  (case-insensitive, exact: no subdomains), with `email_verified` true and an
+  email whose domain is that `hd`. Anything else, including consumer gmail
+  (which has no `hd`), is refused with `StandardId::InvalidRequestError`
+  before any account is touched. In the web flow the ID token is required and
+  decides identity; the access-token-only sign-in is refused while pinned
+  (it has no ID token to pin on). With exactly one domain, `hd` is also sent
+  as the account-chooser hint (a caller-supplied `hd` still wins).
+  **Security note:** pinning is enforced server-side on the verified ID
+  token; the `hd` URL parameter is only a hint and proves nothing.
+- **`trusted_for_linking?` is true while pinned** (standard_id >= 0.46), so a
+  Workspace login may link to the organisation's existing account for the same
+  address under `link_strategy: :strict`. Unpinned it stays false.
+- **`StandardId::Google.staff_policy`** (standard_id >= 0.45): a
+  `login_method_policy` that lets staff in only via Google with a pinned
+  domain, mirroring `StandardId::VoidWhichBinds.staff_policy` (`staff_predicate:`,
+  `fallback:`, `social.google_require_for_staff`, `social.google_staff_predicate`).
+  `StandardId::Google.any_of(*policies)` combines it with another staff policy.
+- `verify_id_token` now also returns the `hd` claim.
+
 ## [0.6.0] - 2026-10-02
 
 Pairs with **standard_id 0.44.0** (security fix L1-01), which matches returning

data/README.md

@@ -52,6 +52,59 @@ end
 
 With those values in place, StandardId routes such as `/auth/callback/google` continue to function using this provider gem.
 
+### Pin sign-in to a Google Workspace domain
+
+To make Google the organisation's own identity provider, pin it to the
+Workspace domain(s) your admins control:
+
+```ruby
+StandardId.configure do |config|
+  config.social.google_hosted_domains = ["example.com"]
+end
+```
+
+With the default (empty), nothing changes. While set, every Google login (web
+and native `id_token`) is refused unless the verified ID token has an `hd`
+claim exactly matching one of the domains (case-insensitive; no subdomains),
+`email_verified` is true, and the email's domain equals `hd`. Consumer Google
+accounts have no `hd`, so they are refused. The refusal is a
+`StandardId::InvalidRequestError` raised before any account is created or
+linked. While pinned the web flow requires the ID token and takes identity from
+it, and access-token-only sign-in is refused. With exactly one domain, `hd` is
+also sent as the account-chooser hint (pass your own `hd:` to override).
+
+**Security:** pinning is enforced server-side on the verified ID token, never on
+the `hd` URL parameter, which a user can edit away. Only trust it if the
+domains' Workspace admins are the people who may create addresses on them.
+
+**Linking.** While pinned, `trusted_for_linking?` is `true` (standard_id 0.46),
+so under `link_strategy: :strict` a Workspace login may link to an existing
+account with the same verified email. Core asks per provider class, not per
+login, which is safe here because core calls it only for a login whose
+`get_user_info` has just passed the pin; unpinned it is `false`, as for any
+public IdP.
+
+**Staff policy.** To require staff to use it (standard_id 0.45+):
+
+```ruby
+StandardId.configure do |config|
+  config.login_method_policy = StandardId::Google.staff_policy(
+    staff_predicate: ->(account) { account.staff? }
+  )
+end
+```
+
+Staff may sign in only with `auth_method: :social`, provider `google`, and only
+while `google_hosted_domains` is set; password, passwordless and remember-me
+(and refreshes of those) are refused, as in the void_which_binds policy.
+Non-staff are allowed everything, or go to `fallback:`. Without a predicate
+the policy raises (fails closed); `social.google_require_for_staff = false`
+switches it off. A host running both this and
+`StandardId::VoidWhichBinds.staff_policy` should combine them with
+`StandardId::Google.any_of(google_policy, void_which_binds_policy)`: staff are
+admitted by either method and refused otherwise (chaining with `fallback:`
+would lock staff out of the other method).
+
 ### ENV fallback
 
 On `standard_id` 0.42+, a field you never assign falls back to the ENV

data/lib/generators/standard_id/google/install/templates/initializer.rb.erb

@@ -28,4 +28,8 @@
 StandardId.configure do |config|
   config.social.google_client_id = ENV.fetch("GOOGLE_CLIENT_ID", nil)
   config.social.google_client_secret = ENV.fetch("GOOGLE_CLIENT_SECRET", nil)
+
+  # Optional: pin sign-in to your Google Workspace domain(s). Enforced on the
+  # verified ID token's `hd` claim (consumer gmail is refused); see the README.
+  # config.social.google_hosted_domains = ["example.com"]
 end

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

@@ -32,16 +32,48 @@ module StandardId
           "google"
         end
 
+        # The Google Workspace domains sign-in is pinned to
+        # (`social.google_hosted_domains`): lowercase, stripped, de-duplicated.
+        # Empty means the provider is not pinned and behaves as it always has.
+        def hosted_domains
+          raw = StandardId.config.google_hosted_domains
+          list = raw.is_a?(String) ? raw.split(/[\s,]+/) : Array(raw)
+          list.map { |domain| domain.to_s.strip.downcase }.reject(&:empty?).uniq
+        end
+
+        def pinned?
+          hosted_domains.any?
+        end
+
+        # True ONLY while sign-in is pinned to Workspace domains. Core calls
+        # this on the class, after get_user_info has returned for the very
+        # login being linked, so there is no per-login question to answer:
+        # while pinned, every login that gets that far presented a verified
+        # ID token whose `hd` is one of the configured domains and whose
+        # email is on that domain (see enforce_hosted_domain!), so the
+        # address is one the domain's Workspace admin provisioned. Unpinned,
+        # Google is a public IdP and must never be trusted for linking.
+        def trusted_for_linking?
+          pinned?
+        end
+
         def supported_authorization_params
           [:nonce, :login_hint, :prompt, :scope, :access_type, :hd, :response_mode, :include_granted_scopes]
         end
 
         def authorization_url(state:, redirect_uri:, **options)
+          # With exactly one pinned domain, `hd` is sent as Google's account
+          # chooser hint (a caller-supplied `hd` still wins). It is only a
+          # hint: pinning is enforced on the verified ID token, never on it.
+          defaults = AUTHORIZATION_PARAM_DEFAULTS
+          domains = hosted_domains
+          defaults = defaults.merge(hd: domains.first) if domains.one?
+
           build_authorization_url(
             endpoint: AUTH_ENDPOINT,
             client_id: credentials[:client_id],
             redirect_uri:, state:, options:,
-            defaults: AUTHORIZATION_PARAM_DEFAULTS
+            defaults: defaults
           )
         end
 
@@ -52,6 +84,13 @@ module StandardId
               tokens: { id_token: id_token }
             )
           elsif access_token.present?
+            # An access token carries no ID token, so there is no verified
+            # `hd` claim to pin on: refused rather than trusted.
+            if pinned?
+              raise StandardId::InvalidRequestError,
+                    "Google access-token sign-in is not available while google_hosted_domains is set"
+            end
+
             build_response(
               fetch_user_info(access_token: access_token),
               tokens: { access_token: access_token }
@@ -77,7 +116,12 @@ module StandardId
         def config_schema
           {
             google_client_id: { type: :string, default: -> { legacy_env(:google_client_id) } },
-            google_client_secret: { type: :string, default: -> { legacy_env(:google_client_secret) }, required: true }
+            google_client_secret: { type: :string, default: -> { legacy_env(:google_client_secret) }, required: true },
+            # Workspace domains sign-in is pinned to; empty (default) = not pinned.
+            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 }
           }
         end
 
@@ -111,6 +155,18 @@ module StandardId
             access_token = parsed_token["access_token"]
             raise StandardId::InvalidRequestError, "Google token response is missing access_token" if access_token.blank?
 
+            if pinned?
+              # Pinned: the ID token is required and decides identity; the
+              # userinfo only adds profile fields.
+              if parsed_token["id_token"].blank?
+                raise StandardId::InvalidRequestError, "Google token response is missing id_token"
+              end
+
+              id_claims = verify_id_token(id_token: parsed_token["id_token"], nonce: nonce)
+              user_info = pinned_user_info(fetch_user_info(access_token: access_token), id_claims)
+              return build_response(user_info, tokens: extract_tokens(parsed_token))
+            end
+
             # Web flow with a server-generated nonce: check it on the ID token.
             if parsed_token["id_token"].present? && nonce.present?
               verify_id_token(id_token: parsed_token["id_token"], nonce: nonce)
@@ -143,7 +199,10 @@ module StandardId
             # 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"],
@@ -173,6 +232,39 @@ module StandardId
 
         private
 
+        # 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
+        # must be verified, and its domain must equal `hd`. Messages never
+        # echo the claims.
+        def enforce_hosted_domain!(claims)
+          hd = claims["hd"]
+          hd = hd.is_a?(String) ? hd.strip.downcase : nil
+          unless hd.present? && hosted_domains.include?(hd)
+            raise StandardId::InvalidRequestError, "Google account is not in an allowed Workspace domain"
+          end
+
+          unless [true, "true"].include?(claims["email_verified"])
+            raise StandardId::InvalidRequestError, "Google account email is not verified"
+          end
+
+          email = claims["email"]
+          local, separator, domain = email.is_a?(String) ? email.strip.rpartition("@") : []
+          unless separator == "@" && local.present? && !local.include?("@") && domain.downcase == hd
+            raise StandardId::InvalidRequestError, "Google account email is not on its Workspace domain"
+          end
+        end
+
+        # Web flow, pinned: identity comes from the verified ID token. The
+        # userinfo must agree on the subject, and its profile fields are kept.
+        def pinned_user_info(userinfo, id_claims)
+          unless userinfo.is_a?(Hash) && userinfo["sub"].to_s == id_claims["sub"].to_s && id_claims["sub"].present?
+            raise StandardId::InvalidRequestError, "Google user info does not match the ID token"
+          end
+
+          userinfo.merge(id_claims.slice("sub", "email", "email_verified", "hd"))
+        end
+
         # The client ID every flow needs, and the secret only the code
         # exchange needs (checked there). Raises when the provider is off.
         def credentials

data/lib/standard_id/google/staff_policy.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module StandardId
+  module Google
+    # A `login_method_policy` (standard_id >= 0.45) that refuses every way into
+    # a staff account except a Google sign-in pinned to the organisation's
+    # Workspace domain(s), so removing someone from the Workspace removes their
+    # way into the app:
+    #
+    #   StandardId.configure do |c|
+    #     c.social.google_hosted_domains = ["example.com"]
+    #     c.login_method_policy = StandardId::Google.staff_policy(
+    #       staff_predicate: ->(account) { account.staff? }
+    #     )
+    #   end
+    #
+    # standard_id consults it before any session or token exists, in every flow
+    # (web password, passwordless, remember-me, other social providers, the
+    # OAuth grants, and each refresh with the original sign-in's method).
+    # Remember-me re-authentication is therefore refused for staff, exactly as
+    # the void_which_binds policy does: staff sign in again with Google.
+    # Non-staff accounts pass through to `fallback`, if given (another policy
+    # with the same keyword contract), and are otherwise allowed.
+    #
+    # Enforced while `social.google_require_for_staff` is true (the default).
+    # `staff_predicate` falls back to `social.google_staff_predicate`; with
+    # neither, every decision fails closed (raises). A staff Google login is
+    # admitted only while `google_hosted_domains` is non-empty: an unpinned
+    # Google sign-in proves nothing about the organisation, so it is refused.
+    class StaffPolicy
+      MESSAGE = "Staff accounts must sign in with the organisation's Google Workspace account"
+
+      attr_reader :staff_predicate
+
+      def initialize(staff_predicate: nil, fallback: nil)
+        @staff_predicate = staff_predicate
+        @fallback = fallback
+      end
+
+      def call(account:, auth_method:, provider:, request: nil, flow: nil)
+        if require_for_staff? && staff?(account)
+          raise StandardId::LoginMethodDenied, MESSAGE unless pinned_google?(auth_method, provider)
+
+          return true
+        end
+        return true if @fallback.nil?
+
+        context = { account:, auth_method:, provider:, request:, flow: }
+        @fallback.call(**StandardId::Utils::CallableParameterFilter.filter(@fallback, context))
+      end
+
+      def staff?(account)
+        predicate = @staff_predicate || StandardId.config.google_staff_predicate
+        unless predicate.respond_to?(:call)
+          raise StandardId::ConfigurationError, "StandardId::Google.staff_policy needs a staff_predicate (or social.google_staff_predicate)"
+        end
+
+        account.present? && predicate.call(account) ? true : false
+      end
+
+      private
+
+      def require_for_staff?
+        StandardId.config.google_require_for_staff == true
+      end
+
+      def pinned_google?(auth_method, provider)
+        auth_method&.to_sym == :social &&
+          provider.to_s == StandardId::Providers::Google.provider_name &&
+          StandardId::Providers::Google.pinned?
+      end
+    end
+
+    # Combines login_method_policies for a host that runs more than one staff
+    # policy (for example this one and StandardId::VoidWhichBinds.staff_policy).
+    # Each of those admits a staff account by ITS method and refuses the rest,
+    # so chaining them with `fallback:` would lock staff out of the other's
+    # method. any_of admits when ANY policy allows, and refuses (with the first
+    # refusal's message) only when all do. Non-staff pass every such policy.
+    # A policy that raises anything but LoginMethodDenied (a missing predicate,
+    # a bug) propagates: the request fails closed.
+    class AnyOfPolicy
+      def initialize(policies)
+        @policies = policies
+        raise ArgumentError, "any_of needs at least one policy" if @policies.empty?
+      end
+
+      def call(**context)
+        denial = nil
+        @policies.each do |policy|
+          allowed = policy.call(**StandardId::Utils::CallableParameterFilter.filter(policy, context))
+          return true if allowed
+          denial ||= StandardId::LoginMethodDenied.new
+        rescue StandardId::LoginMethodDenied => e
+          denial ||= e
+        end
+        raise denial
+      end
+    end
+
+    def self.staff_policy(staff_predicate: nil, fallback: nil)
+      StaffPolicy.new(staff_predicate: staff_predicate, fallback: fallback)
+    end
+
+    def self.any_of(*policies)
+      AnyOfPolicy.new(policies.flatten)
+    end
+  end
+end

data/lib/standard_id/google/version.rb

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

data/lib/standard_id/google.rb

@@ -3,6 +3,7 @@ require "active_support/core_ext/hash/indifferent_access"
 require "standard_id"
 require "standard_id/google/version"
 require "standard_id/google/providers/google"
+require "standard_id/google/staff_policy"
 
 # Registers the provider from a Railtie's after_initialize (a no-op outside
 # Rails). Its config fields are declared earlier, before config/initializers,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id-google
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -53,6 +53,7 @@ files:
 - lib/generators/standard_id/google/install/templates/initializer.rb.erb
 - lib/standard_id/google.rb
 - lib/standard_id/google/providers/google.rb
+- lib/standard_id/google/staff_policy.rb
 - lib/standard_id/google/version.rb
 homepage: https://github.com/rarebit-one/standard_id_google
 licenses: