0
# Configuration and Discovery
1

2
Configuration management and automatic Authorization Server metadata discovery form the foundation of all OAuth 2.0 and OpenID Connect operations in openid-client.
3

4
## Capabilities
5

6
### Discovery Function
7

8
Performs Authorization Server Metadata discovery and returns a configured client instance. This is the recommended method for client configuration.
9

10
```typescript { .api }
11
/**
12
 * Performs Authorization Server Metadata discovery
13
 * @param server - URL of the Authorization Server's Issuer Identifier  
14
 * @param clientId - Client Identifier at the Authorization Server
15
 * @param metadata - Client metadata or client secret string
16
 * @param clientAuthentication - Client authentication method (defaults to ClientSecretPost)
17
 * @param options - Discovery options
18
 * @returns Promise resolving to Configuration instance
19
 */
20
function discovery(
21
  server: URL,
22
  clientId: string,
23
  metadata?: Partial<ClientMetadata> | string,
24
  clientAuthentication?: ClientAuth,
25
  options?: DiscoveryRequestOptions
26
): Promise<Configuration>;
27
```
28

29
**Usage Examples:**
30

31
```typescript
32
import * as client from "openid-client";
33

34
// Basic discovery with client secret
35
const config = await client.discovery(
36
  new URL("https://accounts.google.com"),
37
  "your-client-id",
38
  "your-client-secret"
39
);
40

41
// Discovery with client metadata object
42
const config = await client.discovery(
43
  new URL("https://example.com"),
44
  "client-id",
45
  {
46
    client_secret: "secret",
47
    use_mtls_endpoint_aliases: true
48
  }
49
);
50

51
// Discovery with specific authentication method
52
const config = await client.discovery(
53
  new URL("https://example.com"),
54
  "client-id",
55
  undefined, // no client secret for public client
56
  client.None()
57
);
58

59
// Discovery with options
60
const config = await client.discovery(
61
  new URL("https://example.com"),
62
  "client-id",
63
  "client-secret",
64
  undefined, // default auth method
65
  {
66
    algorithm: "oauth2", // use OAuth 2.0 discovery instead of OIDC
67
    timeout: 60, // 60 second timeout
68
    execute: [client.allowInsecureRequests] // allow HTTP for development
69
  }
70
);
71
```
72

73
### Configuration Class
74

75
Manual configuration when Authorization Server metadata is known upfront.
76

77
```typescript { .api }
78
/**
79
 * Configuration class combining server and client metadata
80
 */
81
class Configuration implements ConfigurationMethods, ConfigurationProperties {
82
  constructor(
83
    server: ServerMetadata,
84
    clientId: string,
85
    metadata?: Partial<ClientMetadata> | string,
86
    clientAuthentication?: ClientAuth
87
  );
88
  
89
  serverMetadata(): Readonly<ServerMetadata> & ServerMetadataHelpers;
90
  clientMetadata(): Readonly<OmitSymbolProperties<ClientMetadata>>;
91
  
92
  timeout?: number;
93
  [customFetch]?: CustomFetch;
94
}
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import * as client from "openid-client";
101

102
// Manual configuration with known server metadata
103
const serverMetadata: client.ServerMetadata = {
104
  issuer: "https://example.com",
105
  authorization_endpoint: "https://example.com/auth",
106
  token_endpoint: "https://example.com/token",
107
  userinfo_endpoint: "https://example.com/userinfo",
108
  jwks_uri: "https://example.com/.well-known/jwks.json",
109
  // ... other required metadata
110
};
111

112
const config = new client.Configuration(
113
  serverMetadata,
114
  "client-id",
115
  "client-secret"
116
);
117

118
// Access metadata
119
const server = config.serverMetadata();
120
const clientInfo = config.clientMetadata();
121

122
// Check server capabilities  
123
if (server.supportsPKCE()) {
124
  console.log("Server supports PKCE");
125
}
126
```
127

128
### Dynamic Client Registration
129

130
Perform dynamic client registration with automatic discovery.
131

132
```typescript { .api }
133
/**
134
 * Performs dynamic client registration with discovery
135
 * @param server - Authorization Server issuer URL
136
 * @param metadata - Client metadata to register
137
 * @param clientAuthentication - Authentication method for registration
138
 * @param options - Registration options
139
 * @returns Promise resolving to Configuration with registered client
140
 */
141
function dynamicClientRegistration(
142
  server: URL,
143
  metadata: Partial<ClientMetadata>,
144
  clientAuthentication?: ClientAuth,
145
  options?: DynamicClientRegistrationRequestOptions
146
): Promise<Configuration>;
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
import * as client from "openid-client";
153

154
// Register a new client
155
const config = await client.dynamicClientRegistration(
156
  new URL("https://example.com"),
157
  {
158
    redirect_uris: ["https://myapp.com/callback"],
159
    response_types: ["code"],
160
    grant_types: ["authorization_code", "refresh_token"],
161
    application_type: "web",
162
    client_name: "My Application"
163
  }
164
);
165

166
// Registration with initial access token
167
const config = await client.dynamicClientRegistration(
168
  new URL("https://example.com"),
169
  {
170
    redirect_uris: ["https://myapp.com/callback"],
171
    response_types: ["code"]
172
  },
173
  undefined, // default auth
174
  {
175
    initialAccessToken: "bearer-token-for-registration"
176
  }
177
);
178
```
179

180
### Configuration Options
181

182
Options for discovery and registration operations.
183

184
```typescript { .api }
185
interface DiscoveryRequestOptions {
186
  /** Custom fetch implementation */
187
  [customFetch]?: CustomFetch;
188
  /** Discovery algorithm: 'oidc' or 'oauth2' */
189
  algorithm?: 'oidc' | 'oauth2';
190
  /** Configuration methods to execute after instantiation */
191
  execute?: Array<(config: Configuration) => void>;
192
  /** Timeout in seconds (default: 30) */
193
  timeout?: number;
194
}
195

196
interface DynamicClientRegistrationRequestOptions extends DiscoveryRequestOptions, DPoPOptions {
197
  /** Access token for client registration endpoint */
198
  initialAccessToken?: string;
199
}
200
```
201

202
### Server Metadata Helpers
203

204
Helper methods available on server metadata objects.
205

206
```typescript { .api }
207
interface ServerMetadataHelpers {
208
  /**
209
   * Check if server supports PKCE with specified method
210
   * @param method - PKCE method (default: 'S256')
211
   * @returns True if PKCE is supported
212
   */
213
  supportsPKCE(method?: string): boolean;
214
}
215
```
216

217
### Configuration Properties
218

219
Properties available on Configuration instances.
220

221
```typescript { .api }
222
interface ConfigurationProperties {
223
  /** Custom fetch implementation for HTTP requests */
224
  [customFetch]?: CustomFetch;
225
  /** Timeout in seconds for HTTP requests (default: 30) */
226
  timeout?: number;
227
}
228

229
interface ConfigurationMethods {
230
  /** Get server metadata with helpers */
231
  serverMetadata(): Readonly<ServerMetadata> & ServerMetadataHelpers;
232
  /** Get client metadata */
233
  clientMetadata(): Readonly<OmitSymbolProperties<ClientMetadata>>;
234
}
235
```
236

237
## Core Metadata Types
238

239
```typescript { .api }
240
interface ServerMetadata extends AuthorizationServer {
241
  // Standard OAuth 2.0/OIDC Authorization Server metadata
242
  issuer: string;
243
  authorization_endpoint: string;
244
  token_endpoint: string;
245
  userinfo_endpoint?: string;
246
  jwks_uri?: string;
247
  registration_endpoint?: string;
248
  scopes_supported?: string[];
249
  response_types_supported?: string[];
250
  grant_types_supported?: string[];
251
  token_endpoint_auth_methods_supported?: string[];
252
  // ... and many other standard metadata fields
253
}
254

255
interface ClientMetadata extends Client {
256
  /** Client secret for confidential clients */
257
  client_secret?: string;
258
  /** Use mutual TLS endpoint aliases */
259
  use_mtls_endpoint_aliases?: boolean;
260
  /** Client ID */
261
  client_id?: string;
262
  /** Redirect URIs */
263
  redirect_uris?: string[];
264
  /** Response types */
265
  response_types?: string[];
266
  /** Grant types */
267
  grant_types?: string[];
268
  /** Application type ('web' or 'native') */
269
  application_type?: string;
270
  /** Client name */
271
  client_name?: string;
272
  // ... and other standard client metadata fields
273
}
274
```