> ## Content Index
> Fetch the complete content index at: https://blog.fabrixly.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Authentication Reference Guide
- URL: https://blog.fabrixly.com/authentication-reference-78/
- Published: 2026-09-16T01:37:52.000Z
- Updated: 2026-09-16T02:15:36.000Z
- Author: Fabrixly
- Tags: Documentation, Authentication, Reference, Fabrixly-IDS

# Multi-Method Authentication System

## Table of Contents

1. [Overview](#overview)
2. [Authentication Modes](#authentication-modes)
3. [Configuration Guide](#configuration-guide)
4. [User Experience](#user-experience)
5. [API Reference](#api-reference)
6. [Testing](#testing)
7. [Security Considerations](#security-considerations)
8. [Troubleshooting](#troubleshooting)

---

## Overview

The Fabrixly-IDS Identity Server supports four distinct authentication modes, providing flexibility for different security requirements and user preferences. Each client application can be configured independently with its preferred authentication method.

### Key Features

- **4 Authentication Modes**: Password-only, OTP-only, 2FA, and Flexible
- **Mobile Number Login**: Support for mobile number as identifier
- **Configurable OTP Delivery**: Email, SMS, or both
- **Dynamic UI**: Login form adapts to configured mode
- **Session Management**: Secure 2FA flow with session state

---

## Authentication Modes

### 1\. Password Only (`auth_mode: "password"`)

**Description:** Traditional username/password authentication.

**Use Cases:**

- Internal applications with existing password policies
- Applications where OTP delivery is not feasible
- Legacy system integration

**User Flow:**

1. User enters email/mobile
2. User enters password
3. Immediate login upon validation

**Security Level:** ⭐⭐⭐ (Medium)

**Configuration:**

```typescript
{
  auth_mode: "password",
  enable_mobile_login: false,
  otp_delivery_method: "email" // Not used
}

```

---

### 2\. OTP Only (`auth_mode: "otp"`)

**Description:** Passwordless authentication using One-Time Passwords.

**Use Cases:**

- Consumer-facing applications
- Mobile-first applications
- Reducing password management burden
- Improved user experience

**User Flow:**

1. User enters email/mobile
2. OTP sent automatically
3. User enters 6-digit OTP
4. Login upon OTP verification

**Security Level:** ⭐⭐⭐⭐ (High)

**Configuration:**

```typescript
{
  auth_mode: "otp",
  enable_mobile_login: true,
  otp_delivery_method: "email" // or "sms" or "both"
}

```

**Benefits:**

- No password to remember
- Reduced credential theft risk
- Better mobile UX
- Time-limited codes

---

### 3\. Password + OTP (2FA) (`auth_mode: "password_and_otp"`)

**Description:** Two-factor authentication requiring both password and OTP.

**Use Cases:**

- High-security applications
- Financial services
- Healthcare systems
- Admin panels
- Compliance requirements (PCI-DSS, HIPAA)

**User Flow:**

1. **Step 1:** User enters email/mobile + password
2. Password validated
3. OTP sent to user
4. **Step 2:** User enters 6-digit OTP
5. Login upon OTP verification

**Security Level:** ⭐⭐⭐⭐⭐ (Very High)

**Configuration:**

```typescript
{
  auth_mode: "password_and_otp",
  enable_mobile_login: false,
  otp_delivery_method: "email" // or "sms" or "both"
}

```

**Benefits:**

- Multi-factor security
- Protection against password compromise
- Compliance-ready
- Audit trail

---

### 4\. Flexible (`auth_mode: "flexible"`)

**Description:** User chooses between password or OTP authentication.

**Use Cases:**

- Applications with diverse user base
- Gradual migration to passwordless
- Power users who prefer passwords
- Mobile users who prefer OTP

**User Flow (Password):**

1. User enters email/mobile
2. User enters password
3. Immediate login

**User Flow (OTP):**

1. User enters email/mobile
2. User leaves password field empty
3. OTP sent automatically
4. User enters OTP
5. Login upon verification

**Security Level:** ⭐⭐⭐⭐ (High - depends on user choice)

**Configuration:**

```typescript
{
  auth_mode: "flexible",
  enable_mobile_login: true,
  otp_delivery_method: "email" // or "sms" or "both"
}

```

**Benefits:**

- Maximum flexibility
- User preference
- Smooth migration path
- Best of both worlds

---

## Configuration Guide

### Via Admin Console (Recommended)

1. **Navigate to Clients**
  - Open console: `https://ids.fabrixly.com`
  - Go to "Clients" page
2. **Create/Edit Client**
  - Click "Add Client" or edit existing
  - Navigate to "User Authentication" tab
3. **Configure Authentication**
  - **Authentication Mode**: Select from dropdown
    - Password Only
    - OTP Only (Passwordless)
    - Password + OTP (2FA)
    - Flexible (User Choice)
  - **Enable Mobile Number Login**: Toggle on/off
    - Allows users to login with mobile number instead of email
  - **OTP Delivery Method**: Select delivery channel
    - Email Only
    - SMS Only
    - Both Email & SMS
4. **Save Configuration**

### Via API

**Create Client:**

```bash
POST https://ids.fabrixly.com/api/clients
Authorization: Bearer <token>
Content-Type: application/json

{
  "client_name": "My Application",
  "redirect_uris": ["https://ids.fabrixly.com/callback"],
  "auth_mode": "password_and_otp",
  "enable_mobile_login": true,
  "otp_delivery_method": "email",
  "requires_consent": false
}

```

**Update Client:**

```bash
PUT https://ids.fabrixly.com/api/clients/:client_id
Authorization: Bearer <token>
Content-Type: application/json

{
  "auth_mode": "flexible",
  "enable_mobile_login": true,
  "otp_delivery_method": "both"
}

```

### Via Test Scripts

Quick configuration for testing:

```bash
# Password-only mode
npx ts-node src/scripts/test-password-only.ts

# OTP-only mode
npx ts-node src/scripts/test-otp-only.ts

# 2FA mode
npx ts-node src/scripts/test-2fa.ts

# Flexible mode
npx ts-node src/scripts/test-flexible.ts

# Mobile login
npx ts-node src/scripts/test-mobile-login.ts

# View current config
npx ts-node src/scripts/view-auth-config.ts

```

---

## User Experience

### Login Form Behavior

The login form dynamically adapts based on the configured `auth_mode`:

#### Password Only

```
┌─────────────────────────────┐
│ Email or Mobile Number      │
├─────────────────────────────┤
│ Password (required)         │
├─────────────────────────────┤
│      [ SIGN IN ]            │
└─────────────────────────────┘

```

#### OTP Only

```
┌─────────────────────────────┐
│ Email or Mobile Number      │
├─────────────────────────────┤
│      [ SEND OTP ]           │
└─────────────────────────────┘
        ↓
┌─────────────────────────────┐
│ Enter 6-digit OTP           │
├─────────────────────────────┤
│      [ VERIFY OTP ]         │
└─────────────────────────────┘

```

#### 2FA (Password + OTP)

```
Step 1 of 2:
┌─────────────────────────────┐
│ Email or Mobile Number      │
├─────────────────────────────┤
│ Password                    │
├─────────────────────────────┤
│      [ CONTINUE ]           │
└─────────────────────────────┘
        ↓
Step 2 of 2:
┌─────────────────────────────┐
│ Enter 6-digit OTP           │
├─────────────────────────────┤
│      [ VERIFY OTP ]         │
└─────────────────────────────┘

```

#### Flexible

```
┌─────────────────────────────┐
│ Email or Mobile Number      │
├─────────────────────────────┤
│ Password (or leave empty)   │
├─────────────────────────────┤
│      [ SIGN IN ]            │
└─────────────────────────────┘

```

### Visual Feedback

**Success Messages:**

- "OTP sent to your email"
- "OTP sent to your mobile"
- "Password verified. OTP sent to your email"

**Error Messages:**

- "User not found"
- "Password is required"
- "Invalid password"
- "Invalid or expired OTP"
- "Access Denied: You are not a member of any team authorized for this application"

**Progress Indicators:**

- "Step 1 of 2: Enter your password"
- "Step 2 of 2: Two-Factor Authentication"

---

## API Reference

### Client Configuration Fields

```typescript
interface Client {
  // Authentication Configuration
  auth_mode: 'password' | 'otp' | 'password_and_otp' | 'flexible';
  enable_mobile_login: boolean;
  otp_delivery_method: 'email' | 'sms' | 'both';
  
  // Other fields...
  client_id: string;
  client_secret: string;
  client_name: string;
  redirect_uris: string[];
  requires_consent: boolean;
  skip_team_check: boolean;
}

```

### Authentication Endpoints

**Login Endpoint:**

```
POST /interaction/:uid/login

Body:
{
  "identifier": "user@example.com" | "+1234567890",
  "password": "password123" | "" | "otp"
}

Response:
- Redirect to callback (password/flexible with password)
- Render OTP form (otp/flexible without password/2FA)
- Error message (invalid credentials)

```

**OTP Verification Endpoint:**

```
POST /interaction/:uid/otp

Body:
{
  "identifier": "user@example.com",
  "otp": "123456"
}

Response:
- Redirect to callback (valid OTP)
- Error message (invalid OTP)

```

---

## Testing

### Test Users

**Alice (Example Corp):**

- Email: `alice@examplecorp.com`
- Mobile: `+1234567890`
- Password: `password123`

**Bob (Example Corp):**

- Email: `bob@examplecorp.com`
- Password: `password123`

### Testing Each Mode

#### 1\. Test Password-Only

```bash
# Configure
npx ts-node src/scripts/test-password-only.ts

# Test
1. Go to https://ids.fabrixly.com
2. Click "Login with SSO"
3. Enter: alice@examplecorp.com
4. Enter: password123
5. Click "SIGN IN"
✓ Should login immediately

```

#### 2\. Test OTP-Only

```bash
# Configure
npx ts-node src/scripts/test-otp-only.ts

# Test
1. Go to https://ids.fabrixly.com
2. Click "Login with SSO"
3. Enter: alice@examplecorp.com
4. Click "SEND OTP"
5. Check server console for OTP
6. Enter OTP
7. Click "VERIFY OTP"
✓ Should login after OTP verification

```

#### 3\. Test 2FA

```bash
# Configure
npx ts-node src/scripts/test-2fa.ts

# Test
1. Go to https://ids.fabrixly.com
2. Click "Login with SSO"
3. Enter: alice@examplecorp.com
4. Enter: password123
5. Click "CONTINUE"
6. Check server console for OTP
7. Enter OTP
8. Click "VERIFY OTP"
✓ Should login after both factors

```

#### 4\. Test Flexible

```bash
# Configure
npx ts-node src/scripts/test-flexible.ts

# Test Option A (Password):
1. Enter: alice@examplecorp.com
2. Enter: password123
3. Click "SIGN IN"
✓ Immediate login

# Test Option B (OTP):
1. Enter: alice@examplecorp.com
2. Leave password empty
3. Click "SIGN IN"
4. Check console for OTP
5. Enter OTP
✓ Login after OTP

```

### Finding OTP Codes

OTP codes are logged to the server console:

```
[CommunicationService] Generated OTP: 123456 for user: <user-id>
[CommunicationService] OTP: 123456

```

**Note:** In production, OTPs would be sent via email/SMS, not logged.

---

## Security Considerations

### OTP Security

**OTP Characteristics:**

- **Length:** 6 digits
- **Expiration:** 5 minutes (configurable)
- **Storage:** Hashed in database
- **One-time use:** Invalidated after verification
- **Rate limiting:** Recommended for production

### Password Security

**Requirements:**

- Stored using bcrypt hashing
- Minimum length enforced (configurable)
- Team-based access control
- Session management

### 2FA Security

**Best Practices:**

- Session state stored server-side
- `pendingUserId` cleared after verification
- Time-limited OTP codes
- Separate verification step

### Mobile Login Security

**Considerations:**

- Mobile number verification recommended
- SMS delivery security
- SIM swap protection
- Rate limiting on OTP requests

### Recommendations

1. **Enable 2FA** for high-security applications
2. **Use HTTPS** in production
3. **Implement rate limiting** on OTP endpoints
4. **Monitor failed attempts**
5. **Log authentication events**
6. **Regular security audits**
7. **User education** on phishing

---

## Troubleshooting

### Common Issues

#### OTP Not Received

**Problem:** User doesn't receive OTP

**Solutions:**

1. Check server console for OTP (development)
2. Verify `otp_delivery_method` configuration
3. Check email/SMS service configuration
4. Verify user has email/mobile number
5. Check spam folder (email)

#### Login Form Not Changing

**Problem:** Form doesn't adapt to auth mode

**Solutions:**

1. Clear browser cache
2. Verify client configuration
3. Check `auth_mode` value in database
4. Restart identity server
5. Check browser console for errors

#### 2FA Session Lost

**Problem:** OTP step fails after password

**Solutions:**

1. Check session configuration
2. Verify session middleware
3. Check `pendingUserId` in session
4. Ensure cookies are enabled
5. Check session timeout

#### Mobile Login Not Working

**Problem:** Can't login with mobile number

**Solutions:**

1. Verify `enable_mobile_login` is true
2. Check user has mobile number in database
3. Verify mobile number format (+1234567890)
4. Check identifier field name (should be "identifier")

### Debug Mode

Enable detailed logging:

```typescript
// In src/config/database.ts
export const AppDataSource = new DataSource({
  // ...
  logging: true, // Enable SQL logging
});

```

### Support

For issues or questions:

1. Check server logs
2. Review configuration with `view-auth-config.ts`
3. Test with provided test scripts
4. Check database schema
5. Verify API responses

---

## Migration Guide

### From `enable_otp_login` to `auth_mode`

If upgrading from older version:

**Old Configuration:**

```typescript
{
  enable_otp_login: true
}

```

**New Configuration:**

```typescript
{
  auth_mode: "flexible" // or "otp" for OTP-only
}

```

**Migration Mapping:**

- `enable_otp_login: true` → `auth_mode: "flexible"`
- `enable_otp_login: false` → `auth_mode: "password"`

**Database Migration:**

```bash
# Reset database (development only)
npx ts-node src/scripts/reset-db.ts
npm run start:server

```

---

## Best Practices

### Choosing Auth Mode

| Scenario        | Recommended Mode | Reason                  |
| --------------- | ---------------- | ----------------------- |
| Internal tools  | Password         | Familiar, fast          |
| Consumer app    | OTP Only         | Better UX, no passwords |
| Banking/Finance | 2FA              | Maximum security        |
| Mixed user base | Flexible         | User preference         |
| Mobile-first    | OTP Only         | Mobile-optimized        |
| High compliance | 2FA              | Audit requirements      |

### Configuration Tips

1. **Start with Flexible** \- Allows testing both methods
2. **Enable Mobile Login** \- For better mobile UX
3. **Use Email for OTP** \- More reliable than SMS
4. **Monitor Usage** \- Track which method users prefer
5. **Gradual Migration** \- Move to passwordless gradually

### Performance Optimization

1. **Cache client config** \- Reduce database queries
2. **Rate limit OTP** \- Prevent abuse
3. **Async OTP delivery** \- Don't block login flow
4. **Session optimization** \- Efficient 2FA state management
5. **Database indexing** \- On identifier fields

---

## Appendix

### Configuration Matrix

| Auth Mode          | Password Required | OTP Required | User Choice |
| ------------------ | ----------------- | ------------ | ----------- |
| password           | ✅ Yes             | ❌ No         | ❌ No        |
| otp                | ❌ No              | ✅ Yes        | ❌ No        |
| password\_and\_otp | ✅ Yes             | ✅ Yes        | ❌ No        |
| flexible           | ⚠️ Optional       | ⚠️ Optional  | ✅ Yes       |

### File Reference

**Backend:**

- `src/entities/Client.ts` \- Client schema
- `src/routes/interaction.ts` \- Authentication logic
- `src/views/login.ejs` \- Login UI
- `src/services/CommunicationService.ts` \- OTP service

**Console:**

- `console/src/pages/Clients/index.tsx` \- Client management
- `console/src/api/clients.ts` \- API types

**Scripts:**

- `src/scripts/test-*.ts` \- Test configuration scripts
- `src/scripts/view-auth-config.ts` \- View configuration
- `src/scripts/README.md` \- Scripts documentation

### Version History

- **v1.0.0** \- Initial multi-method authentication release
  - 4 authentication modes
  - Mobile number login
  - Dynamic UI
  - Console configuration

---

**Last Updated:** 2025-11-27  
**Version:** 1.0.0  
**Maintained by:** Fabrixly-IDS Team