0
# OIDC Protocol Client
1

2
Low-level OIDC/OAuth2 protocol support providing raw protocol implementation for authorization and token endpoints. Use this class when you need direct protocol control without the additional management features of UserManager.
3

4
## Capabilities
5

6
### OidcClient Class
7

8
Provides the raw OIDC/OAuth2 protocol support for authorization and end session endpoints.
9

10
```typescript { .api }
11
/**
12
 * Provides raw OIDC/OAuth2 protocol support for authorization and end session endpoints.
13
 * Only use this class if you simply want protocol support without the additional
14
 * management features of the UserManager class.
15
 */
16
class OidcClient {
17
  constructor(settings: OidcClientSettings);
18
  constructor(settings: OidcClientSettingsStore, metadataService: MetadataService);
19
  
20
  /** The settings used to configure the OidcClient */
21
  readonly settings: OidcClientSettingsStore;
22
  /** Service for retrieving OIDC provider metadata */
23
  readonly metadataService: MetadataService;
24
}
25
```
26

27
### Authorization Flow Operations
28

29
#### Create Signin Request
30

31
Create an authorization request for the OIDC provider.
32

33
```typescript { .api }
34
/**
35
 * Create a signin request to send to the authorization endpoint
36
 * @param args - Arguments for creating the signin request
37
 * @returns Promise containing the signin request
38
 */
39
createSigninRequest(args: CreateSigninRequestArgs): Promise<SigninRequest>;
40

41
interface CreateSigninRequestArgs {
42
  /** Override the redirect URI */
43
  redirect_uri?: string;
44
  /** Override the response type */
45
  response_type?: string;
46
  /** Override the scope */
47
  scope?: string;
48
  /** DPoP JWT key thumbprint for binding */
49
  dpopJkt?: string;
50
  /** Custom state data to round-trip */
51
  state?: unknown;
52
  
53
  // Optional OIDC parameters
54
  nonce?: string;
55
  prompt?: string;
56
  display?: string;
57
  max_age?: number;
58
  ui_locales?: string;
59
  id_token_hint?: string;
60
  login_hint?: string;
61
  acr_values?: string;
62
  resource?: string | string[];
63
  
64
  // Request object parameters
65
  request?: string;
66
  request_uri?: string;
67
  request_type?: string;
68
  
69
  // Additional parameters
70
  extraQueryParams?: Record<string, string | number | boolean>;
71
  extraTokenParams?: Record<string, unknown>;
72
  url_state?: boolean;
73
}
74

75
class SigninRequest {
76
  constructor(args: SigninRequestCreateArgs);
77
  
78
  /** The complete authorization URL */
79
  readonly url: string;
80
  /** The state parameter for this request */
81
  readonly state: State;
82
}
83
```
84

85
#### Process Signin Response
86

87
Process the callback response from the authorization endpoint.
88

89
```typescript { .api }
90
/**
91
 * Process the response from the authorization endpoint
92
 * @param url - The callback URL containing the authorization response
93
 * @returns Promise containing the signin response
94
 */
95
processSigninResponse(url: string): Promise<SigninResponse>;
96

97
class SigninResponse {
98
  constructor(url: string);
99
  
100
  /** The authorization code (for code flow) */
101
  readonly code?: string;
102
  /** The state parameter from the request */
103
  readonly state?: string;
104
  /** Error code if the request failed */
105
  readonly error?: string;
106
  /** Error description if available */
107
  readonly error_description?: string;
108
  /** Session state for session management */
109
  readonly session_state?: string;
110
  
111
  /** The access token (for implicit flow) */
112
  readonly access_token?: string;
113
  /** The ID token */
114
  readonly id_token?: string;
115
  /** The token type */
116
  readonly token_type?: string;
117
  /** The scope granted by the authorization server */
118
  readonly scope?: string;
119
  /** Token expiration time in seconds */
120
  readonly expires_in?: number;
121
  
122
  /** The user profile extracted from the ID token */
123
  readonly profile?: UserProfile;
124
  /** When the access token expires */
125
  readonly expires_at?: number;
126
  /** Whether the access token has expired */
127
  readonly expired: boolean;
128
  /** Array of granted scopes */
129
  readonly scopes: string[];
130
}
131
```
132

133
### Token Operations
134

135
#### Use Refresh Token
136

