0
# OpenID Client
1

2
OpenID Client is a comprehensive OAuth 2.0 and OpenID Connect client library for JavaScript runtimes. It provides complete support for all major authentication flows, advanced security features like FAPI compliance, DPoP, JARM, JAR, and PAR, with extensive configuration options for Node.js, browsers, Deno, Cloudflare Workers, and other JavaScript environments.
3

4
## Package Information
5

6
- **Package Name**: openid-client
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript (ESM)
9
- **Installation**: `npm install openid-client`
10

11
## Core Imports
12

13
```typescript
14
import * as client from "openid-client";
15
```
16

17
For specific imports:
18

19
```typescript
20
import { 
21
  discovery, 
22
  Configuration, 
23
  authorizationCodeGrant, 
24
  buildAuthorizationUrl,
25
  ClientSecretPost 
26
} from "openid-client";
27
```
28

29
For Passport.js integration:
30

31
```typescript
32
import { Strategy } from "openid-client/passport";
33
```
34

35
For CommonJS:
36

37
```javascript
38
const client = require("openid-client");
39
```
40

41
For specific CommonJS imports:
42

43
```javascript
44
const { 
45
  discovery, 
46
  Configuration, 
47
  authorizationCodeGrant, 
48
  buildAuthorizationUrl,
49
  ClientSecretPost 
50
} = require("openid-client");
51
```
52

53
## Basic Usage
54

55
```typescript
56
import * as client from "openid-client";
57

58
// 1. Discover authorization server configuration
59
const config = await client.discovery(
60
  new URL("https://accounts.google.com"), // issuer
61
  "your-client-id", // client ID  
62
  "your-client-secret" // client secret (or client metadata object)
63
);
64

65
// 2. Build authorization URL with PKCE
66
const codeVerifier = client.randomPKCECodeVerifier();
67
const codeChallenge = await client.calculatePKCECodeChallenge(codeVerifier);
68

69
const authUrl = client.buildAuthorizationUrl(config, {
70
  redirect_uri: "https://example.com/callback",
71
  scope: "openid email profile",
72
  code_challenge: codeChallenge,
73
  code_challenge_method: "S256",
74
  state: client.randomState(),
75
  nonce: client.randomNonce()
76
});
77

78
// 3. Handle authorization callback
79
const tokens = await client.authorizationCodeGrant(
80
  config,
81
  currentUrl, // URL with authorization response parameters
82
  {
83
    pkceCodeVerifier: codeVerifier,
84
    expectedState: expectedState,
85
    expectedNonce: expectedNonce
86
  }
87
);
88

89
// 4. Access tokens and claims
90
console.log("Access Token:", tokens.access_token);
91
console.log("ID Token Claims:", tokens.claims());
92
console.log("Expires in:", tokens.expiresIn(), "seconds");
93

94
// 5. Fetch user info
95
const userInfo = await client.fetchUserInfo(
96
  config,
97
  tokens.access_token,
98
  tokens.claims()?.sub // expected subject
99
);
100
```
101

102
## Architecture
103

104
OpenID Client is built around several key components:
105

106
- **Configuration System**: Central `Configuration` class combining server and client metadata with automatic discovery support
107
- **Authentication Methods**: Pluggable client authentication system supporting all standard OAuth methods
108
- **Grant Implementations**: Complete support for Authorization Code, Client Credentials, Device, CIBA, and custom grants  
109
- **Security Features**: Advanced security with PKCE, DPoP, JARM, JAR, PAR, and FAPI compliance capabilities
110
- **Runtime Agnostic**: Works across Node.js, browsers, Deno, Cloudflare Workers with custom fetch support
111
- **Type Safety**: Full TypeScript support with comprehensive type definitions for all operations
112

113
## Capabilities
114

115
### Configuration and Discovery
116

117
Core configuration management and automatic Authorization Server metadata discovery. Essential for all OAuth/OIDC operations.
118

119
```typescript { .api }
120
function discovery(
121
  server: URL,
122
  clientId: string,
123
  metadata?: Partial<ClientMetadata> | string,
124
  clientAuthentication?: ClientAuth,
125
  options?: DiscoveryRequestOptions
126
): Promise<Configuration>;
127

128
class Configuration {
129
  constructor(
130
    server: ServerMetadata,
131
    clientId: string,
132
    metadata?: Partial<ClientMetadata> | string,
133
    clientAuthentication?: ClientAuth
134
  );
135
  serverMetadata(): Readonly<ServerMetadata>;
136
  clientMetadata(): Readonly<ClientMetadata>;
137
}
138
```
139

140
[Configuration and Discovery](./configuration.md)
141

142
### Authorization Flows
143

144
Authorization URL building and authorization code grant processing with support for PKCE, state validation, and advanced flows.
145

146
```typescript { .api }
147
function buildAuthorizationUrl(
148
  config: Configuration,
149
  parameters: URLSearchParams | Record<string, string>
150
): URL;
151

152
function authorizationCodeGrant(
153
  config: Configuration,
154
  currentUrl: URL | Request,
155
  checks?: AuthorizationCodeGrantChecks,
156
  tokenEndpointParameters?: URLSearchParams | Record<string, string>,
157
  options?: AuthorizationCodeGrantOptions
158
): Promise<TokenEndpointResponse & TokenEndpointResponseHelpers>;
159
```
160

161
[Authorization Flows](./authorization-flows.md)
162

163
### Client Authentication
164

165
All standard OAuth 2.0 client authentication methods including client secrets, private key JWT, and mutual TLS.
166

