0
# Authentication Management
1

2
Authentication flow configuration, execution management, and authenticator configuration.
3

4
## Capabilities
5

6
### Authentication Flows
7

8
Management of authentication flows that define the authentication process.
9

10
```typescript { .api }
11
/**
12
 * Get all authentication flows in the realm
13
 * @returns Array of authentication flow representations
14
 */
15
getFlows(): Promise<AuthenticationFlowRepresentation[]>;
16

17
/**
18
 * Create a new authentication flow
19
 * @param flow - Flow configuration
20
 */
21
createFlow(flow: AuthenticationFlowRepresentation): Promise<void>;
22

23
/**
24
 * Get a specific authentication flow
25
 * @param params - Flow identifier
26
 * @returns Authentication flow representation
27
 */
28
getFlow(params: { flowId: string }): Promise<AuthenticationFlowRepresentation>;
29

30
/**
31
 * Update an existing authentication flow
32
 * @param params - Flow identifier
33
 * @param flow - Updated flow configuration
34
 */
35
updateFlow(params: { flowId: string }, flow: AuthenticationFlowRepresentation): Promise<void>;
36

37
/**
38
 * Delete an authentication flow
39
 * @param params - Flow identifier
40
 */
41
deleteFlow(params: { flowId: string }): Promise<void>;
42

43
/**
44
 * Copy an existing authentication flow
45
 * @param params - Source flow alias and new flow name
46
 */
47
copyFlow(params: { flowAlias: string; newName: string }): Promise<void>;
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
// List all authentication flows
54
const flows = await kcAdminClient.authenticationManagement.getFlows();
55
console.log("Authentication flows:", flows.map(f => f.alias));
56

57
// Create custom authentication flow
58
await kcAdminClient.authenticationManagement.createFlow({
59
  alias: "custom-browser-flow",
60
  description: "Custom browser authentication flow",
61
  providerId: "basic-flow",
62
  topLevel: true,
63
  builtIn: false,
64
});
65

66
// Copy existing flow
67
await kcAdminClient.authenticationManagement.copyFlow({
68
  flowAlias: "browser",
69
  newName: "custom-browser-with-otp",
70
});
71

72
// Get specific flow
73
const browserFlow = await kcAdminClient.authenticationManagement.getFlow({
74
  flowId: "browser-flow-id",
75
});
76

77
// Update flow description
78
await kcAdminClient.authenticationManagement.updateFlow(
79
  { flowId: "custom-flow-id" },
80
  {
81
    description: "Updated: Custom authentication flow with additional security",
82
  }
83
);
84

85
// Delete custom flow
86
await kcAdminClient.authenticationManagement.deleteFlow({
87
  flowId: "custom-flow-id",
88
});
89
```
90

91
### Authentication Executions
92

93
Management of individual authentication steps within flows.
94

95
```typescript { .api }
96
/**
97
 * Get executions for an authentication flow
98
 * @param params - Flow alias
99
 * @returns Array of execution info representations
100
 */
101
getExecutions(params: { flowAlias: string }): Promise<AuthenticationExecutionInfoRepresentation[]>;
102

103
/**
104
 * Add execution to an authentication flow
105
 * @param params - Flow alias
106
 * @param execution - Execution configuration
107
 */
108
addExecution(params: { flowAlias: string }, execution: AuthenticationExecutionRepresentation): Promise<void>;
109

110
/**
111
 * Update execution configuration
112
 * @param params - Execution identifier
113
 * @param execution - Updated execution configuration
114
 */
115
updateExecution(params: { executionId: string }, execution: AuthenticationExecutionInfoRepresentation): Promise<void>;
116

117
/**
118
 * Delete execution from flow
119
 * @param params - Execution identifier
120
 */
121
deleteExecution(params: { executionId: string }): Promise<void>;
122

123
/**
124
 * Move execution up in the flow order
125
 * @param params - Execution identifier
126
 */
127
raiseExecutionPriority(params: { executionId: string }): Promise<void>;
128

129
/**
130
 * Move execution down in the flow order
131
 * @param params - Execution identifier
132
 */
133
lowerExecutionPriority(params: { executionId: string }): Promise<void>;
134
```
135

136
**Usage Examples:**
137

