US-106: SSO Login & Mapping

1. Story Title

Single Sign-On (SSO) federated login with user claim mapping

2. Context / Background

Extends initial credential-based signup to support enterprise tenants using external IdP (OIDC/SAML). Ensures consistent user creation and role assignment from federation claims.

3. User Persona

Primary: Priya – Tenant Admin (configures SSO) Secondary: Enterprise Employee (end user)

4. Problem Statement

Enterprise prospects require SSO; lack of federation blocks adoption and introduces manual account management overhead.

5. Desired Outcome

Tenant admin configures IdP metadata; users sign in via SSO and are provisioned (or matched) seamlessly with roles applied from configured claim mappings.

6. Business Value

Removes onboarding friction for larger accounts; reduces password-related support and improves security posture.

7. Scope (In / Out)

In: IdP metadata config (issuer, client ID/secret), OIDC login, claim mapping (email, name, optional role), auto-provision new user. Out: SAML protocol (phase 2), SCIM user sync, advanced role transformation rules.

8. Acceptance Criteria (BDD)

Scenario: Successful SSO login provisions user
  Given tenant has configured valid IdP metadata
  When an enterprise employee authenticates via IdP
  Then a user account is created (if not existing)
  And user is associated to tenant
  And a login success event is published

Scenario: Existing user matched
  Given a local user with matching email exists
  When SSO login occurs
  Then no duplicate user is created
  And lastLogin timestamp updates

Scenario: Claim mapping missing required email
  Given IdP response lacks email claim
  When login completes
  Then system returns mapping error
  And no user is provisioned

Scenario: Logout invalidates session
  Given user is logged in via SSO
  When user clicks logout
  Then session tokens become invalid

9. UX Notes / References

Login page includes "Sign in with Company SSO" button if enabled; admin settings page for IdP config (text fields + test connection).

10. Data / Domain Model Impact

Add SsoConfig (tenantId, issuer, clientId, secret, enabled); extend User for federation flags.

11. NFR Touchpoints

• Security: OIDC nonce/state validated; secrets stored encrypted.
• Performance: login round trip p95 < 800ms.
• Observability: events SSOLoginAttempt, SSOLoginSuccess, SSOLoginFailure.

12. Dependencies

US-101 signup baseline; Identity Service; IdP external integration.

13. Risks & Mitigations

Risk	Impact	Probability	Mitigation
Incorrect claim mapping	Misprovision roles	Medium	Validation + preview test tool
Token replay	Unauthorized access	Low	Validate nonce/state & expiration

14. Estimation Support

1. Config endpoints & storage
2. OIDC auth flow
3. Claim mapping logic
4. Provision/match + events

15. Analytics / Success Metrics

SSO adoption rate; failure reasons distribution; average login latency.

16. Rollout / Release Strategy

Pilot with one internal test IdP; enable flag by tenant.

17. Definition of Ready Checklist

• IdP fields finalized
• Claim mapping rules agreed
• Security review of flow

18. Definition of Done Checklist

• All scenarios tested
• Events visible in analytics
• Admin docs updated

19. Open Questions

1. Support role override vs additive merge?
2. Auto-disable passwords after SSO enable?

---

Version: 1.0