Product Requirements Document (PRD): SAMLify Direct

1. Executive Summary

SAMLify Direct is a self-service Single Sign-On (SSO) configuration portal designed to eliminate the friction between enterprise IT administrators and B2B SaaS providers. By automating metadata exchange, providing guided workflows for major Identity Providers (IdPs), and offering a real-time "Side-Stream" sandbox for login validation, the platform reduces SSO deployment time from weeks to minutes.

2. Problem Statement

Setting up SSO (SAML 2.0/OIDC) is traditionally a manual, error-prone process. IT admins often struggle with mismatched entity IDs, incorrect attribute mappings, and expired certificates. This results in high-volume support tickets for SaaS companies and delayed "time-to-value" for enterprise customers. Current solutions lack a safe, non-production environment to test assertions before going live.

3. Goals & Success Metrics

• Reduce Support Overhead: Decrease SSO-related support tickets by 60% within the first six months.
• Time-to-Live: Reduce the average time for a customer to complete SSO setup from 5 business days to < 30 minutes.
• Configuration Accuracy: Achieve a 95% first-time success rate for "Test Login" validations.
• User Satisfaction: Achieve a System Usability Scale (SUS) score of 80+ from IT administrators.

4. User Personas

• Enterprise IT Admin (Ian): Responsible for connecting the company's Okta/Azure AD to third-party apps. He values clear documentation and instant error feedback.
• SaaS Customer Success Engineer (Sarah): Manages the onboarding of large accounts. She needs to see where a customer is stuck in the configuration wizard.
• Security Architect (Sam): Approves the integration. He cares about encryption standards, XXE prevention, and certificate rotation policies.

5. User Stories

• As an IT Admin, I want to upload my IdP metadata XML so that the system automatically populates SSO URLs and certificates.
• As an IT Admin, I want a guided wizard for Azure AD so that I don't have to search for proprietary Microsoft Graph settings manually.
• As an IT Admin, I want to perform a test login in a sandbox so that I can see exactly which claims (email, groups) are being sent before enabling it for all users.
• As a Security Architect, I want all sensitive keys to be encrypted at rest so that our identity backbone remains secure.

6. Functional Requirements

6.1 Configuration Wizard

• Dynamic Step-by-Step UI: A schema-driven wizard that branches based on the selected protocol (SAML 2.0 vs. OIDC) and IdP (Okta, Azure, Google).
• Metadata Parser: Automated ingestion of IdP XML metadata using streaming logic to handle large enterprise files.
• SP Metadata Generator: Automated generation of Service Provider metadata (XML/URL) for the admin to copy into their IdP.

6.2 Validation & Diagnostics

• The Sandbox: A dedicated callback URL (/auth/sso/sandbox-callback) that intercepts assertions without creating real user sessions.
• Assertion Inspector: A real-time UI that displays decoded SAML/OIDC claims, signature status, and timing (clock skew) diagnostics.
• Attribute Mapping Validator: Visual comparison of "Expected" vs "Received" user attributes.

6.3 Security Features

• Automated Certificate Monitoring: Alerts for certificates nearing expiration.
• Hardened Parsing: Mandatory XXE and XSW (Signature Wrapping) protection on all XML inputs.

7. Technical Requirements

7.1 Tech Stack (2026 Baseline)

• Frontend: React 19.2.3 (using React Compiler), Tailwind CSS 4.1.18 (Oxide Engine), Headless UI 2.x.
• Backend: NestJS 11.1.12 running on Node.js 24 LTS.
• Language: TypeScript 6.0.2 (utilizing native type-stripping).
• Database: PostgreSQL 18 with AES-256-GCM application-level encryption.
• Authentication: Clerk (Internal portal access) + openid-client / @node-saml/node-saml (SSO Logic).

7.2 Core SSO Libraries

• SAML: samlify (v2.10.0+) for high-level API; @node-saml/node-saml for core validation.
• OIDC: openid-client (v6.x) for FAPI 2.0 and DPoP support.
• XML Processing: fast-xml-parser with worker_threads for non-blocking ingestion.

8. Data Model

8.1 SSOConnection

• connectionId: UUID (Primary Key)
• protocol: Enum (SAML, OIDC)
• idpMetadata: Text (Stored as raw XML/JSON)
• encryptedSecrets: Bytea (Envelope-encrypted ClientSecret/PrivateKeys)
• status: Enum (Draft, Active, Testing)

