REC Verifiable Credentialing Platform System Design¶

Overview¶

This document outlines the system design for the REC Verifiable Credentialing Platform, with a specific focus on the Auth0 integration for identity and access management. The platform enables UK staffing companies and work-seeking individuals to securely create, issue, receive, and verify workforce credentials.

System Components¶

1. Frontend Application (React)¶

The frontend application is a React-based single-page application (SPA) that provides the user interface for:

User authentication and profile management
Credential issuance for staffing companies
Credential verification for staffing companies
Credential management for candidates
Administrative functions for platform administrators

The frontend is deployed to AWS S3 and distributed via CloudFront CDN for optimal performance and scalability.

2. Backend API (NestJS)¶

The backend API is built with NestJS and provides RESTful endpoints for:

User management
Credential issuance
Credential verification
Administrative functions
Payment processing
Integration with external services

The backend is deployed to AWS ECS/Elastic Beanstalk for scalability and reliability.

3. Auth0 Identity Platform¶

Auth0 serves as the identity platform for the application, providing:

User authentication (username/password, social, enterprise)
Multi-factor authentication
Passkey (WebAuthn) support
Role-based access control
User profile management
Audit logging for authentication events

4. Database Layer¶

The database layer consists of:

PostgreSQL: Primary relational database for user data, credential metadata, and transaction records
Redis: In-memory cache for session data and frequently accessed information
S3: Object storage for document attachments and credential evidence

5. External Integrations¶

The platform integrates with several external services:

Velocity Credential Agent: For issuing and verifying verifiable credentials
VCL PDF Generation Service: For generating PDF reports and documents
Payment Gateway: For processing payments (implementation details TBD)
Email Service: For sending notifications and credential offers

System Interactions¶

Authentication Flow¶

sequenceDiagram
    participant User
    participant Frontend as React Frontend
    participant Auth0
    participant Backend as NestJS Backend
    participant DB as Database

    User->>Frontend: Access Application
    Frontend->>Auth0: Redirect to Auth0 Login
    Auth0->>User: Present Login UI
    User->>Auth0: Enter Credentials

    alt MFA Required
        Auth0->>User: Request MFA
        User->>Auth0: Provide MFA
    end

    Auth0->>Auth0: Validate Credentials
    Auth0->>Frontend: Return Access & ID Tokens
    Frontend->>Frontend: Store Tokens

    User->>Frontend: Request Protected Resource
    Frontend->>Backend: API Request with Access Token
    Backend->>Backend: Validate Token
    Backend->>DB: Query Data
    DB->>Backend: Return Data
    Backend->>Frontend: Return Protected Resource
    Frontend->>User: Display Protected Resource

Credential Issuance Flow¶

sequenceDiagram
    participant SC as Staffing Company
    participant Frontend as React Frontend
    participant Backend as NestJS Backend
    participant IS as Issuer Service
    participant VCA as Velocity Credential Agent
    participant DB as Database
    participant C as Candidate

    SC->>Frontend: Enter Credential Data
    Frontend->>Backend: Submit Credential Data
    Backend->>IS: Process Credential Request
    IS->>DB: Store Credential Request
    IS->>VCA: Request Credential Issuance
    VCA-->>IS: Credential Created
    IS->>DB: Update Credential Status
    IS->>Backend: Return Success
    Backend->>Frontend: Return Success
    Frontend->>SC: Display Success
    IS->>C: Send Email with Credential Offer

Credential Verification Flow¶

sequenceDiagram
    participant SC as Staffing Company
    participant Frontend as React Frontend
    participant Backend as NestJS Backend
    participant VS as Verification Service
    participant VCA as Velocity Credential Agent
    participant PDF as PDF Generation Service
    participant DB as Database
    participant C as Candidate

    SC->>Frontend: Request Credential Disclosure
    Frontend->>Backend: Submit Disclosure Request
    Backend->>VS: Process Disclosure Request
    VS->>DB: Store Disclosure Request
    VS->>C: Send Disclosure Request Email
    C-->>VCA: Share Credentials
    VCA-->>VS: Receive Shared Credentials
    VS->>VCA: Verify Credentials
    VCA-->>VS: Verification Result
    VS->>DB: Store Verification Result
    VS->>PDF: Generate Verification Report
    PDF-->>VS: PDF Report
    VS->>Backend: Return Verification Result & PDF
    Backend->>Frontend: Return Verification Result & PDF
    Frontend->>SC: Display Verification Result

Auth0 Integration Design¶

Auth0 Tenant Configuration¶

The Auth0 tenant is configured with:

Database Connection: For username/password authentication
Social Connections: Optional integrations with social providers
Enterprise Connections: For staffing company SSO integration
Multi-factor Authentication: Required for admin accounts, optional for others
WebAuthn/Passkey Support: For passwordless authentication
Custom Domain: Branded authentication experience

Role-Based Access Control¶

