0
# Authentication
1

2
Parse Dashboard provides a comprehensive authentication system supporting multiple users, multi-factor authentication (TOTP), read-only access controls, and per-app access restrictions.
3

4
## Capabilities
5

6
### User Configuration
7

8
Configuration for dashboard users and their access permissions:
9

10
```javascript { .api }
11
interface UserConfig {
12
  /**
13
   * Username for login
14
   */
15
  user: string;
16
  
17
  /**
18
   * Password (plain text or bcrypt hash)
19
   * Use bcrypt hash when useEncryptedPasswords is true
20
   */
21
  pass: string;
22
  
23
  /**
24
   * Read-only access flag (optional)
25
   * When true, user cannot modify data
26
   */
27
  readOnly?: boolean;
28
  
29
  /**
30
   * App-specific access restrictions (optional)
31
   * If specified, user can only access these apps
32
   */
33
  apps?: UserAppConfig[];
34
  
35
  /**
36
   * MFA secret (optional)
37
   * Base32-encoded TOTP secret for two-factor authentication
38
   */
39
  mfa?: string;
40
  
41
  /**
42
   * MFA algorithm (optional)
43
   * TOTP algorithm: SHA1, SHA256, SHA512
44
   * Default: SHA1
45
   */
46
  mfaAlgorithm?: string;
47
  
48
  /**
49
   * MFA digits (optional)
50
   * Number of digits in TOTP code
51
   * Default: 6
52
   */
53
  mfaDigits?: number;
54
  
55
  /**
56
   * MFA period (optional)
57
   * TOTP period in seconds
58
   * Default: 30
59
   */
60
  mfaPeriod?: number;
61
}
62

63
interface UserAppConfig {
64
  /**
65
   * App ID the user can access
66
   */
67
  appId: string;
68
  
69
  /**
70
   * Read-only access for this specific app
71
   */
72
  readOnly?: boolean;
73
}
74
```
75

76
### Authentication Class
77

78
Core authentication functionality (internal use):
79

80
```javascript { .api }
81
class Authentication {
82
  /**
83
   * Creates authentication instance
84
   * @param validUsers - Array of valid user configurations
85
   * @param useEncryptedPasswords - Whether passwords are bcrypt hashed
86
   * @param mountPath - Dashboard mount path for redirects
87
   */
88
  constructor(validUsers: UserConfig[], useEncryptedPasswords: boolean, mountPath: string);
89
  
90
  /**
91
   * Initialize authentication middleware
92
   * @param app - Express application instance
93
   * @param options - Authentication options
94
   */
95
  initialize(app: Express.Application, options: AuthOptions): void;
96
  
97
  /**
98
   * Authenticate user credentials
99
   * @param userToTest - User credentials to verify
100
   * @param usernameOnly - Whether to check username only
101
   * @returns Authentication result
102
   */
103
  authenticate(userToTest: any, usernameOnly?: boolean): Promise<AuthResult>;
104
}
105

106
interface AuthOptions {
107
  cookieSessionSecret?: string;
108
  cookieSessionMaxAge?: number;
109
  mountPath?: string;
110
}
111

112
interface AuthResult {
113
  isAuthenticated: boolean;
114
  matchingUsername: string;
115
  otpMissingLength: number | false;
116
  otpValid: boolean;
117
  appsUserHasAccessTo: string[] | null;
118
  isReadOnly: boolean;
119
}
120
```
121

122
### CLI Authentication Helpers
123

124
Interactive utilities for managing users and MFA:
125

126
```javascript { .api }
127
interface CLIHelper {
128
  /**
129
   * Interactive user creation utility
130
   * Prompts for username, password, and generates bcrypt hash
131
   */
132
  createUser(): Promise<void>;
133
  
134
  /**
135
   * Interactive MFA setup utility
136
   * Generates TOTP secret and displays QR code
137
   */
138
  createMFA(): Promise<void>;
139
}
140
```
141

142
**Authentication Examples:**
143

