0
# Configuration
1

2
Comprehensive configuration options for both UserManager and OidcClient with extensive customization capabilities for authentication flows, token management, and provider integration.
3

4
## Capabilities
5

6
### UserManager Settings
7

8
Extended configuration for UserManager including popup, silent renewal, and session monitoring options.
9

10
```typescript { .api }
11
/**
12
 * The settings used to configure the UserManager
13
 */
14
interface UserManagerSettings extends OidcClientSettings {
15
  // Popup flow configuration
16
  /** The URL for the page containing the call to signinPopupCallback */
17
  popup_redirect_uri?: string;
18
  /** The URL for the page containing the call to signoutPopupCallback */
19
  popup_post_logout_redirect_uri?: string;
20
  /** Features parameter for window.open popup (default: { location: false, toolbar: false, height: 640 }) */
21
  popupWindowFeatures?: PopupWindowFeatures;
22
  /** Target parameter for window.open popup (default: "_blank") */
23
  popupWindowTarget?: string;
24
  
25
  // Redirect flow configuration
26
  /** Window.location method used to redirect (default: "assign") */
27
  redirectMethod?: "replace" | "assign";
28
  /** Target window being redirected (default: "self") */
29
  redirectTarget?: "top" | "self";
30

31
  // Silent flow configuration
32
  /** The URL for the page containing the silent renew handler */
33
  silent_redirect_uri?: string;
34
  /** Timeout for silent renew requests in seconds (default: 10) */
35
  silentRequestTimeoutInSeconds?: number;
36
  /** Enable automatic silent token renewal (default: true) */
37
  automaticSilentRenew?: boolean;
38
  /** Validate user.profile.sub in silent renew calls (default: true) */
39
  validateSubOnSilentRenew?: boolean;
40
  /** Include id_token as id_token_hint in silent renew calls (default: false) */
41
  includeIdTokenInSilentRenew?: boolean;
42

43
  // IFrame configuration
44
  /** Target origin for postMessage inside iframe (default: window.location.origin) */
45
  iframeNotifyParentOrigin?: string;
46
  /** Script origin to check during message callback (default: window.location.origin) */
47
  iframeScriptOrigin?: string;
48

49
  // Session monitoring
50
  /** Enable session monitoring for signout events (default: false) */
51
  monitorSession?: boolean;
52
  /** Monitor anonymous sessions (default: false) */
53
  monitorAnonymousSession?: boolean;
54
  /** Interval in seconds to check session (default: 2) */
55
  checkSessionIntervalInSeconds?: number;
56
  /** Response type for session status queries */
57
  query_status_response_type?: string;
58
  /** Stop session checking on error (default: true) */
59
  stopCheckSessionOnError?: boolean;
60

61
  // Token management
62
  /** Token types to revoke on signout (default: ["access_token", "refresh_token"]) */
63
  revokeTokenTypes?: ("access_token" | "refresh_token")[];
64
  /** Invoke revocation endpoint on signout (default: false) */
65
  revokeTokensOnSignout?: boolean;
66
  /** Include id_token as id_token_hint in silent signout (default: false) */
67
  includeIdTokenInSilentSignout?: boolean;
68
  /** Seconds before access token expiry to raise expiring event (default: 60) */
69
  accessTokenExpiringNotificationTimeInSeconds?: number;
70

71
  // Storage
72
  /** Storage for user data (default: window.sessionStorage) */
73
  userStore?: StateStore;
74
}
75

76
interface PopupWindowFeatures {
77
  /** Show location bar in popup */
78
  location?: boolean;
79
  /** Show toolbar in popup */
80
  toolbar?: boolean;
81
  /** Popup window height */
82
  height?: number;
83
  /** Popup window width */
84
  width?: number;
85
  /** Popup window left position */
86
  left?: number;
87
  /** Popup window top position */
88
  top?: number;
89
  /** Auto-close popup after seconds (-1 to disable) */
90
  closePopupWindowAfterInSeconds?: number;
91
}
92
```
93

94
### OidcClient Settings
95

96
Core configuration for OIDC/OAuth2 protocol communication.
97

