Feature Decomposition: SSO Integration (Google, Microsoft, SAML)

Total Stories: 9 stories (1 investigation + 8 implementation)
Estimated Timeline: ~18 days (assuming 1 team)
Dependencies: Investigation story must complete first; Story 2 blocks Stories 3-5; Stories 6-7 are independent

---

🔍 Story 1: SSO Provider Research & Integration Options Investigation [Investigation]

Estimated Size: 2 days
Priority: MUST HAVE (blocks implementation decisions)

As a technical lead,
I want to research SSO libraries and providers for Elixir/Phoenix,
So that we can choose the right integration approach for Google, Microsoft, and SAML.

Acceptance Criteria (starters):

• Evaluate Ueberauth ecosystem (ueberauth_google, ueberauth_microsoft, ueberauth_identity)
• Research SAML libraries (samly, esaml) and their Phoenix compatibility
• Document OAuth 2.0 vs. SAML trade-offs for enterprise use
• Identify required configurations per provider (client IDs, redirect URIs, scopes)
• Assess compatibility with existing auth system (password auth preservation)
• Create decision document with recommended libraries and implementation approach
• Estimate data model changes needed (user identity linking, provider tracking)

Technical Notes:

• Output: Decision document with library recommendations
• Consider enterprise requirements (domain verification, admin controls)
• Investigate session management implications
• Review security best practices (PKCE, state validation)

INVEST Check:

• Independent: Research-only, no implementation
• Negotiable: Can adjust scope based on findings
• Valuable: Informs all subsequent stories
• Estimable: Timeboxed to 2 days
• Small: 2-day maximum
• Testable: Decision document is deliverable

---

Story 2: SSO Database Schema & User Identity Linking [Foundation]

Estimated Size: 2 days
Priority: MUST HAVE (blocks all SSO stories)
Dependency: Requires Story 1 (investigation complete)

As a user with multiple login methods,
I want my SSO identities linked to one account,
So that I can use any login method to access the same account.

Acceptance Criteria (starters):

• Create user_identities table (provider, provider_uid, user_id, metadata)
• Support multiple identities per user (email + Google + Microsoft + SAML)
• Migration preserves existing password-based users
• Unique constraint on (provider, provider_uid) prevents duplicates
• Cascade delete when user deleted
• Store provider metadata (OAuth tokens, refresh tokens, expiry)
• Context functions: link_identity, unlink_identity, find_by_identity

Technical Notes:

• Encrypted storage for OAuth refresh tokens
• Consider GDPR implications (token storage duration)
• Add indexes: (user_id), (provider, provider_uid)
• Support account linking flow (existing email + new SSO)

INVEST Check: All criteria met

---

Story 3: Google OAuth SSO Login [Core]

Estimated Size: 3 days
Priority: MUST HAVE
Dependency: Requires Story 2 (identity schema)

As a user,
I want to log in with my Google account,
So that I don’t need to remember another password.

Acceptance Criteria (starters):

• “Sign in with Google” button on login page
• OAuth flow redirects to Google, returns with user profile
• Creates new user if email not found (auto-registration)
• Links to existing user if email matches
• Stores Google identity in user_identities table
• Session created on successful OAuth callback
• Error handling: user cancels, invalid credentials, network failure
• Rate limiting on OAuth callbacks (prevent abuse)
• [Add more based on domain routing requirements]

Technical Notes:

• Use ueberauth_google library
• Configure Google Cloud Console (OAuth client ID, redirect URI)
• Handle multi-domain routing (callsanta.ai, smartvoxlabs.com)
• Store OAuth tokens for future API calls (optional)
• Consider profile picture sync

INVEST Check: All criteria met

---

Story 4: Microsoft OAuth SSO Login [Core]

Estimated Size: 3 days
Priority: MUST HAVE
Dependency: Requires Story 2 (identity schema)

As a enterprise user,
I want to log in with my Microsoft/Azure AD account,
So that I can use my company credentials.

Acceptance Criteria (starters):

• “Sign in with Microsoft” button on login page
• OAuth flow redirects to Microsoft, returns with user profile
• Supports both personal (Outlook) and work (Azure AD) accounts
• Creates new user if email not found (auto-registration)
• Links to existing user if email matches
• Stores Microsoft identity in user_identities table
• Session created on successful OAuth callback
• Error handling: user cancels, tenant restrictions, network failure
• [Add more based on Azure AD tenant restrictions]

Technical Notes:

• Use ueberauth_microsoft library
• Configure Azure AD app registration (client ID, tenant ID, redirect URI)
• Handle Azure AD B2B guest accounts
• Support multi-tenant vs. single-tenant configuration
• Consider organization logo/branding support

INVEST Check: All criteria met

---

Story 5: SAML SSO Login for Enterprise [Core]

Estimated Size: 3 days
Priority: MUST HAVE (enterprise requirement)
Dependency: Requires Story 2 (identity schema)

As an enterprise customer,
I want to use my company’s SAML identity provider,
So that our team can authenticate with our corporate SSO.

Acceptance Criteria (starters):

• SAML service provider (SP) configuration endpoint
• Metadata XML upload for identity provider (IdP) configuration
• SAML assertion validation (signature, expiry, audience)
• Extracts user attributes from SAML assertion (email, name, groups)
• Creates/links user based on email attribute
• Stores SAML identity in user_identities table
• Admin UI to configure SAML providers (per organization/domain)
• Error handling: invalid assertion, expired session, attribute mapping failures
• [Add more based on multi-tenant SAML requirements]

Technical Notes:

• Use samly library (most maintained SAML for Elixir)
• Support multiple SAML IdPs (Okta, OneLogin, Azure AD SAML)
• SP metadata generation for customer IdP configuration
• Handle attribute mapping variations (email vs. emailAddress)
• Consider JIT (Just-In-Time) provisioning vs. pre-provisioning

INVEST Check: All criteria met
Note: Most complex story - consider 4 days if SAML expertise low

---

Story 6: SSO Account Linking & Unlinking UI [Core]

Estimated Size: 2 days
Priority: MUST HAVE
Dependencies: Stories 3-5 (SSO providers implemented)

As a user,
I want to manage my connected login methods in settings,
So that I can add or remove SSO providers.

Acceptance Criteria (starters):

• User settings page shows connected identities (Google, Microsoft, SAML, password)
• “Connect” button for each unlinked provider
• “Disconnect” button for each linked provider (if >1 method remains)
• Prevent removing last login method (must have ≥1)
• Confirmation modal before disconnecting
• Success/error messages for link/unlink actions
• Shows provider-specific details (email, linked date)
• [Add more based on security verification requirements]

Technical Notes:

• LiveView or traditional Phoenix controller approach
• Require password re-authentication before unlinking (security)
• Handle edge case: user has email but no password set (SSO-only)
• Show “primary” login method indicator

INVEST Check: All criteria met

---

Story 7: SSO Admin Dashboard for Enterprise [Enhancement]

Estimated Size: 3 days
Priority: SHOULD HAVE (enterprise visibility)
Dependencies: Stories 3-5 (SSO providers implemented)

As an enterprise admin,
I want to see which team members use SSO vs. password auth,
So that I can enforce security policies.

Acceptance Criteria (starters):

• Admin dashboard shows login method breakdown (Google, Microsoft, SAML, password)
• List users by login method (filterable)
• Show last login date and method used
• Export user login audit log to CSV
• Force SSO requirement for organization (disable password auth)
• Revoke user SSO identities (admin override)
• [Add more based on compliance audit requirements]

Technical Notes:

• Requires organization/team model (multi-tenant consideration)
• Paginate user lists (could be 1000+ users)
• Consider real-time updates (Phoenix PubSub)
• Track login events in audit log table

INVEST Check: All criteria met
Note: May require organization model if not present - add +1 day

---

Story 8: SSO Email Domain Verification for SAML [Enhancement]

Estimated Size: 2 days
Priority: SHOULD HAVE (enterprise security)
Dependencies: Story 5 (SAML implemented)

As an enterprise admin,
I want to restrict SSO login to verified email domains,
So that only company employees can access the platform.

Acceptance Criteria (starters):

• Admin configures allowed email domains (e.g., @acmecorp.com)
• SAML login rejects users with non-matching domains
• Domain verification via DNS TXT record (optional)
• Error message explains domain restriction
• Support multiple domains per organization
• Bypass domain check for super admins (support access)

Technical Notes:

• Store allowed_domains in organization settings
• DNS verification similar to email provider domain verification
• Consider wildcard subdomain support (@*.acmecorp.com)

INVEST Check: All criteria met
Note: Could be pushed to v2 if timeline pressure

---

Story 9: SSO Login Fallback & Error Recovery [Enhancement]

Estimated Size: 2 days
Priority: NICE TO HAVE (UX improvement)
Dependencies: Stories 3-5 (SSO providers implemented)