138
```typescript
139
// Get executions for browser flow
140
const executions = await kcAdminClient.authenticationManagement.getExecutions({
141
  flowAlias: "browser",
142
});
143

144
console.log("Browser flow executions:", executions.map(e => e.displayName));
145

146
// Add username/password execution
147
await kcAdminClient.authenticationManagement.addExecution(
148
  { flowAlias: "custom-browser-flow" },
149
  {
150
    provider: "auth-username-password-form",
151
    requirement: "REQUIRED",
152
  }
153
);
154

155
// Add OTP execution
156
await kcAdminClient.authenticationManagement.addExecution(
157
  { flowAlias: "custom-browser-flow" },
158
  {
159
    provider: "auth-otp-form",
160
    requirement: "OPTIONAL",
161
  }
162
);
163

164
// Update execution requirement
165
await kcAdminClient.authenticationManagement.updateExecution(
166
  { executionId: "execution-id" },
167
  {
168
    requirement: "REQUIRED",
169
  }
170
);
171

172
// Reorder executions
173
await kcAdminClient.authenticationManagement.raiseExecutionPriority({
174
  executionId: "otp-execution-id",
175
});
176

177
// Delete execution
178
await kcAdminClient.authenticationManagement.deleteExecution({
179
  executionId: "execution-to-delete",
180
});
181
```
182

183
### Authenticator Configuration
184

185
Management of authenticator configurations and settings.
186

187
```typescript { .api }
188
/**
189
 * Get authenticator providers available in the realm
190
 * @returns Array of authenticator provider representations
191
 */
192
getAuthenticatorProviders(): Promise<AuthenticatorConfigInfoRepresentation[]>;
193

194
/**
195
 * Get authenticator configurations
196
 * @returns Array of authenticator configurations
197
 */
198
getAuthenticatorConfigs(): Promise<AuthenticatorConfigRepresentation[]>;
199

200
/**
201
 * Create authenticator configuration
202
 * @param config - Configuration settings
203
 * @returns Created configuration representation
204
 */
205
createAuthenticatorConfig(config: AuthenticatorConfigRepresentation): Promise<AuthenticatorConfigRepresentation>;
206

207
/**
208
 * Get specific authenticator configuration
209
 * @param params - Configuration identifier
210
 * @returns Authenticator configuration
211
 */
212
getAuthenticatorConfig(params: { configId: string }): Promise<AuthenticatorConfigRepresentation>;
213

214
/**
215
 * Update authenticator configuration
216
 * @param params - Configuration identifier
217
 * @param config - Updated configuration
218
 */
219
updateAuthenticatorConfig(params: {
220
  configId: string;
221
}, config: AuthenticatorConfigRepresentation): Promise<void>;
222

223
/**
224
 * Delete authenticator configuration
225
 * @param params - Configuration identifier
226
 */
227
deleteAuthenticatorConfig(params: { configId: string }): Promise<void>;
228
```
229

230
**Usage Examples:**
231

232
```typescript
233
// Get available authenticator providers
234
const providers = await kcAdminClient.authenticationManagement.getAuthenticatorProviders();
235
console.log("Available authenticators:", providers.map(p => p.displayName));
236

237
// Create OTP authenticator configuration
238
const otpConfig = await kcAdminClient.authenticationManagement.createAuthenticatorConfig({
239
  alias: "mobile-otp-config",
240
  config: {
241
    "otp.policy.type": "totp",
242
    "otp.policy.algorithm": "HmacSHA1",
243
    "otp.policy.initialCounter": "0",
244
    "otp.policy.digits": "6",
245
    "otp.policy.lookAheadWindow": "1",
246
    "otp.policy.period": "30",
247
  },
248
});
249

250
// Get all authenticator configurations
251
const configs = await kcAdminClient.authenticationManagement.getAuthenticatorConfigs();
252
console.log("Authenticator configs:", configs.map(c => c.alias));
253

254
// Update configuration
255
await kcAdminClient.authenticationManagement.updateAuthenticatorConfig(
256
  { configId: otpConfig.id! },
257
  {
258
    alias: "updated-mobile-otp-config",
259
    config: {
260
      "otp.policy.digits": "8", // Change to 8 digits
261
      "otp.policy.period": "60", // Change to 60 seconds
262
    },
263
  }
264
);
265

266
// Delete configuration
267
await kcAdminClient.authenticationManagement.deleteAuthenticatorConfig({
268
  configId: "config-to-delete",
269
});
270
```
271

272
### Required Actions
273

274
Management of required actions that users must complete.
275