98
```typescript { .api }
99
/**
100
 * The settings used to configure the OidcClient
101
 */
102
interface OidcClientSettings {
103
  // Required settings
104
  /** The URL of the OIDC/OAuth2 provider */
105
  authority: string;
106
  /** Your client application's identifier */
107
  client_id: string;
108
  /** The redirect URI to receive responses */
109
  redirect_uri: string;
110

111
  // Provider configuration
112
  /** Custom metadata URL if different from authority */
113
  metadataUrl?: string;
114
  /** Provide metadata when CORS is not available on discovery endpoint */
115
  metadata?: Partial<OidcMetadata>;
116
  /** Additional values to seed discovery results */
117
  metadataSeed?: Partial<OidcMetadata>;
118
  /** Signing keys when CORS is not available on jwks_uri */
119
  signingKeys?: SigningKey[];
120

121
  // OAuth2/OIDC parameters
122
  /** Response type requested (default: "code") */
123
  response_type?: string;
124
  /** Scope requested (default: "openid") */
125
  scope?: string;
126
  /** Post logout redirect URI */
127
  post_logout_redirect_uri?: string;
128
  /** Client secret for confidential clients */
129
  client_secret?: string;
130
  
131
  // Client authentication
132
  /** Client authentication method (default: "client_secret_post") */
133
  client_authentication?: "client_secret_basic" | "client_secret_post";
134

135
  // Optional protocol parameters
136
  /** Force user authentication prompt */
137
  prompt?: string;
138
  /** UI display mode */
139
  display?: string;
140
  /** Maximum authentication age in seconds */
141
  max_age?: number;
142
  /** Preferred languages for authentication UI */
143
  ui_locales?: string;
144
  /** Requested Authentication Context Class Reference values */
145
  acr_values?: string;
146
  /** Resource indicators for requested access tokens */
147
  resource?: string | string[];
148
  /** Response mode (query, fragment) */
149
  response_mode?: "query" | "fragment";
150

151
  // Claims processing
152
  /** Remove optional OIDC protocol claims from profile (default: true) */
153
  filterProtocolClaims?: boolean | string[];
154
  /** Load additional user info from userinfo endpoint (default: false) */
155
  loadUserInfo?: boolean;
156
  /** Strategy for merging userinfo claims with id_token claims */
157
  mergeClaimsStrategy?: { array: "replace" | "merge" };
158

159
  // Request customization
160
  /** Additional query parameters for authorization requests */
161
  extraQueryParams?: Record<string, string | number | boolean>;
162
  /** Additional parameters for token requests */
163
  extraTokenParams?: Record<string, unknown>;
164
  /** Additional headers for requests */
165
  extraHeaders?: Record<string, ExtraHeader>;
166

167
  // Storage and state management
168
  /** Storage for request state (default: window.localStorage) */
169
  stateStore?: StateStore;
170
  /** Age in seconds for abandoned state cleanup (default: 900) */
171
  staleStateAgeInSeconds?: number;
172

173
  // Security features
174
  /** DPoP (Demonstration of Proof-of-Possession) settings */
175
  dpop?: DPoPSettings;
176
  /** Disable PKCE validation (default: false) */
177
  disablePKCE?: boolean;
178
  /** Fetch credentials mode (default: "same-origin") */
179
  fetchRequestCredentials?: RequestCredentials;
180

181
  // Token revocation
182
  /** Additional content types for revocation endpoint responses */
183
  revokeTokenAdditionalContentTypes?: string[];
184
}
185

186
type ExtraHeader = string | (() => string);
187

188
interface DPoPSettings {
189
  /** Bind DPoP key to authorization code */
190
  bind_authorization_code?: boolean;
191
  /** Storage for DPoP state */
192
  store: DPoPStore;
193
}
194

195
type SigningKey = Record<string, string | string[]>;
196
```
197

198
### Configuration Store Classes
199

200
Immutable configuration stores with applied defaults.
201

