VENI-AI

English

Tiếng Việt

English

Tiếng Việt

Appearance

Feature Specification: Identity & SSO ​

1. Overview & Vision ​

Identity & SSO is the heartbeat of the VENI-AI platform. It provides a unified login experience, manages user sessions across micro-frontends, and handles the complexity of external identity providers, ensuring one secure session for the entire platform.

2. Personas & Stakeholders ​

PersonaGoal
End UserSeamless access to all authorized apps with one login.
Org AdminEnforce corporate SSO and manage member access.
System AdminConfigure global identity providers and security policies.

3. User Stories ​

  • As a member, I want to log in via Google so I don't have to remember another password.
  • As an admin, I want to revoke a user's session instantly when they leave the company.

4. Functional Requirements (FR) ​

  • REQ-SSO-001: Support for multi-provider OAuth2/OIDC (Google, Keycloak, external enterprise Keycloak).
  • REQ-SSO-002: Local authentication fallback (Email/Password).
  • REQ-SSO-003: Secure platform-wide RS256 JWT issuance.
  • REQ-SSO-004: Token exchange mechanism for service-scoped JWTs.
  • REQ-SSO-005: Email-first login — resolves SSO provider by email domain before presenting credentials.
  • REQ-SSO-006: Per-organization SSO — org admins can connect their own Keycloak instance as an identity provider.
  • REQ-SSO-007: BFF pattern — tokens stored in HttpOnly cookies; no access tokens exposed to the browser JS context.

5. Non-Functional Requirements (NFR) ​

  • Latency: Local authentication validation < 50ms.
  • Security: Mandatory PKCE for all public client flows.
  • Reliability: 99.99% availability for the JWKS endpoint.

6. Business Logic & Rules ​

  • Email-First Login: POST /api/auth/resolve-provider checks the email domain against organizations.domain; if a match has an idpProviderId, SSO is triggered automatically.
  • Domain Matching: Automatic organization linkage based on verified email domains.
  • Session Lifespan: Access tokens short-lived (1 hour); Refresh tokens long-lived (7 days), stored in HttpOnly cookies.
  • BFF Cookie Pattern: The Shell API acts as a Backend-for-Frontend; all tokens are stored in HttpOnly, SameSite=Lax cookies — no token is ever in localStorage or accessible to JavaScript.
  • Revocation: Blacklisting token signatures in Redis upon logout.
  • Status Control: Only users with status ACTIVE can authenticate. Individuals with SUSPENDED status are blocked at the gateway level.
  • Enterprise SSO Bootstrap: Platform admin configures per-org external Keycloak via Admin → Organizations → SSO & Identity, so the org admin doesn't need to log in before SSO is active.

7. User Interface (UI/UX) ​

  • Centralized Login Page with responsive social auth buttons.
  • "Identity Switcher" for users belonging to multiple organizations.
  • Loading states for OIDC redirects and token exchange handshakes.

8. Information Architecture ​

  • Part of the Shell "Identity Hub".
  • Exposed via the Shell top-bar user menu.

9. Data Model & Persistence ​

  • Tables: identity_providers, oauth_accounts, user_credentials.
  • Cache: Redis for session metadata and token blacklists.

10. API & Service Layer ​

  • GET /api/auth/providers — list enabled OAuth providers
  • GET /api/auth/login?provider=<id> — get authorization URL
  • GET /api/auth/callback — OAuth callback, sets HttpOnly cookies
  • POST /api/auth/resolve-provider — email-first: resolve SSO by domain
  • POST /api/auth/exchange — exchange Shell JWT for service-scoped JWT
  • POST /api/auth/refresh — rotate access token via refresh cookie
  • POST /api/auth/logout — blacklist token + return IdP logout URL
  • GET /api/.well-known/jwks.json — public RS256 JWKS for satellite verification
  • PUT /api/auth/me/organization — org admin configures SSO (idpConfig)

11. Integration Patterns ​

  • BroadcastChannel: Used to sync JWTs from the Shell Host to dynamic MFEs.
  • Connect Protocol: gRPC-compatible exchange for S2S security.

12. Security & Permissions ​

  • RSA Handshake: Public keys exposed via JWKS for distributed verification.
  • Isolation: JWTs include organizationId claims for mandatory database filtering.

13. Error Handling & Resilience ​

  • Graceful error pages for "Provider Unavailable".
  • Standardized 401 Unauthorized responses with diagnostic codes.

14. Performance & Scalability ​

  • JWKS public keys are cached globally across all satellite modules.
  • Stateless JWT verification avoids database lookups on every request.

15. Globalization & i18n ​

  • Support for localized login errors (EN/VI).
  • RTL support for identity widgets (planned).

16. Accessibility (a11y) ​

  • WCAG 2.2 compliant login forms (ARIA labels, keyboard focus).
  • Support for screen readers during the OAuth redirect sequence.

17. Observability & Analytics ​

  • Tracking of "Failed Login Attempts" for security auditing.
  • Analytics on "Provider Popularity" (Google vs. Local).

18. Testing & Quality ​

  • Mock OIDC server for automated integration tests.
  • E2E testing of the Token Exchange flow across MFEs.

19. Constraints & Assumptions ​

  • Requires a stable connection to external IdPs for social login.
  • Assumes satellite modules implement standard JWT verification.

20. Future Enhancements ​

  • Biometric (WebAuthn/Passkeys) support.
  • Adaptive MFA based on user location or risk score.

© 2025-2026 VENIZIA AI