The platform uses Auth0's role-based access control with the following roles:

Admin: Platform administrators with full access
StaffingCompany: Staffing company users who can issue and verify credentials
Candidate: Individual users who can receive and share credentials

Roles are assigned through Auth0 and included in the JWT tokens as custom claims.

Auth0 Rules and Actions¶

Custom Auth0 rules and actions are implemented for:

Role Assignment: Adding role information to tokens
MFA Enforcement: Requiring MFA for admin accounts
Login Tracking: Recording login events for audit purposes
Token Enhancement: Adding custom claims to tokens

Token Handling¶

The application uses two types of tokens:

ID Token: Contains user profile information
Access Token: Used for API authorization

Tokens are stored securely in memory (not localStorage) and refreshed as needed.

Security Design¶

Authentication Security¶

PKCE Flow: Used for secure authentication
Short-lived Tokens: Access tokens expire after 1 hour
Refresh Tokens: Used for obtaining new access tokens without re-authentication
Token Validation: Backend validates tokens using Auth0's JWKS endpoint

API Security¶

JWT Authentication: All API endpoints require valid JWT tokens
Role-Based Authorization: Endpoints check for appropriate roles
Rate Limiting: Prevents abuse of API endpoints
Input Validation: All input is validated before processing

Data Security¶

Encryption at Rest: All sensitive data is encrypted in the database
Encryption in Transit: All communication uses TLS 1.3
Data Minimization: Only necessary data is collected and stored
Data Retention: Clear policies for data retention and deletion

Deployment Architecture¶

Frontend Deployment¶

flowchart LR
    subgraph "Frontend Deployment"
        GitRepo["GitHub Repository"] --> GHActions["GitHub Actions"]
        GHActions --> Build["Build React App"]
        Build --> Deploy["Deploy to S3"]
        Deploy --> Invalidate["Invalidate CloudFront Cache"]

        S3["S3 Bucket"] --> CloudFront["CloudFront CDN"]
        CloudFront --> Users["End Users"]
    end

Backend Deployment¶

flowchart LR
    subgraph "Backend Deployment"
        GitRepo["GitHub Repository"] --> GHActions["GitHub Actions"]
        GHActions --> Build["Build NestJS App"]
        Build --> Test["Run Tests"]
        Test --> Package["Package Application"]
        Package --> Deploy["Deploy to ECS/Elastic Beanstalk"]

        ECS["ECS/Elastic Beanstalk"] --> ALB["Application Load Balancer"]
        ALB --> Users["API Clients"]
    end

Scalability and Performance¶

Scalability Considerations¶

Horizontal Scaling: Both frontend and backend can scale horizontally
Auto-scaling: ECS/Elastic Beanstalk auto-scaling based on load
Database Scaling: Read replicas for database scaling
CDN: CloudFront for global content delivery

Performance Optimizations¶

Caching Strategy: Redis caching for frequently accessed data
Database Indexing: Proper indexes for common queries
Asset Optimization: Minification and compression of frontend assets
Lazy Loading: Component and route-based code splitting

Monitoring and Observability¶

Monitoring Components¶

Application Logs: Structured logs sent to CloudWatch
Auth0 Logs: Authentication events logged in Auth0
API Metrics: Request counts, response times, error rates
Database Metrics: Query performance, connection counts
Infrastructure Metrics: CPU, memory, network utilization

Alerting Strategy¶

Error Rate Alerts: Alerts for elevated error rates
Latency Alerts: Alerts for slow response times
Security Alerts: Alerts for suspicious authentication events
Capacity Alerts: Alerts for resource utilization thresholds

Disaster Recovery and Business Continuity¶

Backup Strategy¶

Database Backups: Daily automated backups with 30-day retention
Point-in-Time Recovery: Ability to restore to any point in the last 30 days
Geographic Redundancy: Backups stored in multiple AWS regions

Recovery Procedures¶

Database Failure: Automatic failover to standby instance
Application Failure: Auto-scaling to replace failed instances
Region Failure: Manual failover to backup region (future enhancement)

Implementation Considerations¶

Development Workflow¶

Local Development: Developers use local Auth0 tenant for development
Testing: Automated tests use test Auth0 tenant
Staging: Staging environment uses staging Auth0 tenant
Production: Production environment uses production Auth0 tenant

Auth0 Tenant Separation¶

Development Tenant: Used for local development
Testing Tenant: Used for automated tests
Staging Tenant: Used for staging environment
Production Tenant: Used for production environment

Conclusion¶

The system design outlined in this document provides a comprehensive approach to implementing the REC Verifiable Credentialing Platform with Auth0 integration. The design prioritizes security, scalability, and maintainability while meeting all the specified requirements.

For detailed Auth0 implementation steps, refer to the Auth0 Implementation Plan.

For a comprehensive overview of the entire platform architecture, refer to the Architecture Documentation.