202
```typescript { .api }
203
/**
204
 * UserManager settings with defaults applied
205
 */
206
class UserManagerSettingsStore extends OidcClientSettingsStore {
207
  constructor(args: UserManagerSettings);
208
  
209
  // All UserManagerSettings properties as readonly
210
  readonly popup_redirect_uri: string;
211
  readonly popup_post_logout_redirect_uri: string | undefined;
212
  readonly popupWindowFeatures: PopupWindowFeatures;
213
  readonly popupWindowTarget: string;
214
  readonly redirectMethod: "replace" | "assign";
215
  readonly redirectTarget: "top" | "self";
216
  
217
  readonly iframeNotifyParentOrigin: string | undefined;
218
  readonly iframeScriptOrigin: string | undefined;
219
  
220
  readonly silent_redirect_uri: string;
221
  readonly silentRequestTimeoutInSeconds: number;
222
  readonly automaticSilentRenew: boolean;
223
  readonly validateSubOnSilentRenew: boolean;
224
  readonly includeIdTokenInSilentRenew: boolean;
225
  
226
  readonly monitorSession: boolean;
227
  readonly monitorAnonymousSession: boolean;
228
  readonly checkSessionIntervalInSeconds: number;
229
  readonly query_status_response_type: string;
230
  readonly stopCheckSessionOnError: boolean;
231
  
232
  readonly revokeTokenTypes: ("access_token" | "refresh_token")[];
233
  readonly revokeTokensOnSignout: boolean;
234
  readonly includeIdTokenInSilentSignout: boolean;
235
  
236
  readonly accessTokenExpiringNotificationTimeInSeconds: number;
237
  readonly userStore: StateStore;
238
}
239

240
/**
241
 * OidcClient settings with defaults applied
242
 */
243
class OidcClientSettingsStore {
244
  constructor(args: OidcClientSettings);
245
  
246
  // All OidcClientSettings properties as readonly
247
  readonly authority: string;
248
  readonly metadataUrl?: string;
249
  readonly metadata?: Partial<OidcMetadata>;
250
  readonly metadataSeed?: Partial<OidcMetadata>;
251
  readonly signingKeys?: SigningKey[];
252
  
253
  readonly client_id: string;
254
  readonly client_secret?: string;
255
  readonly response_type: string;
256
  readonly scope: string;
257
  readonly redirect_uri: string;
258
  readonly post_logout_redirect_uri?: string;
259
  readonly client_authentication: "client_secret_basic" | "client_secret_post";
260
  
261
  readonly prompt?: string;
262
  readonly display?: string;
263
  readonly max_age?: number;
264
  readonly ui_locales?: string;
265
  readonly acr_values?: string;
266
  readonly resource?: string | string[];
267
  readonly response_mode?: "query" | "fragment";
268
  
269
  readonly filterProtocolClaims: boolean | string[];
270
  readonly loadUserInfo: boolean;
271
  readonly staleStateAgeInSeconds: number;
272
  readonly mergeClaimsStrategy: { array: "replace" | "merge" };
273
  
274
  readonly stateStore: StateStore;
275
  readonly extraQueryParams?: Record<string, string | number | boolean>;
276
  readonly extraTokenParams?: Record<string, unknown>;
277
  readonly extraHeaders?: Record<string, ExtraHeader>;
278
  
279
  readonly dpop?: DPoPSettings;
280
  readonly revokeTokenAdditionalContentTypes: string[];
281
  readonly disablePKCE: boolean;
282
  readonly fetchRequestCredentials: RequestCredentials;
283
}
284
```
285

286
### OIDC Provider Metadata
287

288
Structure for OIDC provider configuration.
289

