--- title: Cuatrolabs Auth Ms emoji: 📊 colorFrom: green colorTo: green sdk: docker pinned: false --- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference # Cuatrolabs Auth Microservice Authentication and authorization microservice for the Cuatrolabs platform. ## Features ### System User Authentication - JWT-based authentication for system users - Role-based access control (RBAC) - Password rotation policies - Account lockout protection - Forgot password functionality - Session management ### Customer Authentication (Mobile App) - **WhatsApp OTP Authentication** via WATI API - Mobile number-based login - Automatic customer registration - Profile management (name, email, gender, DOB) - JWT token generation for customers - Secure OTP delivery via WhatsApp ### Staff Authentication (Employee/Staff Users) - **WhatsApp OTP Authentication** via WATI API - Mobile number-based login for staff - Role validation (staff only, excludes admin) - Status validation (active users only) - JWT token generation with merchant context - Secure OTP delivery via WhatsApp - Separate OTP storage from customers ### Security Features - Password hashing with bcrypt - JWT token generation and validation - Rate limiting for OTP requests - Maximum login attempt tracking - Account lockout after failed attempts - Password expiration policies - Secure token storage ## Architecture ### Technology Stack - **Framework**: FastAPI (Python) - **Database**: MongoDB (NoSQL) - **Cache**: Redis - **Authentication**: JWT (JSON Web Tokens) - **WhatsApp Integration**: WATI API - **Password Hashing**: bcrypt ### Key Components 1. **System Users Module** (`app/system_users/`) - System user management - Role and permission management - Password policies 2. **Customer Auth Module** (`app/auth/`) - Customer OTP authentication - WhatsApp OTP delivery via WATI - Customer profile management - Token generation 3. **Internal Module** (`app/internal/`) - Internal authentication utilities - Token validation - Permission checking ## Quick Start ### Prerequisites - Python 3.9+ - MongoDB - Redis - WATI account (for WhatsApp OTP) ### Installation 1. Clone the repository ```bash git clone cd cuatrolabs-auth-ms ``` 2. Create virtual environment ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. Install dependencies ```bash pip install -r requirements.txt ``` 4. Configure environment variables ```bash cp .env.example .env # Edit .env with your configuration ``` 5. Start the service ```bash ./start_server.sh ``` The service will be available at `http://localhost:8001` ## Configuration ### Environment Variables Key configuration in `.env`: ```env # MongoDB MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/ MONGODB_DB_NAME=cuatrolabs # Redis REDIS_HOST=your-redis-host.com REDIS_PORT=6379 REDIS_PASSWORD=your-redis-password # JWT SECRET_KEY=your-secret-key TOKEN_EXPIRATION_HOURS=8 # WATI WhatsApp API (for Customer OTP) WATI_API_ENDPOINT=https://live-mt-server.wati.io/YOUR_TENANT_ID WATI_ACCESS_TOKEN=your-wati-bearer-token WATI_OTP_TEMPLATE_NAME=cust_otp ``` See `.env.example` for complete configuration options. ## WhatsApp OTP Integration ### Overview Both customer and staff authentication use WATI WhatsApp API to send OTP codes via WhatsApp messages. ### Setup 1. **Create WATI Account** - Sign up at [WATI](https://www.wati.io) - Choose Growth, Pro, or Business plan 2. **Create Authentication Templates** **Customer Template:** `cust_otp` ``` Your OTP for login is: {{otp_code}} This code will expire in {{expiry_time}} minutes. Do not share this code with anyone. ``` **Staff Template:** `staff_otp_login` ``` Your staff login OTP is: {{otp_code}} This code will expire in {{expiry_time}} minutes. Do not share this code with anyone. ``` - Add "Copy Code" button - Submit for WhatsApp approval 3. **Configure Environment** - Add WATI credentials to `.env` - Set template names 4. **Test Integration** ```bash # Test customer OTP python test_wati_otp.py # Test staff OTP python test_staff_wati_otp.py ``` ### Documentation **Customer OTP:** - Quick Start: [WATI_QUICKSTART.md](WATI_QUICKSTART.md) - Full Guide: [WATI_WHATSAPP_OTP_INTEGRATION.md](WATI_WHATSAPP_OTP_INTEGRATION.md) - Implementation: [WATI_IMPLEMENTATION_SUMMARY.md](WATI_IMPLEMENTATION_SUMMARY.md) **Staff OTP:** - Full Guide: [STAFF_WATI_OTP_INTEGRATION.md](STAFF_WATI_OTP_INTEGRATION.md) - Summary: [STAFF_WATI_OTP_COMPLETE.md](../STAFF_WATI_OTP_COMPLETE.md) ## API Endpoints ### System User Authentication #### POST /auth/login Login with username and password. **Request:** ```json { "username": "user@example.com", "password": "password123" } ``` **Response:** ```json { "access_token": "eyJhbGci...", "token_type": "bearer", "expires_in": 28800 } ``` #### POST /auth/forgot-password Request password reset. #### POST /auth/reset-password Reset password with token. ### Staff Authentication #### POST /staff/send-otp Send OTP to staff mobile number via WhatsApp. **Request:** ```json { "phone": "+919999999999" } ``` **Response:** ```json { "success": true, "message": "OTP sent successfully via WhatsApp", "expires_in": 300 } ``` #### POST /staff/login/mobile-otp Verify OTP and authenticate staff user. **Request:** ```json { "phone": "+919999999999", "otp": "123456" } ``` **Response:** ```json { "access_token": "eyJhbGci...", "token_type": "bearer", "expires_in": 28800, "user_info": { "user_id": "uuid", "username": "staff@example.com", "role": "staff", "merchant_id": "merchant-uuid" } } ``` #### GET /staff/me Get current staff user profile (requires authentication). #### POST /staff/logout Logout current staff user (requires authentication). ### Customer Authentication #### POST /customer/auth/send-otp Send OTP to customer's WhatsApp. **Request:** ```json { "mobile": "+919999999999" } ``` **Response:** ```json { "success": true, "message": "OTP sent successfully via WhatsApp", "expires_in": 300 } ``` #### POST /customer/auth/verify-otp Verify OTP and authenticate customer. **Request:** ```json { "mobile": "+919999999999", "otp": "123456" } ``` **Response:** ```json { "access_token": "eyJhbGci...", "customer_id": "uuid", "is_new_customer": false, "token_type": "bearer", "expires_in": 28800 } ``` #### GET /customer/auth/profile Get customer profile (requires authentication). #### PUT /customer/auth/profile Update customer profile. **Request:** ```json { "name": "John Doe", "email": "john@example.com", "gender": "male", "dob": "1990-01-01" } ``` ### System User Management #### POST /system-users/create Create new system user. #### GET /system-users/{user_id} Get system user details. #### PUT /system-users/{user_id} Update system user. #### POST /system-users/list List system users with filters. ## Testing ### Unit Tests ```bash pytest tests/ ``` ### Integration Tests **Test Customer OTP Flow:** ```bash python test_customer_auth.py python test_wati_otp.py ``` **Test Staff OTP Flow:** ```bash python test_staff_wati_otp.py ``` **Test System User API:** ```bash python test_system_users_api.py ``` ### Manual Testing Use the provided test scripts in the root directory: - `test_customer_auth.py` - Customer authentication flow - `test_forgot_password.py` - Password reset flow - `test_password_rotation.py` - Password rotation policies - `test_system_users_api.py` - System user management ## Database Schema ### Collections #### system_users System user accounts with roles and permissions. #### scm_customers Customer accounts for mobile app users. #### customer_otps OTP codes for customer authentication. #### staff_otps OTP codes for staff authentication (separate from customer OTPs). #### password_reset_tokens Tokens for password reset functionality. #### user_sessions Active user sessions. ## Security ### Best Practices 1. **Environment Variables**: Never commit `.env` files 2. **Token Security**: Rotate JWT secret keys regularly 3. **Password Policies**: Enforce strong passwords 4. **Rate Limiting**: Implement rate limiting on OTP endpoints 5. **Logging**: Monitor authentication attempts 6. **HTTPS**: Always use HTTPS in production ### Password Requirements - Minimum 8 characters - At least one uppercase letter - At least one lowercase letter - At least one number - At least one special character ### OTP Security - 6-digit random codes - 5-minute expiration - Maximum 3 verification attempts - One-time use only - Secure delivery via WhatsApp ## Logging Logs are stored in `logs/` directory: - `app.log` - All logs - `app_info.log` - Info level logs - `app_errors.log` - Error level logs ### Log Levels - **INFO**: Successful operations - **WARNING**: Invalid attempts, expired tokens - **ERROR**: API failures, system errors ## Deployment ### Docker Build and run with Docker: ```bash docker build -t cuatrolabs-auth-ms . docker run -p 8001:8001 --env-file .env cuatrolabs-auth-ms ``` ### Kubernetes Deploy using Helm charts in `cuatrolabs-deploy` repository. ## Monitoring ### Health Check ```bash curl http://localhost:8001/health ``` ### Metrics to Monitor - Authentication success/failure rates - OTP delivery success rates - Token generation rates - Failed login attempts - Account lockouts - API response times ## Troubleshooting ### Common Issues **OTP Not Received** - Verify WATI credentials in `.env` - Check mobile number is WhatsApp-enabled - Review logs for API errors - Verify template is approved in WATI **Authentication Failures** - Check MongoDB connection - Verify JWT secret key - Review user credentials - Check account lockout status **Database Connection Issues** - Verify MongoDB URI - Check network connectivity - Ensure database exists - Review MongoDB logs ## Documentation ### Customer Authentication - [WATI Quick Start](WATI_QUICKSTART.md) - [WATI Integration Guide](WATI_WHATSAPP_OTP_INTEGRATION.md) - [Implementation Summary](WATI_IMPLEMENTATION_SUMMARY.md) ### System Features - [Customer Profile Updates](CUSTOMER_PROFILE_UPDATE_ENDPOINTS.md) - [Password Rotation](PASSWORD_ROTATION_POLICY.md) - [Forgot Password](FORGOT_PASSWORD_FEATURE.md) - [Error Handling](ERROR_HANDLING_GUIDE.md) - [Logging Guide](LOGGING_QUICK_REFERENCE.md) ### Testing - [System Users API Testing](SYSTEM_USERS_API_TESTING.md) - [Test Scripts README](TEST_SCRIPTS_README.md) ## Contributing 1. Create feature branch 2. Make changes 3. Add tests 4. Update documentation 5. Submit pull request ## Support For issues or questions: - Check documentation in this repository - Review logs in `logs/` directory - Contact development team ## License Proprietary - Cuatrolabs --- **Version**: 1.0.0 **Last Updated**: February 5, 2026