137
Exchange a refresh token for new tokens.
138

139
```typescript { .api }
140
/**
141
 * Use a refresh token to obtain a new access token
142
 * @param args - Arguments for the refresh token request
143
 * @returns Promise containing the token response
144
 */
145
useRefreshToken(args: UseRefreshTokenArgs): Promise<SigninResponse>;
146

147
interface UseRefreshTokenArgs {
148
  /** Override the redirect URI */
149
  redirect_uri?: string;
150
  /** Resource indicators for the requested access token */
151
  resource?: string | string[];
152
  /** Additional parameters for the token request */
153
  extraTokenParams?: Record<string, unknown>;
154
  /** Request timeout in seconds */
155
  timeoutInSeconds?: number;
156
  /** The refresh state containing the refresh token */
157
  state: RefreshState;
158
  /** Additional headers for the token request */
159
  extraHeaders?: Record<string, ExtraHeader>;
160
}
161

162
interface RefreshState {
163
  /** The refresh token */
164
  refresh_token: string;
165
  /** The ID token hint */
166
  id_token_hint?: string;
167
  /** Session state */
168
  session_state?: string;
169
  /** Custom data */
170
  data?: unknown;
171
}
172
```
173

174
#### Resource Owner Password Credentials
175

176
Perform resource owner password credentials grant (not recommended for browser apps).
177

178
```typescript { .api }
179
/**
180
 * Process resource owner password credentials (ROPC) grant
181
 * @param args - Username and password credentials
182
 * @returns Promise containing the token response
183
 */
184
processResourceOwnerPasswordCredentials(args: ProcessResourceOwnerPasswordCredentialsArgs): Promise<SigninResponse>;
185

186
interface ProcessResourceOwnerPasswordCredentialsArgs {
187
  /** The username */
188
  username: string;
189
  /** The password */
190
  password: string;
191
  /** Skip loading user info from the userinfo endpoint */
192
  skipUserInfo?: boolean;
193
  /** Additional parameters for the token request */
194
  extraTokenParams?: Record<string, unknown>;
195
}
196
```
197

198
### Signout Operations
199

200
#### Create Signout Request
201

202
Create an end session request.
203

204
```typescript { .api }
205
/**
206
 * Create a signout request to send to the end session endpoint
207
 * @param args - Arguments for creating the signout request (optional)
208
 * @returns Promise containing the signout request
209
 */
210
createSignoutRequest(args?: CreateSignoutRequestArgs): Promise<SignoutRequest>;
211

212
interface CreateSignoutRequestArgs {
213
  /** Custom state data to round-trip */
214
  state?: unknown;
215
  /** ID token hint for the signout request */
216
  id_token_hint?: string;
217
  /** Override the post logout redirect URI */
218
  post_logout_redirect_uri?: string;
219
  /** Additional query parameters for the end session request */
220
  extraQueryParams?: Record<string, string | number | boolean>;
221
  /** Custom URL state parameter */
222
  url_state?: boolean;
223
}
224

225
class SignoutRequest {
226
  constructor(args: SignoutRequestArgs);
227
  
228
  /** The complete end session URL */
229
  readonly url: string;
230
  /** The state parameter for this request */
231
  readonly state?: State;
232
}
233
```
234

235
#### Process Signout Response
236

237
Process the callback response from the end session endpoint.
238

239
```typescript { .api }
240
/**
241
 * Process the response from the end session endpoint
242
 * @param url - The callback URL containing the signout response
243
 * @returns Promise containing the signout response
244
 */
245
processSignoutResponse(url: string): Promise<SignoutResponse>;
246

247
class SignoutResponse {
248
  constructor(url: string);
249
  
250
  /** The state parameter from the request */
251
  readonly state?: string;
252
  /** Error code if the request failed */
253
  readonly error?: string;
254
  /** Error description if available */
255
  readonly error_description?: string;
256
}
257
```
258

259
### Usage Examples
260

261
#### Basic Authorization Code Flow
262

