PVPipe ms-auth Documentation

This directory contains comprehensive documentation for the PVPipe Authentication microservice, including biometric authentication, WebAuthn/passkey support, and deployment guides.

Documentation Structure

Core API Documentation

  • API.md - Complete API reference with all endpoints, authentication types, and integration examples
  • BIOMETRIC_GUIDE.md - Comprehensive biometric authentication implementation guide
  • WEBAUTHN_IMPLEMENTATION.md - WebAuthn/passkey implementation for modern passwordless auth

Implementation Guides

Specialized Topics

Quick Start

For API Consumers

  1. Read API.md for complete endpoint reference
  2. Check mobile-integration-guide.md for platform-specific implementations
  3. Review security-architecture.md for security requirements

For Mobile Developers

  1. Start with BIOMETRIC_GUIDE.md for biometric authentication overview
  2. Follow mobile-integration-guide.md for your platform (iOS/Android/React Native)
  3. Configure PUSH_NOTIFICATIONS.md for cross-device workflows

For Web Developers

  1. Review API.md for standard authentication endpoints
  2. Implement WEBAUTHN_IMPLEMENTATION.md for passwordless login
  3. Set up action confirmation flows using biometric endpoints

For DevOps/SysAdmins

  1. Follow deployment-guide.md for production deployment
  2. Review security-architecture.md for security hardening
  3. Configure monitoring and alerting as documented

Authentication Methods Supported

Standard Authentication

  • Username/password login with JWT tokens
  • Token refresh and revocation
  • Multi-factor authentication (TOTP)

Biometric Authentication

  • Mobile device registration with public key cryptography
  • Biometric login (TouchID, FaceID, Fingerprint)
  • Cross-device action confirmation
  • Push notification integration

WebAuthn/Passkey

  • Platform authenticators (built-in biometrics)
  • External security keys (YubiKey, etc.)
  • Resident credentials (passkeys)
  • Cross-platform synchronization

Security Features

  • Zero Trust Architecture: Every request authenticated and validated
  • Cryptographic Security: ES256/RS256/PS256 signatures, AES-256-GCM encryption
  • Device Binding: Tokens tied to specific registered devices
  • Token Differentiation: Multiple token types with appropriate lifetimes
  • Comprehensive Auditing: Full security event logging
  • Vietnamese Compliance: Meets enterprise regulatory requirements

Architecture Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Web Client    │    │  Mobile Client   │    │  External Key   │
│  (WebAuthn)     │    │  (Biometric)     │    │  (Security Key) │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                         ┌──────────────┐
                         │ API Gateway  │
                         │  (Traefik)   │
                         └──────────────┘
                                 │
                         ┌──────────────┐
                         │   ms-auth    │
                         │   Service    │
                         └──────────────┘
                                 │
                   ┌─────────────┼─────────────┐
                   │             │             │
            ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
            │PostgreSQL   │ │    Redis    │ │ Firebase    │
            │ Database    │ │   Cache     │ │    FCM      │
            └─────────────┘ └─────────────┘ └─────────────┘

Service Capabilities

Multi-Platform Support

  • Web: WebAuthn/passkey authentication
  • Mobile: Native biometric authentication (iOS/Android/React Native)
  • Cross-Device: Action confirmation across devices
  • Enterprise: Vietnamese compliance and audit requirements

Token Types

  • Standard Access/Refresh: Web authentication (8h/30d)
  • Biometric Access/Refresh: Mobile authentication (15min/30d)
  • Action Confirmation: Single-use sensitive operations (5min)
  • WebAuthn: Passwordless web authentication

Security Standards

  • Cryptography: ES256 (recommended), RS256, PS256
  • Encryption: AES-256-GCM for sensitive fields
  • Compliance: Vietnamese digital signature law
  • Audit: Comprehensive security event logging

Recent Changes (2025-08-13)

Documentation Reorganization

  • Consolidated API Documentation: Combined multiple API docs into single comprehensive reference
  • Unified Biometric Guide: Merged 4 separate biometric documents into cohesive implementation guide
  • Added WebAuthn Support: New comprehensive WebAuthn/passkey implementation documentation
  • Removed Redundancies: Eliminated duplicate information across multiple files

Files Reorganized

Created:

  • API.md - Complete API reference (consolidated from api-guidelines.md + biometric-api-complete.md)
  • BIOMETRIC_GUIDE.md - Unified implementation guide (consolidated from 4 separate biometric docs)
  • WEBAUTHN_IMPLEMENTATION.md - New WebAuthn/passkey implementation guide
  • README.md - This documentation index

Removed (consolidated into above):

  • api-guidelines.md → merged into API.md
  • biometric-api-complete.md → merged into API.md
  • BIOMETRIC_IMPLEMENTATION.md → merged into BIOMETRIC_GUIDE.md
  • BIOMETRIC_JWT_EXAMPLES.md → merged into BIOMETRIC_GUIDE.md
  • IMPLEMENTATION_REPORT.md → merged into BIOMETRIC_GUIDE.md
  • JWT_BIOMETRIC_IMPLEMENTATION_REPORT.md → merged into BIOMETRIC_GUIDE.md
  • JWT_TOKEN_DIFFERENTIATION_REPORT.md → merged into BIOMETRIC_GUIDE.md

Retained (specialized content):

  • deployment-guide.md - Production deployment guide
  • mobile-integration-guide.md - Platform-specific mobile integration
  • security-architecture.md - Security model and compliance
  • PUSH_NOTIFICATIONS.md - Firebase FCM setup details

Support and Integration

Getting Help

Example Implementations

All documentation includes comprehensive examples for:

  • JavaScript/TypeScript (Web, React, React Native)
  • Swift (iOS native)
  • Kotlin (Android native)
  • Go (server-side)
  • Docker/Kubernetes deployment configurations

This documentation structure provides clear, comprehensive guidance for implementing and deploying the PVPipe authentication service across all supported platforms and use cases.