Phase 4c: Soft SSO login nudge (access token hook)

Author: GregorShear

supabase/config.toml

@@ -45,6 +45,10 @@ jwt_expiry = 604800
 # Allow/disallow new user signups to your project.
 enable_signup = true
 
+[auth.hook.custom_access_token]
+enabled = true
+uri = "pg-functions://postgres/public/custom_access_token_hook"
+
 [auth.email]
 # Allow/disallow new user signups via email to your project.
 enable_signup = true

supabase/migrations/20260320120000_sso_access_token_hook.sql

@@ -0,0 +1,67 @@
+-- Add a customize_access_token hook that embeds SSO provider IDs into the JWT
+-- when a non-SSO user has grants on tenants with SSO configured.
+--
+-- The dashboard reads the `sso_required` claim on login/refresh and can show
+-- an interstitial prompting the user to re-authenticate via SSO.
+-- Only provider UUIDs are included — no tenant names — to avoid leaking
+-- which tenants the user has grants on.
+--
+-- Keyed on sso_provider_id IS NOT NULL (not enforce_sso) so users get nudged
+-- as soon as SSO is configured, giving them runway before hard enforcement.
+
+begin;
+
+create or replace function public.custom_access_token_hook(event jsonb)
+returns jsonb
+language plpgsql
+stable
+security definer
+set search_path to ''
+as $$
+declare
+  claims         jsonb;
+  target_user_id uuid;
+  provider_ids   jsonb;
+begin
+  target_user_id = (event->>'user_id')::uuid;
+  claims = event->'claims';
+
+  -- Find distinct SSO provider IDs for tenants that have SSO configured and
+  -- where this user has grants but lacks the matching SSO identity.
+  select jsonb_agg(distinct t.sso_provider_id)
+    into provider_ids
+    from public.user_grants ug
+    join public.tenants t on t.tenant ^@ ug.object_role
+    where ug.user_id = target_user_id
+      and t.sso_provider_id is not null
+      and not exists (
+        select 1 from auth.identities ai
+        where ai.user_id = target_user_id
+          and ai.provider = 'sso'
+          and ai.provider_id = t.sso_provider_id::text
+      );
+
+  if provider_ids is not null then
+    claims = jsonb_set(claims, '{sso_required}', provider_ids);
+  else
+    claims = claims - 'sso_required';
+  end if;
+
+  event = jsonb_set(event, '{claims}', claims);
+  return event;
+end;
+$$;
+
+-- The hook is invoked by GoTrue as the supabase_auth_admin role.
+grant usage on schema public to supabase_auth_admin;
+grant execute on function public.custom_access_token_hook(jsonb) to supabase_auth_admin;
+
+-- The function reads from these tables.
+grant select on public.user_grants to supabase_auth_admin;
+grant select on public.tenants to supabase_auth_admin;
+grant select on auth.identities to supabase_auth_admin;
+
+-- Revoke from anon/authenticated — this is not a user-callable function.
+revoke execute on function public.custom_access_token_hook(jsonb) from authenticated, anon;
+
+commit;

supabase/tests/sso_access_token_hook.test.sql

