0003 — Authentication: Clerk + Apple/Google social login, no Entra for end users

Status: Accepted (Android native Google Sign-In path requires verification before Phase 4)

Date: 2026-06-17

ADO work item: AB#3073

Deciders: Kristopher Turner (platform owner)

---

Context

Heritage Community Hub requires authentication for adult community members across web and mobile surfaces, and parent-managed credentials for children. The platform is a closed community — all accounts require minister/admin approval.

Constraints locked before this ADR:

• End-user auth: Apple Sign-In + Google Sign-In. No Microsoft Entra / Azure AD B2C for end users.
• Entra is infrastructure-only (operators, CI/CD, managed identities, Key Vault).
• The platform maintains its own Users record keyed to the provider sub claim.
• Children have no email address and no social login — parent-managed username + PIN/password.
• Sign in with Apple requires an Apple Developer account ($99/yr, needed for App Store regardless).
• Mobile is React Native + Expo (ADR 0002) — auth must work via native builds, not Expo Go or browser-based OAuth redirects.

The open question was: which auth provider service — Supabase Auth, Clerk, Auth.js, or roll-your-own OIDC?

Decision

We will use Clerk as the authentication provider for adult end users (Apple Sign-In + Google Sign-In), because Clerk's Expo SDK ships a native Sign in with Apple implementation (expo-apple-authentication) that avoids browser redirects — the architecturally correct path for a React Native + Expo app. Children's parent-managed credentials are stored directly in the platform's own Users table — the PIN/password hashed with Argon2id and verified server-side — and are not routed through Clerk.

Research basis (Phase-0, verified 2026-06-17):

• Clerk's Expo SDK ships native Sign in with Apple (no browser redirect) — verified 3-0 against Clerk's official changelog (Nov 2025) and two API reference pages. Requires EAS Build or local prebuild; does not work in Expo Go.
• Supabase Auth native Apple/Google sign-in claim was refuted 1-2 (insufficient sourcing to confirm the native ID-token path is production-ready in Expo).

Alternatives considered

Option	Pros	Cons	Why not chosen
Clerk (chosen)	Native Expo Apple sign-in (verified); strong React + RN SDK; handles OIDC token exchange; manages user sessions	SaaS (not self-hostable); cost scales with MAU; closed-source	— chosen
Supabase Auth	Postgres-native; open-source; bundles with DB	Native Apple/Google sign-in in Expo not verified (refuted 1-2 in research); harder to decouple from Supabase stack	Native mobile auth path unconfirmed
Auth.js (NextAuth v5)	OSS; framework-agnostic; no vendor lock-in	Requires own session store and token management; no native Expo SDK	More implementation effort; no clear native Expo story
Azure AD B2C / Entra External ID	Familiar to Azure operators	Ruled out by locked decision — Entra is infrastructure-only	Hard constraint
Roll-your-own OIDC	Maximum control; no SaaS dependency	Significant implementation + maintenance burden; security-critical code	Not justified at current team size

Consequences

Positive

• Clerk handles OIDC token exchange, session management, and JWT issuance — less code to write and audit.
• Native Sign in with Apple on iOS satisfies the App Store requirement (Guideline 4.8) without browser redirects.
• Clerk's React SDK integrates cleanly with the web app (apps/web); the Expo SDK integrates with apps/mobile.
• Children's parent-managed credentials are kept entirely within the platform's own Users table — Clerk never touches child accounts, keeping the COPPA boundary clean.

Negative / trade-offs

• Clerk is a paid SaaS above the free tier (MAU-based pricing). Monitor usage and cost as the community grows.
• If the stack fork decision (ADR 0004) goes fully Supabase-native, Clerk becomes an external dependency separate from the DB layer. This is acceptable — Clerk is auth-only and can coexist with any database.
• Clerk is closed-source. Migration away would require re-implementing the OIDC token exchange and session layer.

Risks

• Android native Google Sign-In — whether Clerk's Expo SDK wraps @react-native-google-signin/google-signin natively was not confirmed in Phase-0 research. This must be verified before mobile scaffolding (Phase 4). If Clerk does not handle it natively, a separate @react-native-google-signin integration alongside Clerk is required.
• Clerk free tier limits — Clerk's free plan limits changed in late 2024/early 2025. Confirm current MAU ceiling before Phase 2 launch.

References

• Platform strategy — authentication section
• ADR 0002 — Mobile: React Native + Expo — native build requirement (coupled)
• ADR 0007 — Account & Family-Group identity — child accounts (parent-managed, not Clerk)
• Clerk changelog: Native Sign in with Apple for Expo (Nov 2025)
• Clerk docs: Expo — Sign in with Apple
• Microsoft Learn: ADO Pipelines free tier