276
```typescript { .api }
277
/**
278
 * Get all required actions in the realm
279
 * @returns Array of required action provider representations
280
 */
281
getRequiredActions(): Promise<RequiredActionProviderRepresentation[]>;
282

283
/**
284
 * Get specific required action
285
 * @param params - Required action alias
286
 * @returns Required action provider representation
287
 */
288
getRequiredAction(params: { alias: string }): Promise<RequiredActionProviderRepresentation>;
289

290
/**
291
 * Update required action configuration
292
 * @param params - Required action alias
293
 * @param requiredAction - Updated configuration
294
 */
295
updateRequiredAction(params: {
296
  alias: string;
297
}, requiredAction: RequiredActionProviderRepresentation): Promise<void>;
298

299
/**
300
 * Register new required action
301
 * @param requiredAction - Required action configuration
302
 */
303
registerRequiredAction(requiredAction: RequiredActionProviderRepresentation): Promise<void>;
304

305
/**
306
 * Delete required action
307
 * @param params - Required action alias
308
 */
309
unregisterRequiredAction(params: { alias: string }): Promise<void>;
310
```
311

312
**Usage Examples:**
313

314
```typescript
315
// Get all required actions
316
const requiredActions = await kcAdminClient.authenticationManagement.getRequiredActions();
317
console.log("Required actions:", requiredActions.map(ra => ra.alias));
318

319
// Enable terms and conditions required action
320
await kcAdminClient.authenticationManagement.updateRequiredAction(
321
  { alias: "TERMS_AND_CONDITIONS" },
322
  {
323
    enabled: true,
324
    defaultAction: false,
325
    priority: 20,
326
    config: {
327
      "terms.text": "Please accept our terms and conditions to continue.",
328
    },
329
  }
330
);
331

332
// Configure password update action
333
await kcAdminClient.authenticationManagement.updateRequiredAction(
334
  { alias: "UPDATE_PASSWORD" },
335
  {
336
    enabled: true,
337
    defaultAction: false,
338
    priority: 30,
339
  }
340
);
341

342
// Register custom required action
343
await kcAdminClient.authenticationManagement.registerRequiredAction({
344
  alias: "custom-verification",
345
  name: "Custom Verification",
346
  providerId: "custom-verification-provider",
347
  enabled: true,
348
  defaultAction: false,
349
  priority: 40,
350
  config: {
351
    "verification.method": "email",
352
    "verification.timeout": "300",
353
  },
354
});
355
```
356

357
## Types
358

359
```typescript { .api }
360
/**
361
 * Authentication flow representation
362
 */
363
interface AuthenticationFlowRepresentation {
364
  /** Flow unique identifier */
365
  id?: string;
366
  /** Flow alias (unique name) */
367
  alias?: string;
368
  /** Flow description */
369
  description?: string;
370
  /** Provider ID for flow type */
371
  providerId?: string;
372
  /** Whether this is a top-level flow */
373
  topLevel?: boolean;
374
  /** Whether this is a built-in flow */
375
  builtIn?: boolean;
376
  /** Authentication executions in this flow */
377
  authenticationExecutions?: AuthenticationExecutionExportRepresentation[];
378
}
379

380
/**
381
 * Authentication execution representation
382
 */
383
interface AuthenticationExecutionRepresentation {
384
  /** Authenticator provider */
385
  provider?: string;
386
  /** Execution requirement */
387
  requirement?: "REQUIRED" | "ALTERNATIVE" | "DISABLED" | "CONDITIONAL";
388
  /** Priority order */
389
  priority?: number;
390
  /** Whether this is a user setup allowed */
391
  userSetupAllowed?: boolean;
392
  /** Whether authentication execution is configurable */
393
  configurable?: boolean;
394
  /** Parent flow ID */
395
  parentFlow?: string;
396
}
397

398
/**
399
 * Authentication execution info representation
400
 */
401
interface AuthenticationExecutionInfoRepresentation {
402
  /** Execution ID */
403
  id?: string;
404
  /** Execution requirement */
405
  requirement?: "REQUIRED" | "ALTERNATIVE" | "DISABLED" | "CONDITIONAL";
406
  /** Display name */
407
  displayName?: string;
408
  /** Alias */
409
  alias?: string;
410
  /** Description */
411
  description?: string;
412
  /** Required actions */
413
  requirementChoices?: string[];
414
  /** Whether configurable */
415
  configurable?: boolean;
416
  /** Provider ID */
417
  providerId?: string;
418
  /** Authentication config */
419
  authenticationConfig?: string;
420
  /** Flow ID */
421
  flowId?: string;
422
  /** Priority level */
423
  level?: number;
424
  /** Index */
425
  index?: number;
426
}
427

428
/**
429
 * Authenticator configuration representation
430
 */
431
interface AuthenticatorConfigRepresentation {
432
  /** Configuration ID */
433
  id?: string;
434
  /** Configuration alias */
435
  alias?: string;
436
  /** Configuration settings */
437
  config?: Record<string, string>;
438
}
439

440
/**
441
 * Authenticator config info representation
442
 */
443
interface AuthenticatorConfigInfoRepresentation {
444
  /** Provider name */
445
  name?: string;
446
  /** Display name */
447
  displayName?: string;
448
  /** Provider ID */
449
  providerId?: string;
450
  /** Description */
451
  description?: string;
452
  /** Help text */
453
  helpText?: string;
454
  /** Configuration properties */
455
  properties?: ConfigPropertyRepresentation[];
456
}
457

458
/**
459
 * Required action provider representation
460
 */
461
interface RequiredActionProviderRepresentation {
462
  /** Action alias */
463
  alias?: string;
464
  /** Action name */
465
  name?: string;
466
  /** Provider ID */
467
  providerId?: string;
468
  /** Whether enabled */
469
  enabled?: boolean;
470
  /** Whether default action */
471
  defaultAction?: boolean;
472
  /** Priority */
473
  priority?: number;
474
  /** Configuration */
475
  config?: Record<string, string>;
476
}
477

478
/**
479
 * Configuration property representation
480
 */
481
interface ConfigPropertyRepresentation {
482
  /** Property name */
483
  name?: string;
484
  /** Property label */
485
  label?: string;
486
  /** Help text */
487
  helpText?: string;
488
  /** Property type */
489
  type?: string;
490
  /** Default value */
491
  defaultValue?: any;
492
  /** Available options */
493
  options?: string[];
494
  /** Whether secret */
495
  secret?: boolean;
496
}
497
```
498

