##### Context
Legacy Gifts requires secure authentication and user management across three web applications (Creator, Beneficiary, Admin) with different access patterns and permission models.

- Key Requirements:
	- Support multiple user roles (Creator, Beneficiary, Support, Ops, Admin)
	- Enable seamless SSO across subdomains
	- Handle users with multiple roles simultaneously
	- Provide admin capabilities for user/role/group management
	- Maintain security for sensitive PII and relationship data
	- Meet compliance requirements (SOC 2, GDPR, HIPAA eligibility)
- Constraints:
	- Time-to-market is critical
	- Authentication is table-stakes, not a differentiator
	- Team should focus on core business features (gift scheduling, death verification, vendor integrations)
##### Decision
Adopt **Descope as our managed OIDC authentication provider** with the following approach:

- Authentication Strategy
	- Single Descope project serving all three applications
	- Embedded Descope web components in Marketing site (maintains brand consistency)
	- Post-login routing based on JWT claims (roles, custom attributes)
	- Shared cookie domain (`.legacygifts.com`) for seamless SSO
- Authorization Strategy
	- Descope provides authentication via OIDC/JWT tokens
	- Authorization enforcement remains in .NET applications (ASP.NET Core policies)
	- Roles defined in Descope: `creator`, `beneficiary`, `admin`, `ops`, `support`
	- Custom attributes for routing and business logic: `userType`, `subscriptionTier`, `linkedCreatorId`
- User Management Strategy (MVP)	
	- **Link out to Descope Console** for all user management operations
	- Optional: Display read-only user status in Admin app
	- No custom user management UI in MVP
	- Future: Build native UI using Descope Management API when team grows (~10+ users)

##### Options Considered

1. Descope (Recommended)
	- **Pros**: expedite development; free through 7,500 MAU; embeddable UI; modern auth (passwordless, social, MFA); SOC 2/GDPR/HIPAA included; 99.99% SLA
	- **Cons**: Vendor dependency; link-out UX; per-user pricing; newer vendor (2022)
	- **Cost**: $0 through 7,500 MAU; $0.05 per additional MAU
2.  Custom Build
	- **Pros**: Complete control; no per-user costs; no vendor dependency
	- **Cons**: development time; ongoing maintenance; security burden; delays MVP 2-3 months
	- **Cost**: $ initial + $ annual maintenance + $ compliance
3.  Auth0/Okta	
	- **Pros**: Enterprise-proven; comprehensive features; mature product
	- **Cons**: slightly shorter development time; complex setup; redirect-based flows
	- **Cost**: $ annually 
4.  Azure AD B2C
	- **Pros**: Microsoft ecosystem; strong compliance
	- **Cons**: Over-engineered for consumer use; steep learning curve; complex pricing
	- **Cost**: Comparable to Descope but more complex
5.  Firebase/Supabase	
	- **Pros**: Quick integration; low cost
	- **Cons**: Limited admin features; weaker compliance; insufficient for post-MVP
	- **Cost**: Low initially but feature gaps problematic
##### Rationale

- Why Managed Provider
	- **Speed**: faster path to MVP
	- **Team focus**: Team builds differentiating features, not auth infrastructure
	- **Security**: Enterprise-grade without expertise requirement or ongoing burden
	- **Cost**: Free through MVP; predictable scaling; cheaper than alternatives through significant scale
- Why Descope Specifically
	- **Embeddable UI**: Maintains seamless brand experience (users never leave legacygifts.com)
	- **Modern auth**: Passwordless/social login ideal for infrequent Beneficiaries
	- **Multi-role support**: Native support for complex role scenarios
	- **Developer velocity**: .NET SDK, clear docs, quick integration
	- **Migration path**: Management API enables future custom UI without re-architecture
	- **Cost**: Cheaper than Auth0/Okta through growth phase
	- **Compliance**: SOC 2, GDPR, HIPAA, ISO 27001 included
- Why Link-Out for MVP
	- Custom user management UI = 3-4 weeks development
	- Descope Console provides full features immediately
	- Acceptable UX trade-off for 1-3 admin users during MVP
	- Saves development time to accelerate core features
	- Can build native UI later using Management API (no re-architecture)
##### Implementation

- Integration Points
	1. Marketing site: Embed Descope flow component
	2. All apps: Configure OIDC middleware, validate JWTs
	3. Post-login: Backend reads claims, routes to appropriate app
	4. Admin app: Link-out buttons to Descope Console
	5. Authorization: ASP.NET Core policies check claims
- Configuration
	- Descope: Roles, custom attributes, redirect URLs, theme/branding
	- .NET: Shared cookie domain, OIDC middleware, Management API key in Key Vault
	- Database: `DescopeUserId` foreign keys in Creator/Beneficiary tables

---
**Decision Date**: January 26, 2026  
**Author**: Lead Architect