Skip to main content

UID Login

This module enables passwordless one-tap login for employees.

Overview​

The UID Login module provides a simplified authentication method that allows employees to log in using their registered device ID without requiring a password. When a device is registered to a user via the Field Manager module, that device can authenticate directly using its unique device identifier.

Features​

  • Device-Based Authentication: Login using a registered device's unique ID
  • Passwordless Login: Quick access without password entry for mobile apps
  • JWT Token Generation: Returns a JWT token valid for 28 days upon successful authentication
  • Device Verification: Checks if a device ID is registered before attempting login
  • Role-Based Access Control: Validates that the user's role has mobile app access enabled

Requirements​

  • Open Core Business Suite (Base System)
  • FieldManager module (required - uses the UserDevice model for device registration)

Installation​

Enable via Admin Panel​

  1. Log in as administrator
  2. Navigate to Settings > Addons
  3. Find UID Login and click Enable

Enable via Command Line​

php artisan module:enable UidLogin

Usage​

This module is an API-only module with no web interface. It provides two API endpoints used by the mobile apps for passwordless device-based authentication. There are no admin settings to configure.

Prerequisites​

Before UID Login can be used, a device must be registered to an employee through the Field Manager module. This creates a UserDevice record that links a unique device ID to a specific user account.

Mobile App Integration​

The mobile apps use UID Login for quick re-authentication:

  1. Check Device - The app calls GET /api/V1/checkUid?uid={device_id} to verify the device is registered
  2. Authenticate - If registered, the app calls POST /api/V1/loginWithUid with the device ID to receive a JWT token
  3. Access Granted - The JWT token (valid for 28 days) is used for all subsequent API requests

Validation Checks​

During login, the module verifies:

  • The device ID is registered in the system
  • The associated user account exists
  • The user account is active (not inactive)
  • The user's role has mobile app access enabled (is_mobile_app_access_enabled)

If any check fails, an appropriate error message is returned.

How It Works​

  1. An employee's device must first be registered through the Field Manager module, which creates a UserDevice record linking a device ID to a user
  2. The mobile app can then use the device ID to authenticate without a password
  3. The module verifies the device is registered, finds the associated user, checks user status and role permissions, then issues a JWT token

API Endpoints​

Check Device UID​

Verify if a device ID is registered in the system before attempting login.

GET /api/V1/checkUid?uid={device_id}

Parameters:

ParameterTypeRequiredDescription
uidstringYesThe device ID to check

Response (found):

{
    "success": true,
    "message": "Device found"
}

Response (not found):

{
    "success": false,
    "message": "Device not found"
}

Login with Device UID​

Authenticate using a registered device ID and receive a JWT token.

POST /api/V1/loginWithUid
Content-Type: application/json

{
    "deviceId": "device-unique-id"
}

Response (success):

{
    "success": true,
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "id": 1,
        "firstName": "John",
        "lastName": "Doe",
        "employeeCode": "EMP001",
        "dob": "1990-01-15",
        "gender": "male",
        "email": "[email protected]",
        "phoneNumber": "1234567890",
        "status": "active",
        "role": "employee",
        "isLocationActivityTrackingEnabled": true,
        "designation": "Software Engineer",
        "createdAt": "2024-01-01 10:00:00",
        "avatar": "https://yourdomain.com/uploads/profile/photo.jpg",
        "expiresIn": 40320
    }
}

Error responses:

  • deviceId is required - No device ID provided
  • Device not found. Please register this device first. - Device ID not registered
  • User not found. - Associated user does not exist
  • User is inactive. - User account is disabled
  • You do not have permission to access this resource - User role lacks mobile app access

Security Considerations​

When to Use UID Login​

UID login is appropriate for:

  • Mobile app authentication: Where the device has already been registered and verified
  • Quick re-authentication: For mobile apps that need to re-authenticate after token expiry

Important Notes​

  • Device registration must happen first through the Field Manager module
  • Only users with roles that have is_mobile_app_access_enabled can use UID login
  • Inactive users cannot authenticate via UID login
  • The JWT token is valid for 28 days

Troubleshooting​

Device Not Found​

  • Verify the device has been registered through the Field Manager module
  • Check the device ID matches exactly what was registered
  • Ensure the FieldManager module is enabled

Permission Denied​

  • Check that the user's role has mobile app access enabled (is_mobile_app_access_enabled)
  • Verify the user account is active

User Inactive​

  • Contact an administrator to reactivate the user account

Changelog: View version history

Last updated on