499
## Authentication Flow Patterns
500

501
Common patterns for authentication flow configuration:
502

503
```typescript
504
// Pattern 1: Custom MFA flow
505
await kcAdminClient.authenticationManagement.createFlow({
506
  alias: "mfa-flow",
507
  description: "Multi-factor authentication flow",
508
  providerId: "basic-flow",
509
  topLevel: true,
510
});
511

512
// Add username/password step
513
await kcAdminClient.authenticationManagement.addExecution(
514
  { flowAlias: "mfa-flow" },
515
  {
516
    provider: "auth-username-password-form",
517
    requirement: "REQUIRED",
518
  }
519
);
520

521
// Add OTP step
522
await kcAdminClient.authenticationManagement.addExecution(
523
  { flowAlias: "mfa-flow" },
524
  {
525
    provider: "auth-otp-form", 
526
    requirement: "REQUIRED",
527
  }
528
);
529

530
// Pattern 2: Social + Username/Password alternative
531
await kcAdminClient.authenticationManagement.createFlow({
532
  alias: "social-or-local",
533
  description: "Social login or local authentication",
534
  providerId: "basic-flow",
535
  topLevel: true,
536
});
537

538
// Create identity provider redirector subflow
539
await kcAdminClient.authenticationManagement.addExecution(
540
  { flowAlias: "social-or-local" },
541
  {
542
    provider: "identity-provider-redirector",
543
    requirement: "ALTERNATIVE",
544
  }
545
);
546

547
// Add username/password as alternative
548
await kcAdminClient.authenticationManagement.addExecution(
549
  { flowAlias: "social-or-local" },
550
  {
551
    provider: "auth-username-password-form",
552
    requirement: "ALTERNATIVE",
553
  }
554
);
555

556
// Pattern 3: Conditional OTP flow
557
await kcAdminClient.authenticationManagement.createFlow({
558
  alias: "conditional-otp",
559
  description: "OTP required based on conditions",
560
  providerId: "basic-flow",
561
  topLevel: true,
562
});
563

564
// Add conditional OTP execution
565
await kcAdminClient.authenticationManagement.addExecution(
566
  { flowAlias: "conditional-otp" },
567
  {
568
    provider: "conditional-user-configured",
569
    requirement: "REQUIRED",
570
  }
571
);
572

573
await kcAdminClient.authenticationManagement.addExecution(
574
  { flowAlias: "conditional-otp" },
575
  {
576
    provider: "auth-otp-form",
577
    requirement: "REQUIRED",
578
  }
579
);
580
```