144
```javascript
145
// Basic user authentication
146
const dashboardWithAuth = new ParseDashboard({
147
  apps: [{ /* app config */ }],
148
  users: [
149
    {
150
      user: 'admin',
151
      pass: 'securePassword123'
152
    },
153
    {
154
      user: 'viewer',
155
      pass: 'viewerPassword',
156
      readOnly: true
157
    }
158
  ]
159
});
160

161
// Multi-factor authentication setup
162
const dashboardWithMFA = new ParseDashboard({
163
  apps: [{ /* app config */ }],
164
  users: [
165
    {
166
      user: 'admin',
167
      pass: 'password123',
168
      mfa: 'JBSWY3DPEHPK3PXP',  // Base32 secret
169
      mfaAlgorithm: 'SHA1',
170
      mfaDigits: 6,
171
      mfaPeriod: 30
172
    }
173
  ],
174
  useEncryptedPasswords: false
175
});
176

177
// Bcrypt encrypted passwords
178
const dashboardWithEncryption = new ParseDashboard({
179
  apps: [{ /* app config */ }],
180
  users: [
181
    {
182
      user: 'admin',
183
      pass: '$2b$10$xyz...'  // bcrypt hash
184
    }
185
  ],
186
  useEncryptedPasswords: true
187
});
188

189
// App-specific user access
190
const dashboardWithAppAccess = new ParseDashboard({
191
  apps: [
192
    { appId: 'prod-app', /* ... */ },
193
    { appId: 'dev-app', /* ... */ },
194
    { appId: 'test-app', /* ... */ }
195
  ],
196
  users: [
197
    {
198
      user: 'admin',
199
      pass: 'adminPass'
200
      // Admin has access to all apps
201
    },
202
    {
203
      user: 'developer',
204
      pass: 'devPass',
205
      apps: [
206
        { appId: 'dev-app' },
207
        { appId: 'test-app', readOnly: true }
208
      ]
209
    },
210
    {
211
      user: 'viewer',
212
      pass: 'viewPass',
213
      readOnly: true,
214
      apps: [
215
        { appId: 'prod-app', readOnly: true }
216
      ]
217
    }
218
  ]
219
});
220

221
// Combined MFA and app restrictions
222
const advancedAuth = new ParseDashboard({
223
  apps: [
224
    { appId: 'critical-app', /* ... */ },
225
    { appId: 'normal-app', /* ... */ }
226
  ],
227
  users: [
228
    {
229
      user: 'security-admin',
230
      pass: '$2b$10$hashedPassword...',
231
      mfa: 'JBSWY3DPEHPK3PXP',
232
      apps: [
233
        { appId: 'critical-app' }
234
      ]
235
    },
236
    {
237
      user: 'regular-user',
238
      pass: '$2b$10$anotherHash...',
239
      readOnly: true,
240
      apps: [
241
        { appId: 'normal-app', readOnly: true }
242
      ]
243
    }
244
  ],
245
  useEncryptedPasswords: true
246
});
247
```
248

249
## Interactive User Management
250

251
### Creating Users via CLI
252

253
```bash
254
# Generate user with bcrypt password
255
parse-dashboard --createUser
256

257
# This will prompt for:
258
# - Username
259
# - Password  
260
# - Confirm password
261
# And output bcrypt hash for configuration
262
```
263

264
### Setting up MFA
265

266
```bash
267
# Generate MFA secret and QR code
268
parse-dashboard --createMFA
269

270
# This will:
271
# - Generate a random base32 secret
272
# - Display QR code for scanning with authenticator app
273
# - Show the secret for manual entry
274
# - Provide configuration example
275
```
276

277
## Session Management
278

279
### Session Configuration
280

281
```javascript
282
const dashboard = new ParseDashboard(config, {
283
  cookieSessionSecret: 'your-secret-key-change-in-production',
284
  cookieSessionMaxAge: 7200000  // 2 hours in milliseconds
285
});
286
```
287

288
### Environment Variables for Sessions
289

290
```bash
291
PARSE_DASHBOARD_COOKIE_SESSION_SECRET=your-secret-key
292
PARSE_DASHBOARD_COOKIE_SESSION_MAX_AGE=7200000
293
```
294

295
## Security Considerations
296

297
### Password Security
298

299
```javascript
300
// Recommended: Use bcrypt for password hashing
301
const config = {
302
  users: [
303
    {
304
      user: 'admin',
305
      pass: '$2b$10$N9qo8uLOickgx2ZMRZoMye.Uo3vfx2u4UqOJNcYOCMy0LvP9KN.2u'
306
    }
307
  ],
308
  useEncryptedPasswords: true
309
};
310

311
// Not recommended: Plain text passwords
312
const insecureConfig = {
313
  users: [
314
    {
315
      user: 'admin',
316
      pass: 'plainTextPassword'  // Avoid in production
317
    }
318
  ],
319
  useEncryptedPasswords: false
320
};
321
```
322

323
### Access Control Patterns
324

325
```javascript
326
// Role-based access control
327
const roleBasedConfig = {
328
  apps: [
329
    { appId: 'prod', appName: 'Production' },
330
    { appId: 'staging', appName: 'Staging' },
331
    { appId: 'dev', appName: 'Development' }
332
  ],
333
  users: [
334
    // Super admin - full access
335
    {
336
      user: 'superadmin',
337
      pass: '$2b$10$...',
338
      mfa: 'MFA_SECRET'
339
    },
340
    // Production admin - prod + staging read
341
    {
342
      user: 'prodadmin', 
343
      pass: '$2b$10$...',
344
      apps: [
345
        { appId: 'prod' },
346
        { appId: 'staging', readOnly: true }
347
      ]
348
    },
349
    // Developer - dev full, staging read
350
    {
351
      user: 'developer',
352
      pass: '$2b$10$...',
353
      apps: [
354
        { appId: 'dev' },
355
        { appId: 'staging', readOnly: true }
356
      ]
357
    },
358
    // Viewer - read-only access to specific app
359
    {
360
      user: 'viewer',
361
      pass: '$2b$10$...',
362
      readOnly: true,
363
      apps: [
364
        { appId: 'prod', readOnly: true }
365
      ]
366
    }
367
  ],
368
  useEncryptedPasswords: true
369
};
370
```