290
```typescript { .api }
291
/**
292
 * OIDC provider metadata from discovery document
293
 */
294
interface OidcMetadata {
295
  /** The authorization server's issuer identifier */
296
  issuer: string;
297
  /** URL of the authorization endpoint */
298
  authorization_endpoint: string;
299
  /** URL of the token endpoint */
300
  token_endpoint: string;
301
  /** URL of the userinfo endpoint */
302
  userinfo_endpoint?: string;
303
  /** URL of the end session endpoint */
304
  end_session_endpoint?: string;
305
  /** URL of the check session iframe */
306
  check_session_iframe?: string;
307
  /** URL of the revocation endpoint */
308
  revocation_endpoint?: string;
309
  /** URL of the introspection endpoint */
310
  introspection_endpoint?: string;
311
  /** URL of the jwks_uri */
312
  jwks_uri: string;
313
  /** URL of the registration endpoint */
314
  registration_endpoint?: string;
315
  
316
  /** Supported scopes */
317
  scopes_supported?: string[];
318
  /** Supported response types */
319
  response_types_supported: string[];
320
  /** Supported response modes */
321
  response_modes_supported?: string[];
322
  /** Supported grant types */
323
  grant_types_supported?: string[];
324
  /** Supported subject types */
325
  subject_types_supported: string[];
326
  /** Supported ID token signing algorithms */
327
  id_token_signing_alg_values_supported: string[];
328
  /** Supported ID token encryption algorithms */
329
  id_token_encryption_alg_values_supported?: string[];
330
  /** Supported ID token encryption encoding algorithms */
331
  id_token_encryption_enc_values_supported?: string[];
332
  /** Supported userinfo signing algorithms */
333
  userinfo_signing_alg_values_supported?: string[];
334
  /** Supported userinfo encryption algorithms */
335
  userinfo_encryption_alg_values_supported?: string[];
336
  /** Supported userinfo encryption encoding algorithms */
337
  userinfo_encryption_enc_values_supported?: string[];
338
  /** Supported request object signing algorithms */
339
  request_object_signing_alg_values_supported?: string[];
340
  /** Supported request object encryption algorithms */
341
  request_object_encryption_alg_values_supported?: string[];
342
  /** Supported request object encryption encoding algorithms */
343
  request_object_encryption_enc_values_supported?: string[];
344
  /** Supported token endpoint authentication methods */
345
  token_endpoint_auth_methods_supported?: string[];
346
  /** Supported token endpoint authentication signing algorithms */
347
  token_endpoint_auth_signing_alg_values_supported?: string[];
348
  /** Supported display values */
349
  display_values_supported?: string[];
350
  /** Supported claim types */
351
  claim_types_supported?: string[];
352
  /** Supported claims */
353
  claims_supported?: string[];
354
  /** Whether claims parameter is supported */
355
  claims_parameter_supported?: boolean;
356
  /** Whether request parameter is supported */
357
  request_parameter_supported?: boolean;
358
  /** Whether request_uri parameter is supported */
359
  request_uri_parameter_supported?: boolean;
360
  /** Whether TLS client certificate bound access tokens are supported */
361
  tls_client_certificate_bound_access_tokens?: boolean;
362
  /** Supported revocation endpoint authentication methods */
363
  revocation_endpoint_auth_methods_supported?: string[];
364
  /** Supported revocation endpoint authentication signing algorithms */
365
  revocation_endpoint_auth_signing_alg_values_supported?: string[];
366
  /** Supported introspection endpoint authentication methods */
367
  introspection_endpoint_auth_methods_supported?: string[];
368
  /** Supported introspection endpoint authentication signing algorithms */
369
  introspection_endpoint_auth_signing_alg_values_supported?: string[];
370
  /** Supported PKCE code challenge methods */
371
  code_challenge_methods_supported?: string[];
372
}
373
```
374

375
## Configuration Examples
376

377
### Basic Configuration
378

379
```typescript
380
import { UserManager } from "oidc-client-ts";
381

382
const userManager = new UserManager({
383
  // Required settings
384
  authority: "https://demo.identityserver.io",
385
  client_id: "interactive.public",
386
  redirect_uri: "http://localhost:3000/callback",
387
  
388
  // Basic OAuth2/OIDC settings
389
  response_type: "code",
390
  scope: "openid profile email",
391
  post_logout_redirect_uri: "http://localhost:3000",
392
});
393
```
394

395
### Production Configuration
396