167
```typescript { .api }
168
function ClientSecretPost(clientSecret?: string): ClientAuth;
169
function ClientSecretBasic(clientSecret?: string): ClientAuth;
170
function ClientSecretJwt(clientSecret?: string, options?: ModifyAssertionOptions): ClientAuth;
171
function PrivateKeyJwt(clientPrivateKey: CryptoKey | PrivateKey, options?: ModifyAssertionOptions): ClientAuth;
172
function TlsClientAuth(): ClientAuth;
173
function None(): ClientAuth;
174
```
175

176
[Client Authentication](./client-authentication.md)
177

178
### Grant Types
179

180
Complete implementation of all OAuth 2.0 and OpenID Connect grant types including device flow and CIBA.
181

182
```typescript { .api }
183
function clientCredentialsGrant(
184
  config: Configuration,
185
  parameters?: URLSearchParams | Record<string, string>,
186
  options?: DPoPOptions
187
): Promise<TokenEndpointResponse & TokenEndpointResponseHelpers>;
188

189
function refreshTokenGrant(
190
  config: Configuration,
191
  refreshToken: string,
192
  parameters?: URLSearchParams | Record<string, string>,
193
  options?: DPoPOptions
194
): Promise<TokenEndpointResponse & TokenEndpointResponseHelpers>;
195
```
196

197
[Grant Types](./grant-types.md)
198

199
### Token Management
200

201
Token introspection, revocation, and lifecycle management operations.
202

203
```typescript { .api }
204
function tokenIntrospection(
205
  config: Configuration,
206
  token: string,
207
  parameters?: URLSearchParams | Record<string, string>
208
): Promise<IntrospectionResponse>;
209

210
function tokenRevocation(
211
  config: Configuration,
212
  token: string,
213
  parameters?: URLSearchParams | Record<string, string>
214
): Promise<void>;
215
```
216

217
[Token Management](./token-management.md)
218

219
### Protected Resource Access
220

221
Access protected resources and UserInfo endpoint with proper access token handling.
222

223
```typescript { .api }
224
function fetchUserInfo(
225
  config: Configuration,
226
  accessToken: string,
227
  expectedSubject: string | typeof skipSubjectCheck,
228
  options?: DPoPOptions
229
): Promise<UserInfoResponse>;
230

231
function fetchProtectedResource(
232
  config: Configuration,
233
  accessToken: string,
234
  url: URL,
235
  method: string,
236
  body?: FetchBody,
237
  headers?: Headers,
238
  options?: DPoPOptions
239
): Promise<Response>;
240
```
241

242
[Protected Resource Access](./protected-resources.md)
243

244
### Advanced Security Features
245

246
FAPI compliance, DPoP, JARM, JAR, PAR, and other advanced security mechanisms.
247

248
```typescript { .api }
249
function getDPoPHandle(
250
  config: Configuration,
251
  keyPair: CryptoKeyPair,
252
  options?: ModifyAssertionOptions
253
): DPoPHandle;
254

255
function useJwtResponseMode(config: Configuration): void;
256
function enableNonRepudiationChecks(config: Configuration): void;
257
function useCodeIdTokenResponseType(config: Configuration): void;
258
```
259

260
[Advanced Security](./advanced-security.md)
261

262
### Passport.js Integration
263

264
Complete Passport.js strategy for OpenID Connect authentication with Express.js applications.
265

266
```typescript { .api }
267
class Strategy implements passport.Strategy {
268
  constructor(options: StrategyOptions, verify: VerifyFunction);
269
  constructor(options: StrategyOptionsWithRequest, verify: VerifyFunctionWithRequest);
270
  authenticate<TOptions extends AuthenticateOptions>(
271
    req: express.Request,
272
    options: TOptions
273
  ): void;
274
}
275
```
276

277
[Passport.js Integration](./passport-integration.md)
278

279
## Core Types
280

281
```typescript { .api }
282
interface ServerMetadata extends AuthorizationServer {
283
  // Authorization Server metadata from oauth4webapi
284
}
285

286
interface ClientMetadata extends Client {
287
  client_secret?: string;
288
  use_mtls_endpoint_aliases?: boolean;
289
}
290

291
interface TokenEndpointResponse {
292
  access_token: string;
293
  token_type: string;
294
  expires_in?: number;
295
  refresh_token?: string;
296
  scope?: string;
297
  id_token?: string;
298
}
299

300
interface TokenEndpointResponseHelpers {
301
  claims(): IDToken | undefined;
302
  expiresIn(): number | undefined;
303
}
304

305
interface AuthorizationCodeGrantChecks {
306
  expectedNonce?: string;
307
  expectedState?: string | typeof skipStateCheck;
308
  idTokenExpected?: boolean;
309
  maxAge?: number;
310
  pkceCodeVerifier?: string;
311
}
312

313
interface DPoPOptions {
314
  DPoP?: DPoPHandle;
315
}
316

317
interface DPoPHandle {
318
  // DPoP handle for proof-of-possession operations
319
}
320

321
type ClientAuth = (
322
  as: ServerMetadata,
323
  client: ClientMetadata,
324
  body: URLSearchParams,
325
  headers: Headers
326
) => void;
327

328
type CryptoKey = Extract<Awaited<ReturnType<typeof crypto.subtle.generateKey>>, {
329
  type: string;
330
}>;
331

332
interface CryptoKeyPair {
333
  privateKey: CryptoKey;
334
  publicKey: CryptoKey;
335
}
336
```