263
```typescript
264
import { OidcClient } from "oidc-client-ts";
265

266
const client = new OidcClient({
267
  authority: "https://demo.identityserver.io",
268
  client_id: "interactive.public",
269
  redirect_uri: "http://localhost:5000/callback",
270
  response_type: "code",
271
  scope: "openid profile email",
272
});
273

274
// Create signin request
275
const signinRequest = await client.createSigninRequest({
276
  state: { returnUrl: "/dashboard" },
277
});
278

279
// Redirect user to authorization endpoint
280
window.location.href = signinRequest.url;
281

282
// In callback handler
283
const signinResponse = await client.processSigninResponse(window.location.href);
284
if (signinResponse.error) {
285
  console.error("Authorization failed:", signinResponse.error_description);
286
} else {
287
  console.log("Authorization successful:", signinResponse.profile);
288
}
289
```
290

291
#### Token Refresh
292

293
```typescript
294
// Assuming you have a refresh token from a previous authentication
295
const refreshState = {
296
  refresh_token: "your-refresh-token",
297
  id_token_hint: "previous-id-token",
298
};
299

300
try {
301
  const refreshResponse = await client.useRefreshToken({
302
    state: refreshState,
303
    resource: ["api1", "api2"],
304
  });
305
  
306
  console.log("Tokens refreshed:", {
307
    access_token: refreshResponse.access_token,
308
    expires_in: refreshResponse.expires_in,
309
  });
310
} catch (error) {
311
  console.error("Token refresh failed:", error);
312
}
313
```
314

315
#### End Session Flow
316

317
```typescript
318
// Create signout request
319
const signoutRequest = await client.createSignoutRequest({
320
  id_token_hint: "current-id-token",
321
  state: { message: "User initiated signout" },
322
});
323

324
// Redirect to end session endpoint
325
window.location.href = signoutRequest.url;
326

327
// In signout callback handler
328
const signoutResponse = await client.processSignoutResponse(window.location.href);
329
if (signoutResponse.error) {
330
  console.error("Signout error:", signoutResponse.error_description);
331
} else {
332
  console.log("Signout successful");
333
}
334
```
335

336
#### Custom Token Request
337

338
```typescript
339
// Create signin request with custom parameters
340
const signinRequest = await client.createSigninRequest({
341
  scope: "openid profile email offline_access",
342
  acr_values: "urn:mace:incommon:iap:silver",
343
  login_hint: "user@example.com",
344
  max_age: 3600,
345
  extraQueryParams: {
346
    tenant: "contoso",
347
    domain_hint: "contoso.com",
348
  },
349
  extraTokenParams: {
350
    resource: "https://graph.microsoft.com",
351
  },
352
});
353
```
354

355
### Integration with MetadataService
356

357
The OidcClient works closely with the MetadataService to automatically discover provider configuration.
358

359
```typescript { .api }
360
class MetadataService {
361
  constructor(settings: OidcClientSettingsStore);
362
  
363
  /** Get the provider's metadata */
364
  getMetadata(): Promise<OidcMetadata>;
365
  /** Get the provider's signing keys */
366
  getSigningKeys(): Promise<SigningKey[]>;
367
  /** Get a specific endpoint URL */
368
  getAuthorizationEndpoint(): Promise<string>;
369
  getTokenEndpoint(): Promise<string>;
370
  getUserInfoEndpoint(): Promise<string>;
371
  getEndSessionEndpoint(): Promise<string>;
372
  getCheckSessionIframe(): Promise<string | undefined>;
373
  getRevocationEndpoint(): Promise<string | undefined>;
374
  getIntrospectionEndpoint(): Promise<string | undefined>;
375
}
376
```
377

378
**Advanced Usage with Custom Metadata:**
379

380
```typescript
381
import { OidcClient, MetadataService } from "oidc-client-ts";
382

383
// Create client with custom metadata service
384
const settings = {
385
  authority: "https://custom-provider.com",
386
  client_id: "my-client",
387
  redirect_uri: "http://localhost:5000/callback",
388
  // Provide metadata when CORS is not available
389
  metadata: {
390
    authorization_endpoint: "https://custom-provider.com/oauth/authorize",
391
    token_endpoint: "https://custom-provider.com/oauth/token",
392
    userinfo_endpoint: "https://custom-provider.com/oauth/userinfo",
393
    end_session_endpoint: "https://custom-provider.com/oauth/logout",
394
    issuer: "https://custom-provider.com",
395
  },
396
};
397

398
const metadataService = new MetadataService(settings);
399
const client = new OidcClient(settings, metadataService);
400
```