As a user experiencing SSO provider outage,
I want to fall back to password login,
So that I can still access my account.

Acceptance Criteria (starters):

• SSO timeout detection (>10 seconds) shows fallback options
• “Having trouble? Use password instead” link
• Clear error messages per provider failure type
• Retry button for transient failures
• Admin notification if provider down >5 minutes
• Status page link for ongoing outages

Technical Notes:

• Monitor OAuth callback failures (CloudWatch, Datadog)
• Implement circuit breaker for degraded providers
• Cache provider status (avoid repeated failed attempts)

INVEST Check: All criteria met
Note: Nice-to-have, defer if timeline tight

---

Implementation Strategy

Phase 1: Research & Foundation (Days 1-4)

• Story 1 (investigation) - 2 days
• Story 2 (database schema) after investigation - 2 days
• Enables: Clear implementation path + data model ready

Phase 2: Core SSO Providers (Days 5-10)

• Stories 3-5 can run in parallel (3 developers) OR sequentially
  • Story 3 (Google OAuth) - 3 days
  • Story 4 (Microsoft OAuth) - 3 days
  • Story 5 (SAML) - 3 days
• If parallel: 3 days with 3 devs
• If sequential: 9 days with 1 dev
• Enables: MVP shippable (all SSO methods working)

Phase 3: User Management (Days 11-12)

• Story 6 (account linking UI) - 2 days
• Enables: Complete user self-service

Phase 4: Enterprise Features (Days 13-18)

• Stories 7-9 can run in parallel (3 developers)
  • Story 7 (admin dashboard) - 3 days
  • Story 8 (domain verification) - 2 days
  • Story 9 (error recovery) - 2 days
• If parallel: 3 days with 3 devs
• If sequential: 7 days with 1 dev

MVP Definition: Stories 1-6 = Full SSO with user self-service (12 days)
Full Feature: All 9 stories (18 days solo, 9 days with 3 devs)

Parallelization Opportunities:

• Phase 2: 3 developers → 3 days instead of 9
• Phase 4: 3 developers → 3 days instead of 7
• Best case with 3 devs: 11 days total
• Realistic with 2 devs: 14 days total

---

Risk Mitigation

Technical Risks:

• SAML complexity high → Start with Story 1 investigation, consider external SAML expert
• OAuth provider API changes → Pin library versions, monitor deprecation notices
• Email collision across providers → Story 2 handles this with identity linking
• Session security vulnerabilities → Security review after Phase 2
• Multi-tenant SAML configuration → May require organization model refactor

Scope Risks:

• SAML Story 5 could expand to 4-5 days → Timebox, defer advanced SAML features
• Admin dashboard Story 7 needs org model → Add +1 day if not present
• Enterprise customers request custom attributes → Defer to v2, focus on email/name only
• Domain verification complexity → Story 8 could be 3 days if DNS automation added

Recommendation: Build Stories 1-6 first (MVP), validate with enterprise pilot customers, gather feedback on admin features, then prioritize Stories 7-9 based on customer needs.

---

Definition of Done

Each story is complete when:

• Code reviewed and merged
• Unit tests written and passing (context functions, OAuth callbacks)
• Integration tests cover happy path + error cases
• Manual QA completed with each provider (Google, Microsoft, SAML test IdP)
• Security review passed (Stories 3-5 require OAuth security audit)
• Documentation updated:
  • User guide: How to link SSO accounts
  • Admin guide: How to configure SAML
  • Developer guide: Environment variables, OAuth app setup
• Rollout plan documented (feature flag, gradual rollout)
• Monitoring/alerting configured (OAuth callback failures, SAML errors)

---

Additional Considerations

Security Requirements:

• CSRF protection on OAuth callbacks (Phoenix built-in)
• State parameter validation (prevent replay attacks)
• SAML assertion signature verification
• Rate limiting on login endpoints (prevent enumeration)
• Audit log for admin actions (SAML config changes)

Enterprise Customer Onboarding:

• Story 5 (SAML) requires customer to configure their IdP
• Provide setup guide with SP metadata XML
• Test accounts for QA before production rollout
• Support process for SAML troubleshooting (attribute mapping)

Multi-Domain Support:

• Current setup: callsanta.ai, smartvoxlabs.com, interviewgenius.io
• OAuth redirect URIs must be configured per domain
• SAML SP entity IDs must be unique per domain
• Consider domain-specific SSO provider restrictions