8.2 ValidationLog

• logId: UUID
• connectionId: FK to SSOConnection
• rawAssertion: Bytea (Encrypted at rest)
• decodedClaims: JSONB
• isSuccess: Boolean
• errorDetails: Text

9. API Specification

9.1 Ingest Metadata

• Endpoint: POST /api/v1/sso/ingest-metadata
• Request: FormData containing XML file or URL.
• Response: 200 OK with parsed EntityID, SSO URLs, and Certificate Fingerprints.

9.2 Sandbox Callback

• Endpoint: POST /api/v1/sso/sandbox-callback
• Action: Decodes assertion -> Emits via WebSocket (Socket.io) to Frontend -> Masks PII -> Returns diagnostic view.

10. UI/UX Requirements

• Accessibility: Full WCAG 2.2 compliance for high-density IT admin tables.
• Visual Design: Tailwind 4.1 CSS-first variables for "Dark Mode" by default.
• Component Patterns:
  • The "Timeline" View: Visual flow of the SAML handshake (SP -> IdP -> User -> SP).
  • Code Diff Block: Highlighting mismatches in attribute keys (e.g., email vs http://schemas.../emailaddress).

11. Non-Functional Requirements

• Performance: Metadata parsing < 200ms using Worker Threads; UI state transitions < 50ms.
• Security:
  • No persistent storage of unmasked assertions.
  • Absolute XPath selection to prevent XSW attacks.
  • AES-256-GCM encryption for all bytea columns.
• Availability: 99.9% uptime (SSO configuration is mission-critical).

12. Out of Scope

• Identity Proxying: This app configures SSO; it does not act as a login gateway for production traffic.
• Active Directory Sync: SCIM provisioning is a "nice-to-have" and excluded from Phase 1.
• User Management: Creating/Deleting users in the destination app.

13. Risks & Mitigations

• Risk: XML Signature Wrapping (XSW) attacks during testing.
  • Mitigation: Use samlify v2.10+ with mandatory XSD schema validation before signature checking.
• Risk: Sensitive keys leaking in logs.
  • Mitigation: Implement a NestJS Interceptor to scrub "Secret" and "Assertion" keys from all logging streams.

14. Implementation Tasks

Phase 1: Project Foundations

• [ ] Initialize NestJS 11.1.12 with Node 24 LTS
• [ ] Initialize React 19.2.3 with Tailwind 4.1 (Oxide)
• [ ] Configure TypeScript 6.0.2 with native type-stripping support
• [ ] Setup PostgreSQL 18 with pg-crypto extensions
• [ ] Implement Application-Level Envelope Encryption (AES-256-GCM) utility using Web Crypto API

Phase 2: SSO Engine & Parsing

• [ ] Implement Streaming XML Parser using fast-xml-parser and Worker Threads
• [ ] Build SAML Metadata extraction service (EntityID, Binding URLs, Certs)
• [ ] Build OIDC Discovery service using openid-client
• [ ] Implement XXE Protection middleware for all XML ingestion points
• [ ] Create SP Metadata generator for SAML 2.0

Phase 3: The Configuration Wizard

• [ ] Design declarative state machine for wizard logic (Zustand + useReducer)
• [ ] Build "IdP Selector" component using Headless UI 2.x Radio Groups
• [ ] Implement metadata upload/drag-and-drop zone
• [ ] Create Attribute Mapping UI with drag-and-drop field matching
• [ ] Integrate Zod for real-time validation of configuration fields

Phase 4: Sandbox & Diagnostics

• [ ] Create Sandbox Callback Route (/sandbox-callback)
• [ ] Implement Socket.io Gateway for real-time assertion streaming
• [ ] Build "Assertion Inspector" component with react-syntax-highlighter
• [ ] Create "Diagnostic Engine" to detect clock skew and signature mismatches
• [ ] Implement PII Scrubber for sandbox data display

Phase 5: Hardening & Launch

• [ ] Perform security audit for XSW (Signature Wrapping) vulnerabilities
• [ ] Implement TLS 1.3 strict transport security
• [ ] Build "Review & Export" step with PDF documentation generator
• [ ] Set up automated certificate expiration alerts (Cron jobs)
• [ ] Final WCAG 2.2 accessibility pass on wizard components