​

Authentication Service

​

Base URL

​

Authentication

Authorization: Bearer YOUR_TOKEN

• PASSWORD_RESET - For password reset operations
• TOKEN_REFRESH - For token refresh operations
• FETCH_CONFIG - For configuration updates

​

Architecture Overview

• 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

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

​

Data Models

interface IOrgAuthConfig extends Document {
  orgId: Types.ObjectId;
  domain?: string;
  authSteps: {
    order: number;
    allowedMethods: {
      type: 'samlSso' | 'otp' | 'password' | 'google' | 'microsoft' | 'azureAd' | 'oauth';
    }[];
  }[];
  isDeleted?: boolean;
  createdAt?: Date;
  updatedAt?: Date;
}

interface IUserCredentials extends Document {
  userId?: string | null;
  orgId: string;
  ipAddress: string;
  otpValidity?: number;
  hashedOTP?: string;
  hashedPassword?: string;
  forceNewPasswordGeneration: boolean;
  wrongCredentialCount: number;
  isBlocked: boolean;
  isDeleted: boolean;
  createdAt?: Date;
  updatedAt?: Date;
}

interface IUserActivity extends Document {
  email: string;
  userId: Types.ObjectId;
  orgId?: Types.ObjectId;
  activityType:
    | 'LOGIN'
    | 'LOGOUT'
    | 'LOGIN_ATTEMPT'
    | 'OTP_GENERATE'
    | 'WRONG_OTP'
    | 'WRONG_PASSWORD'
    | 'REFRESH_TOKEN';
  loginMode?:
    | 'OTP'
    | 'PASSWORD'
    | 'AUTH SERVICE'
    | 'GOOGLE OAUTH'
    | 'MICROSOFT OAUTH'
    | 'AZUREAD OAUTH'
    | 'OAUTH'
    | 'SSO';
  ipAddress: string;
  isDeleted?: boolean;
  createdAt?: Date;
  updatedAt?: Date;
}

interface SessionData {
  token?: string;
  userId: string;
  email: string;
  orgId: string;
  authConfig: IAuthStep[];
  currentStep: number;
  isAuthenticated?: boolean;
  [key: string]: any; // Allows additional properties
}

​

Session Management with Redis

• 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

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

​

API Endpoints

{
  "email": "user@example.com"
}

{
  "method": "password",
  "credentials": {
    "password": "your-secure-password"
  }
}

{
  "method": "otp",
  "credentials": {
    "otp": "123456"
  }
}

{
  "method": "google",
  "credentials": "google-id-token-string"
}

{
  "method": "microsoft",
  "credentials": {
    "accessToken": "microsoft-access-token",
    "idToken": "microsoft-id-token"
  }
}

{
  "method": "azureAd",
  "credentials": {
    "accessToken": "azure-ad-access-token",
    "idToken": "azure-ad-id-token"
  }
}

{
  "method": "oauth",
  "credentials": {
    "accessToken": "oauth-access-token",
    "idToken": "oauth-id-token"
  }
}

{
  "email": "user@example.com"
}

{
  "code": "authorization-code-from-provider",
  "email": "user@example.com",
  "provider": "google",
  "redirectUri": "https://your-app.com/callback"
}

{
  "email": "user@example.com"
}

{
  "password": "new-secure-password"
}

{
  "currentPassword": "current-password",
  "newPassword": "new-secure-password"
}

GET /api/v1/saml/signIn?email=user@example.com&sessionToken=session-token-123

{
  "authMethod": [
    {
      "order": 1,
      "allowedMethods": [
        {
          "type": "password"
        },
        {
          "type": "otp"
        }
      ]
    },
    {
      "order": 2,
      "allowedMethods": [
        {
          "type": "google"
        }
      ]
    }
  ]
}

{
  "contactEmail": "admin@example.com",
  "registeredName": "Example Corporation",
  "adminFullName": "John Admin",
  "sendEmail": false
}

​

Security Considerations

​

Password Security

• Passwords are validated for complexity requirements (minimum 8 characters with at least one uppercase, one lowercase, one number, and one special character)
• Passwords are hashed using bcrypt with salt rounds
• Password reset links have limited validity

​

Brute Force Protection

• Failed login attempts are tracked per user account
• Accounts are automatically blocked after 5 consecutive failed attempts
• Suspicious login attempts trigger notification emails
• Blocked accounts require admin intervention to restore access

​

Session Security

• Session tokens are generated as UUIDs
• Sessions have limited lifetime (default: 1 hour) and are stored in Redis
• Sessions are invalidated after successful authentication or timeout
• Session data is encrypted and contains minimal user information

​

JWT Security

• Tokens are signed with secure secrets
• Different scopes are used for different token types (auth, refresh, password reset, etc.)
• Access tokens have short lifetimes (typically 1 hour)
• Refresh tokens have longer lifetimes (typically 7 days)

​

OAuth Security

• OAuth tokens are validated against provider endpoints
• Email verification ensures token authenticity
• Provider-specific validation for Google, Microsoft, and Azure AD
• Generic OAuth support with configurable endpoints

​

SAML Security

• SAML responses are cryptographically verified
• Certificate-based validation
• Configurable email field mapping
• Relay state protection against CSRF attacks

​

Error Handling

{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid credentials provided",
    "details": {
      "field": "password",
      "issue": "Password does not match"
    }
  }
}

• AUTHENTICATION_FAILED - Invalid credentials
• SESSION_EXPIRED - Session token expired
• INVALID_TOKEN - Invalid or malformed token
• USER_BLOCKED - Account is blocked due to failed attempts
• VALIDATION_ERROR - Invalid request parameters
• UNAUTHORIZED - Missing or invalid authentication
• FORBIDDEN - Insufficient permissions
• NOT_FOUND - Resource not found
• INTERNAL_ERROR - Server error

​

Important Notes

1. Session Token Management: The x-session-token header is critical for multi-step authentication flows
2. Password Complexity: Passwords must meet minimum security requirements
3. Account Blocking: Users are automatically blocked after 5 failed login attempts
4. Token Scopes: Different endpoints require different token scopes for access
5. Multi-Factor Authentication: Organizations can configure multiple authentication steps
6. Provider Configuration: OAuth and SAML providers require proper configuration
7. Email Validation: All email fields are validated for proper format
8. Security Headers: Proper headers must be included for authentication flows