@@ -0,0 +1,127 @@
+-- Tests for the custom_access_token_hook that adds sso_required claim.
+create function tests.test_sso_access_token_hook()
+returns setof text as $$
+declare
+  provider_acme uuid = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+  provider_bigcorp uuid = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+  alice_id uuid = '11111111-1111-1111-1111-111111111111';
+  bob_id uuid = '22222222-2222-2222-2222-222222222222';
+  result jsonb;
+begin
+  -- Setup: test users.
+  insert into auth.users (id, email) values
+    (alice_id, 'alice@example.com'),
+    (bob_id, 'bob@example.com')
+  on conflict do nothing;
+
+  -- Setup: two SSO providers.
+  insert into auth.sso_providers (id) values (provider_acme), (provider_bigcorp)
+    on conflict do nothing;
+
+  -- Tenants: acmeCo and bigcorpCo have SSO configured, openCo does not.
+  delete from tenants;
+  insert into tenants (tenant, sso_provider_id) values
+    ('acmeCo/', provider_acme),
+    ('bigcorpCo/', provider_bigcorp),
+    ('openCo/', null);
+
+  -- Alice has grants on all three, SSO identity for acmeCo only.
+  delete from user_grants;
+  insert into user_grants (user_id, object_role, capability) values
+    (alice_id, 'acmeCo/', 'admin'),
+    (alice_id, 'bigcorpCo/', 'read'),
+    (alice_id, 'openCo/', 'admin');
+
+  delete from auth.identities where user_id = alice_id;
+  insert into auth.identities (user_id, provider, provider_id, identity_data) values
+    (alice_id, 'sso', provider_acme::text, '{}'::jsonb);
+
+  -- Alice should get sso_required with bigcorpCo's provider (she lacks that identity).
+  select public.custom_access_token_hook(jsonb_build_object(
+    'user_id', alice_id,
+    'claims', jsonb_build_object('sub', alice_id)
+  )) into result;
+
+  return next is(
+    result->'claims'->'sso_required',
+    jsonb_build_array(provider_bigcorp),
+    'Alice gets sso_required with bigcorpCo provider ID'
+  );
+
+  -- Bob has grants on acmeCo and bigcorpCo, no SSO identities at all.
+  insert into user_grants (user_id, object_role, capability) values
+    (bob_id, 'acmeCo/', 'read'),
+    (bob_id, 'bigcorpCo/', 'read'),
+    (bob_id, 'openCo/', 'read');
+
+  delete from auth.identities where user_id = bob_id;
+
+  select public.custom_access_token_hook(jsonb_build_object(
+    'user_id', bob_id,
+    'claims', jsonb_build_object('sub', bob_id)
+  )) into result;
+
+  -- Bob should get both provider IDs (order not guaranteed, so check containment).
+  return next ok(
+    result->'claims'->'sso_required' @> jsonb_build_array(provider_acme)
+      and result->'claims'->'sso_required' @> jsonb_build_array(provider_bigcorp),
+    'Bob gets sso_required with both provider IDs'
+  );
+  return next is(
+    jsonb_array_length(result->'claims'->'sso_required'),
+    2,
+    'Bob has exactly 2 provider IDs in sso_required'
+  );
+
+  -- Give Alice an SSO identity for bigcorpCo too — sso_required should disappear.
+  insert into auth.identities (user_id, provider, provider_id, identity_data) values
+    (alice_id, 'sso', provider_bigcorp::text, '{}'::jsonb);
+
+  select public.custom_access_token_hook(jsonb_build_object(
+    'user_id', alice_id,
+    'claims', jsonb_build_object('sub', alice_id)
+  )) into result;
+
+  return next ok(
+    result->'claims'->'sso_required' is null,
+    'Alice with both SSO identities has no sso_required claim'
+  );
+
+  -- Clean up the extra identity.
+  delete from auth.identities
+    where user_id = alice_id
+      and provider_id = provider_bigcorp::text;
+
+  -- User with only open-tenant grants: no sso_required.
+  delete from user_grants where user_id = bob_id;
+  insert into user_grants (user_id, object_role, capability) values
+    (bob_id, 'openCo/', 'read');
+
+  select public.custom_access_token_hook(jsonb_build_object(
+    'user_id', bob_id,
+    'claims', jsonb_build_object('sub', bob_id)
+  )) into result;
+
+  return next ok(
+    result->'claims'->'sso_required' is null,
+    'User with only open-tenant grants has no sso_required claim'
+  );
+
+  -- SSO user with matching identity on their own tenant: no nudge.
+  delete from user_grants where user_id = alice_id;
+  insert into user_grants (user_id, object_role, capability) values
+    (alice_id, 'acmeCo/', 'admin');
+
+  select public.custom_access_token_hook(jsonb_build_object(
+    'user_id', alice_id,
+    'claims', jsonb_build_object('sub', alice_id)
+  )) into result;
+
+  return next ok(
+    result->'claims'->'sso_required' is null,
+    'SSO user with matching identity on own tenant is not nudged'
+  );
+
+  return;
+end
+$$ language plpgsql;