Skip to main content

Authentication Overview

Introduction​

The BankLingo authentication system provides secure access control for both administrators and customers. It supports multiple verification methods including email OTP, SMS OTP, and TOTP authenticator apps (Google Authenticator, Microsoft Authenticator, etc.).

Authentication Methods​

1. Password-Based Login​

All users authenticate initially with their email/username and password. After successful password validation, a two-factor authentication (2FA) step is required.

2. Two-Factor Authentication (2FA)​

The system supports three verification methods for 2FA:

MethodverificationMethodTypeDescription
Default0Uses the user's preferred method (email or SMS)
Email OTP1One-time password sent via email
SMS OTP2One-time password sent via SMS
Authenticator App3TOTP code from authenticator app

Authentication Flow​

Standard Login Flow​

Authenticator App Setup Flow​

API Endpoints​

Admin Login​

  • Endpoint: /api/BPMSelfService/commands/SelfAdminLoginCommand
  • Method: POST
  • Purpose: Administrator login with 2FA support
  • View Details →

Customer Login​

  • Endpoint: /api/BPMSelfService/commands/SelfLoginCommand
  • Method: POST
  • Purpose: Customer login with 2FA support
  • View Details →

OTP Validation​

  • Endpoint: /api/BPMSelfService/commands/ValidateOtpCommand
  • Method: POST
  • Purpose: Validate email/SMS OTP or TOTP codes
  • View Details →

Resend OTP​

  • Endpoint: /api/BPMSelfService/commands/ResendOtpCommand
  • Method: POST
  • Purpose: Resend OTP for email/SMS methods
  • View Details →

Authenticator Setup​

Authenticator Login​

Refresh Token​

Security Features​

TOTP (Time-based One-Time Password)​

  • Standard: RFC 6238
  • Algorithm: HMAC-SHA1
  • Key Length: 160 bits (20 bytes)
  • Code Length: 6 digits
  • Time Step: 30 seconds
  • Time Window: ±30 seconds (for clock drift tolerance)

Password Security​

  • Passwords are hashed using strong cryptographic algorithms
  • Password complexity requirements enforced
  • Account lockout after multiple failed attempts

JWT Tokens​

  • Tokens are signed using secure algorithms
  • Short expiration times with refresh token support
  • Include claims for user identity, roles, and permissions

Common Response Codes​

Status CodeDescription
200Success
400Bad request (invalid parameters)
401Unauthorized (invalid credentials or token)
403Forbidden (insufficient permissions)
404User not found
500Internal server error

Best Practices​

For Frontend Developers​

  1. Always use HTTPS for authentication endpoints
  2. Store JWT tokens securely (HttpOnly cookies recommended)
  3. Clear tokens on logout to prevent unauthorized access
  4. Handle token expiration gracefully with refresh tokens
  5. Never log sensitive data (passwords, OTPs, tokens)

For Security​

  1. Implement rate limiting on login endpoints
  2. Monitor failed login attempts for suspicious activity
  3. Use strong password policies (minimum length, complexity)
  4. Enable 2FA for all users when possible
  5. Regular security audits of authentication logs

For Authenticator Apps​

  1. Recommend popular authenticator apps:

    • Google Authenticator
    • Microsoft Authenticator
    • Authy
    • LastPass Authenticator

  2. Provide backup codes in case user loses access to authenticator

  3. Allow account recovery through alternative methods

  4. Test time synchronization issues

Testing​

Testing Email/SMS OTP​

  1. Use test environment with email/SMS capture
  2. Verify OTP delivery and expiration
  3. Test resend functionality
  4. Test rate limiting

Testing Authenticator Apps​

  1. Test setup flow with QR code scanning
  2. Verify TOTP code validation
  3. Test time window tolerance
  4. Test with multiple authenticator apps

Error Handling​

Common Errors​

ErrorCauseSolution
Invalid OTPWrong code or expiredRequest new OTP
Invalid TOTPWrong code or time sync issueCheck device time, try again
User locked outToo many failed attemptsWait for lockout period or contact admin
Setup requiredAuthenticator not configuredComplete setup flow

Support​

For authentication issues or questions: