​
Authentication Service

The Authentication Service provides secure user authentication and authorization capabilities across your organization’s ecosystem. It manages user identity verification, session handling, and supports multiple authentication methods including password, one-time passwords (OTP), OAuth providers (Google, Microsoft), Azure AD, and SAML SSO.

​
Architecture Overview

The Authentication Service is built on a Node.js backend with MongoDB for data persistence and Redis for session management. The service implements a container-based dependency injection pattern using InversifyJS for better modularity and testability. Key components that the Auth Service integrates with:
  • IAM Service - Manages user and organization information
  • Configuration Manager - Stores authentication provider configurations
  • Communication Service - Handles email delivery for password resets and OTP
  • Redis - Manages authentication sessions and temporary tokens

​
Authentication Flow Process

The Auth Service employs a multi-step session-based authentication flow:
  1. Authentication Initialization
    • Client calls the /userAccount/initAuth endpoint with an email
    • Server validates the email and creates a temporary session in Redis
    • Server returns a session token in the x-session-token response header along with available authentication methods
  2. Authentication Steps
    • Client calls /userAccount/authenticate with the session token in the x-session-token header
    • Client provides chosen authentication method and credentials
    • If multi-factor authentication is configured, the server returns information about the next step
    • Client repeats the authentication step with appropriate credentials until all required steps are completed
  3. Token Issuance
    • After successful authentication, the server issues access and refresh tokens
    • The Redis session is cleared
    • Client stores tokens for subsequent API calls
Here’s a sequence diagram of the flow:

​
Data Models

​
Session Management with Redis

The Auth Service uses Redis to store temporary session data during the authentication process:
  • Sessions are identified by a unique UUID token
  • The x-session-token header is used to track the session across requests
  • Sessions expire after a configurable period (default: 1 hour)
  • Session data includes authentication state, user info, and available auth methods
  • After successful authentication, sessions are deleted from Redis

​
Token-Based Authentication

After successful authentication, the service issues two types of JWTs:
  1. Access Token
    • Short-lived token (typically 1 hour)
    • Contains user ID, organization ID, user email, and permissions
    • Used for authorizing API requests across services
  2. Refresh Token
    • Longer-lived token (typically 7 days)
    • Used to obtain new access tokens when they expire
    • Prevents the need for frequent re-authentication
Both tokens are cryptographically signed with JWT secrets to ensure authenticity.

​
Auth Service API

​
Authentication Endpoints

POST /api/v1/userAccount/initAuth

​
Authentication Process

POST /api/v1/userAccount/authenticate

​
OTP Authentication

POST /api/v1/userAccount/login/otp/generate

​
Password Management

POST /api/v1/userAccount/password/forgot

POST /api/v1/userAccount/password/reset/token

POST /api/v1/userAccount/password/reset

​
Token Management

POST /api/v1/userAccount/refresh/token

POST /api/v1/userAccount/logout/manual

​
SAML SSO Integration

GET /api/v1/saml/signIn

POST /api/v1/saml/signIn/callback

​
Organization Auth Configuration

GET /api/v1/orgAuthConfig/authMethods

POST /api/v1/orgAuthConfig/updateAuthMethod

POST /api/v1/orgAuthConfig/

​
Security Considerations

The Authentication Service implements several security measures:
  • Password Security
    • Passwords are validated for complexity requirements
    • Passwords are hashed using bcrypt with salt rounds
    • Password reset links have limited validity
  • Brute Force Protection
    • Failed login attempts are tracked
    • Accounts are automatically blocked after multiple failures
    • Suspicious login attempts trigger notification emails
  • Session Security
    • Session tokens are generated as UUIDs
    • Sessions have limited lifetime and are stored in Redis
    • Sessions are invalidated after authentication or timeout
  • JWT Security
    • Tokens are signed with secure secrets
    • Different scopes are used for different token types
    • Access tokens have short lifetimes