0
# Authorization Flows
1

2
Authorization URL building and authorization code grant processing with comprehensive support for PKCE, state validation, advanced security features, and multiple response modes.
3

4
## Capabilities
5

6
### Build Authorization URL
7

8
Creates authorization URLs for redirecting users to the authorization server.
9

10
```typescript { .api }
11
/**
12
 * Build authorization URL for user redirect
13
 * @param config - Configuration instance
14
 * @param parameters - Authorization request parameters
15
 * @returns URL for user-agent redirect
16
 */
17
function buildAuthorizationUrl(
18
  config: Configuration,
19
  parameters: URLSearchParams | Record<string, string>
20
): URL;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import * as client from "openid-client";
27

28
// Basic authorization URL with PKCE
29
const codeVerifier = client.randomPKCECodeVerifier();
30
const codeChallenge = await client.calculatePKCECodeChallenge(codeVerifier);
31

32
const authUrl = client.buildAuthorizationUrl(config, {
33
  redirect_uri: "https://example.com/callback",
34
  scope: "openid email profile",
35
  code_challenge: codeChallenge,
36
  code_challenge_method: "S256",
37
  state: client.randomState(),
38
  nonce: client.randomNonce()
39
});
40

41
// Authorization URL with additional parameters
42
const authUrl = client.buildAuthorizationUrl(config, {
43
  redirect_uri: "https://example.com/callback",
44
  scope: "openid email profile",
45
  code_challenge: codeChallenge,
46
  code_challenge_method: "S256",
47
  state: "random-state-value",
48
  nonce: "random-nonce-value",
49
  prompt: "consent",
50
  max_age: "3600",
51
  login_hint: "user@example.com",
52
  ui_locales: "en es"
53
});
54
```
55

56
### Authorization Code Grant
57

58
Validates authorization response and exchanges authorization code for tokens.
59

60
```typescript { .api }
61
/**
62
 * Execute Authorization Code Grant flow
63
 * @param config - Configuration instance
64
 * @param currentUrl - Current URL or Request with authorization response
65
 * @param checks - Validation checks (PKCE, state, nonce)
66
 * @param tokenEndpointParameters - Additional token endpoint parameters
67
 * @param options - Grant options (DPoP, etc.)
68
 * @returns Promise resolving to token response with helpers
69
 */
70
function authorizationCodeGrant(
71
  config: Configuration,
72
  currentUrl: URL | Request,
73
  checks?: AuthorizationCodeGrantChecks,
74
  tokenEndpointParameters?: URLSearchParams | Record<string, string>,
75
  options?: AuthorizationCodeGrantOptions
76
): Promise<TokenEndpointResponse & TokenEndpointResponseHelpers>;
77
```
78

79
**Usage Examples:**
80

81
```typescript
82
import * as client from "openid-client";
83

84
// Basic authorization code grant with PKCE
85
const tokens = await client.authorizationCodeGrant(
86
  config,
87
  new URL(callbackUrl), // URL with ?code=... parameters
88
  {
89
    pkceCodeVerifier: codeVerifier,
90
    expectedState: expectedState,
91
    expectedNonce: expectedNonce
92
  }
93
);
94

95
// Using Request object (server-side)
96
const tokens = await client.authorizationCodeGrant(
97
  config,
98
  request, // Express/HTTP request object
99
  {
100
    pkceCodeVerifier: codeVerifier,
101
    expectedState: expectedState
102
  }
103
);
104

105
// With additional token endpoint parameters
106
const tokens = await client.authorizationCodeGrant(
107
  config,
108
  currentUrl,
109
  { pkceCodeVerifier: codeVerifier },
110
  { 
111
    resource: "https://api.example.com", // resource indicator
112
    audience: "https://api.example.com"
113
  }
114
);
115

116
// Access token information
117
console.log("Access Token:", tokens.access_token);
118
console.log("Token Type:", tokens.token_type);
119
console.log("Expires In:", tokens.expiresIn()); // helper method
120
console.log("ID Token Claims:", tokens.claims()); // helper method
121
```
122

123
### Authorization URL with JAR
124

125
Build authorization URL using JWT Authorization Request (JAR) for enhanced security.
126

127
```typescript { .api }
128
/**
129
 * Build authorization URL with JWT Authorization Request
130
 * @param config - Configuration instance  
131
 * @param parameters - Authorization request parameters (will be signed)
132
 * @param signingKey - Private key for signing the request JWT
133
 * @param options - JWT modification options
134
 * @returns Promise resolving to authorization URL
135
 */
136
function buildAuthorizationUrlWithJAR(
137
  config: Configuration,
138
  parameters: URLSearchParams | Record<string, string>,
139
  signingKey: CryptoKey | PrivateKey,
140
  options?: ModifyAssertionOptions
141
): Promise<URL>;
142
```
143

144
**Usage Examples:**
145

146
```typescript
147
import * as client from "openid-client";
148

149
// JAR with private key
150
const privateKey = await crypto.subtle.generateKey(
151
  { name: "ECDSA", namedCurve: "P-256" },
152
  true,
153
  ["sign"]
154
);
155

156
const authUrl = await client.buildAuthorizationUrlWithJAR(
157
  config,
158
  {
159
    redirect_uri: "https://example.com/callback",
160
    scope: "openid email profile",
161
    code_challenge: codeChallenge,
162
    code_challenge_method: "S256",
163
    state: "secure-state",
164
    nonce: "secure-nonce"
165
  },
166
  privateKey.privateKey
167
);
168

169
// JAR with assertion modification
170
const authUrl = await client.buildAuthorizationUrlWithJAR(
171
  config,
172
  parameters,
173
  privateKey.privateKey,
174
  {
175
    [client.modifyAssertion]: (header, payload) => {
176
      // Modify JWT before signing
177
      header.custom = "value";
178
      payload.custom_claim = "custom_value";
179
    }
180
  }
181
);
182
```
183

184
### Authorization URL with PAR
185

186
Build authorization URL using Pushed Authorization Request (PAR) for enhanced security.
187

188
```typescript { .api }
189
/**
190
 * Build authorization URL with Pushed Authorization Request
191
 * @param config - Configuration instance
192
 * @param parameters - Authorization request parameters (will be pushed)
193
 * @param options - PAR options (DPoP, etc.)
194
 * @returns Promise resolving to authorization URL with request_uri
195
 */
196
function buildAuthorizationUrlWithPAR(
197
  config: Configuration,
198
  parameters: URLSearchParams | Record<string, string>,
199
  options?: DPoPOptions
200
): Promise<URL>;
201
```
202

203
**Usage Examples:**
204

205
```typescript
206
import * as client from "openid-client";
207

208
// Basic PAR usage
209
const authUrl = await client.buildAuthorizationUrlWithPAR(config, {
210
  redirect_uri: "https://example.com/callback",
211
  scope: "openid email profile",
212
  code_challenge: codeChallenge,
213
  code_challenge_method: "S256",
214
  state: "secure-state",
215
  nonce: "secure-nonce"
216
});
217

218
// JAR + PAR combination for maximum security
219
const { searchParams } = await client.buildAuthorizationUrlWithJAR(
220
  config,
221
  {
222
    redirect_uri: "https://example.com/callback",
223
    scope: "openid email profile",
224
    code_challenge: codeChallenge,
225
    code_challenge_method: "S256"
226
  },
227
  privateKey
228
);
229

230
const authUrl = await client.buildAuthorizationUrlWithPAR(config, searchParams);
231
```
232

233
### Implicit Authentication
234

235
Validate implicit flow responses (ID Token only).
236

237
```typescript { .api }
238
/**
239
 * Validate implicit authentication response
240
 * @param config - Configuration instance
241
 * @param currentUrl - Current URL or Request with implicit response
242
 * @param expectedNonce - Expected nonce value
243
 * @param checks - Additional validation checks
244
 * @returns Promise resolving to ID Token claims
245
 */
246
function implicitAuthentication(
247
  config: Configuration,
248
  currentUrl: URL | Request,
249
  expectedNonce: string,
250
  checks?: ImplicitAuthenticationResponseChecks
251
): Promise<IDToken>;
252
```
253

254
**Usage Examples:**
255

256
```typescript
257
import * as client from "openid-client";
258

259
// Validate implicit flow response
260
const idTokenClaims = await client.implicitAuthentication(
261
  config,
262
  new URL(location.href), // browser environment
263
  expectedNonce,
264
  {
265
    expectedState: expectedState,
266
    maxAge: 3600
267
  }
268
);
269

270
console.log("User ID:", idTokenClaims.sub);
271
console.log("Email:", idTokenClaims.email);
272
```
273

274
### End Session URL
275

276
Build URLs for RP-Initiated Logout.
277

278
```typescript { .api }
279
/**
280
 * Build end session URL for logout
281
 * @param config - Configuration instance
282
 * @param parameters - Logout parameters
283
 * @returns URL for logout redirect
284
 */
285
function buildEndSessionUrl(
286
  config: Configuration,
287
  parameters?: URLSearchParams | Record<string, string>
288
): URL;
289
```
290

291
**Usage Examples:**
292

293
```typescript
294
import * as client from "openid-client";
295

296
// Basic logout URL
297
const logoutUrl = client.buildEndSessionUrl(config, {
298
  id_token_hint: idToken,
299
  post_logout_redirect_uri: "https://example.com/logout"
300
});
301

302
// Logout without redirect
303
const logoutUrl = client.buildEndSessionUrl(config, {
304
  id_token_hint: idToken
305
});
306
```
307

308
## Validation and Security Types
309

310
```typescript { .api }
311
interface AuthorizationCodeGrantChecks {
312
  /** Expected nonce value for ID Token validation */
313
  expectedNonce?: string;
314
  /** Expected state value for CSRF protection */
315
  expectedState?: string | typeof skipStateCheck;
316
  /** Require ID Token in response */
317
  idTokenExpected?: boolean;
318
  /** Maximum age for auth_time claim validation */
319
  maxAge?: number;
320
  /** PKCE code verifier for code challenge validation */
321
  pkceCodeVerifier?: string;
322
}
323

324
interface ImplicitAuthenticationResponseChecks extends Pick<AuthorizationCodeGrantChecks, 'expectedState' | 'maxAge'> {
325
}
326

327
interface AuthorizationCodeGrantOptions extends DPoPOptions {
328
}
329
```
330

331
## PKCE Utilities
332

333
```typescript { .api }
334
/**
335
 * Generate random PKCE code verifier
336
 * @returns Random code verifier string
337
 */
338
function randomPKCECodeVerifier(): string;
339

340
/**
341
 * Calculate PKCE code challenge using S256 method
342
 * @param codeVerifier - Code verifier to hash
343
 * @returns Promise resolving to base64url-encoded SHA256 hash
344
 */
345
function calculatePKCECodeChallenge(codeVerifier: string): Promise<string>;
346
```
347

348
## Random Value Generation
349

350
```typescript { .api }
351
/**
352
 * Generate random state value for CSRF protection
353
 * @returns Random state string
354
 */
355
function randomState(): string;
356

357
/**
358
 * Generate random nonce value for replay protection  
359
 * @returns Random nonce string
360
 */
361
function randomNonce(): string;
362
```