397
```typescript
398
import { UserManager, WebStorageStateStore } from "oidc-client-ts";
399

400
const userManager = new UserManager({
401
  // Provider configuration
402
  authority: "https://your-oidc-provider.com",
403
  client_id: "your-production-client-id",
404
  redirect_uri: "https://your-app.com/auth/callback",
405
  post_logout_redirect_uri: "https://your-app.com",
406
  
407
  // Flow configuration
408
  response_type: "code",
409
  scope: "openid profile email api1 api2",
410
  
411
  // Popup flow
412
  popup_redirect_uri: "https://your-app.com/auth/popup-callback",
413
  popup_post_logout_redirect_uri: "https://your-app.com",
414
  popupWindowFeatures: {
415
    location: false,
416
    toolbar: false,
417
    width: 500,
418
    height: 600,
419
    left: 100,
420
    top: 100,
421
  },
422
  
423
  // Silent renewal
424
  silent_redirect_uri: "https://your-app.com/auth/silent-callback",
425
  automaticSilentRenew: true,
426
  silentRequestTimeoutInSeconds: 10,
427
  includeIdTokenInSilentRenew: true,
428
  
429
  // Session monitoring
430
  monitorSession: true,
431
  checkSessionIntervalInSeconds: 2,
432
  
433
  // Token management
434
  revokeTokensOnSignout: true,
435
  revokeTokenTypes: ["access_token", "refresh_token"],
436
  accessTokenExpiringNotificationTimeInSeconds: 60,
437
  
438
  // Storage configuration
439
  userStore: new WebStorageStateStore({ store: window.localStorage }),
440
  stateStore: new WebStorageStateStore({ 
441
    store: window.sessionStorage,
442
    prefix: "oidc."
443
  }),
444
  
445
  // Security
446
  filterProtocolClaims: true,
447
  loadUserInfo: true,
448
  
449
  // Custom parameters
450
  extraQueryParams: {
451
    tenant: "your-tenant-id",
452
  },
453
  
454
  // Custom headers
455
  extraHeaders: {
456
    "X-Custom-Header": "your-value",
457
  },
458
});
459
```
460

461
### Enterprise Configuration with Custom Metadata
462

463
```typescript
464
import { UserManager } from "oidc-client-ts";
465

466
const userManager = new UserManager({
467
  authority: "https://enterprise-sso.company.com",
468
  client_id: "enterprise-app",
469
  redirect_uri: "https://app.company.com/auth/callback",
470
  
471
  // Custom metadata when discovery is not available
472
  metadata: {
473
    issuer: "https://enterprise-sso.company.com",
474
    authorization_endpoint: "https://enterprise-sso.company.com/oauth/authorize",
475
    token_endpoint: "https://enterprise-sso.company.com/oauth/token",
476
    userinfo_endpoint: "https://enterprise-sso.company.com/oauth/userinfo",
477
    end_session_endpoint: "https://enterprise-sso.company.com/oauth/logout",
478
    jwks_uri: "https://enterprise-sso.company.com/.well-known/jwks",
479
    response_types_supported: ["code"],
480
    subject_types_supported: ["public"],
481
    id_token_signing_alg_values_supported: ["RS256"],
482
  },
483
  
484
  // Enterprise-specific settings
485
  client_authentication: "client_secret_basic",
486
  response_type: "code",
487
  scope: "openid profile email groups",
488
  
489
  // Security requirements
490
  acr_values: "urn:mace:incommon:iap:silver",
491
  max_age: 3600,
492
  
493
  // Custom authentication parameters
494
  extraQueryParams: {
495
    domain_hint: "company.com",
496
    prompt: "select_account",
497
  },
498
  
499
  // Network configuration
500
  fetchRequestCredentials: "include", // Send cookies for SSO
501
  
502
  // Claims processing
503
  filterProtocolClaims: ["nbf", "jti", "auth_time", "nonce"],
504
  loadUserInfo: true,
505
  mergeClaimsStrategy: { array: "merge" },
506
});
507
```
508

509
### Azure AD Configuration
510

511
```typescript
512
import { UserManager } from "oidc-client-ts";
513

514
const userManager = new UserManager({
515
  authority: "https://login.microsoftonline.com/your-tenant-id/v2.0",
516
  client_id: "your-azure-app-id",
517
  redirect_uri: "http://localhost:3000/auth/callback",
518
  post_logout_redirect_uri: "http://localhost:3000",
519
  
520
  response_type: "code",
521
  scope: "openid profile email User.Read",
522
  
523
  // Azure AD specific parameters
524
  extraQueryParams: {
525
    resource: "https://graph.microsoft.com",
526
    prompt: "select_account",
527
  },
528
  
529
  // Token configuration
530
  automaticSilentRenew: true,
531
  silent_redirect_uri: "http://localhost:3000/auth/silent-callback",
532
  
533
  // Azure AD metadata override (optional)
534
  metadataSeed: {
535
    end_session_endpoint: "https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/logout",
536
  },
537
});
538
```