Repository navigation
feat: expose discoverOAuthServerInfo() and add provider caching for auth server URL #1527
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 3 commits
7ebd854
54cb233
1437f1d
cb5cb53
d6a75e4
f5c980e
d2cd62d
864c44a
cb7b55c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| '@modelcontextprotocol/client': minor | ||
| --- | ||
|
|
||
| Add `discoverOAuthServerInfo()` function and optional provider caching for authorization server discovery | ||
|
|
||
| - New `discoverOAuthServerInfo(serverUrl)` export that performs RFC 9728 protected resource metadata discovery followed by authorization server metadata discovery in a single call. Use this for operations like token refresh and revocation that need the authorization server URL outside of `auth()`. | ||
| - New optional `OAuthClientProvider` methods `saveAuthorizationServerUrl()` and `authorizationServerUrl()` allow providers to persist the discovered authorization server URL across sessions. When `authorizationServerUrl()` returns a cached URL, `auth()` skips RFC 9728 discovery, reducing latency on subsequent calls. | ||
| - New `OAuthServerInfo` type exported for the return value of `discoverOAuthServerInfo()`. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -183,6 +183,26 @@ export interface OAuthClientProvider { | |
| * } | ||
| */ | ||
| prepareTokenRequest?(scope?: string): URLSearchParams | Promise<URLSearchParams | undefined> | undefined; | ||
|
|
||
| /** | ||
| * Saves the authorization server URL discovered during the OAuth flow. | ||
| * | ||
| * Called by {@linkcode auth} after RFC 9728 discovery so providers can persist the | ||
| * URL for later use in operations like token refresh or revocation, avoiding | ||
| * redundant discovery requests. | ||
| */ | ||
| saveAuthorizationServerUrl?(url: string | URL): void | Promise<void>; | ||
|
|
||
| /** | ||
| * Returns a previously saved authorization server URL, or `undefined` if none is cached. | ||
| * | ||
| * When available, {@linkcode auth} skips RFC 9728 protected resource metadata | ||
| * discovery and uses this URL directly, reducing latency on subsequent calls. | ||
| * | ||
| * Providers should clear the cached URL on repeated authentication failures | ||
| * to allow re-discovery in case the authorization server has changed. | ||
| */ | ||
| authorizationServerUrl?(): string | URL | undefined | Promise<string | URL | undefined>; | ||
|
felixweinberger marked this conversation as resolved.
Resolved
|
||
| } | ||
|
|
||
| export type AuthResult = 'AUTHORIZED' | 'REDIRECT'; | ||
|
|
@@ -395,32 +415,37 @@ async function authInternal( | |
| fetchFn?: FetchLike; | ||
| } | ||
| ): Promise<AuthResult> { | ||
| // Check if the provider has a cached authorization server URL to skip discovery | ||
| const cachedAuthServerUrl = await provider.authorizationServerUrl?.(); | ||
|
|
||
| let resourceMetadata: OAuthProtectedResourceMetadata | undefined; | ||
| let authorizationServerUrl: string | URL | undefined; | ||
| let authorizationServerUrl: string | URL; | ||
| let metadata: AuthorizationServerMetadata | undefined; | ||
|
|
||
| try { | ||
| resourceMetadata = await discoverOAuthProtectedResourceMetadata(serverUrl, { resourceMetadataUrl }, fetchFn); | ||
| if (resourceMetadata.authorization_servers && resourceMetadata.authorization_servers.length > 0) { | ||
| authorizationServerUrl = resourceMetadata.authorization_servers[0]; | ||
| } | ||
| } catch { | ||
| // Ignore errors and fall back to /.well-known/oauth-authorization-server | ||
| } | ||
| if (cachedAuthServerUrl) { | ||
| // Use cached URL, skip auth server URL derivation from RFC 9728 | ||
| authorizationServerUrl = cachedAuthServerUrl; | ||
| metadata = await discoverAuthorizationServerMetadata(authorizationServerUrl, { fetchFn }); | ||
|
|
||
| /** | ||
| * If we don't get a valid authorization server metadata from protected resource metadata, | ||
| * fallback to the legacy MCP spec's implementation (version 2025-03-26): MCP server base URL acts as the Authorization server. | ||
| */ | ||
| if (!authorizationServerUrl) { | ||
| authorizationServerUrl = new URL('/', serverUrl); | ||
| // Still fetch resource metadata for selectResourceURL (needed for the resource parameter) | ||
| try { | ||
| resourceMetadata = await discoverOAuthProtectedResourceMetadata(serverUrl, { resourceMetadataUrl }, fetchFn); | ||
| } catch { | ||
| // RFC 9728 not available — selectResourceURL will handle undefined | ||
| } | ||
| } else { | ||
| // Full discovery via RFC 9728 | ||
| const serverInfo = await discoverOAuthServerInfo(serverUrl, { resourceMetadataUrl, fetchFn }); | ||
| authorizationServerUrl = serverInfo.authorizationServerUrl; | ||
| metadata = serverInfo.authorizationServerMetadata; | ||
| resourceMetadata = serverInfo.resourceMetadata; | ||
|
|
||
| // Persist the discovered URL for future use | ||
| await provider.saveAuthorizationServerUrl?.(authorizationServerUrl); | ||
| } | ||
|
|
||
| const resource: URL | undefined = await selectResourceURL(serverUrl, provider, resourceMetadata); | ||
|
|
||
| const metadata = await discoverAuthorizationServerMetadata(authorizationServerUrl, { | ||
| fetchFn | ||
| }); | ||
|
|
||
| // Handle client registration if needed | ||
| let clientInformation = await Promise.resolve(provider.clientInformation()); | ||
| if (!clientInformation) { | ||
|
|
@@ -941,6 +966,87 @@ export async function discoverAuthorizationServerMetadata( | |
| return undefined; | ||
| } | ||
|
|
||
| /** | ||
| * Result of {@linkcode discoverOAuthServerInfo}. | ||
| */ | ||
| export interface OAuthServerInfo { | ||
|
felixweinberger marked this conversation as resolved.
Resolved
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can this type and
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think they're a little bit different right, they just happen to look similar right now - but in future the To avoid duplication though makes sense for
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. cool that makes sense to me |
||
| /** | ||
| * The authorization server URL, either discovered via RFC 9728 | ||
| * or derived from the MCP server URL as a fallback. | ||
| */ | ||
| authorizationServerUrl: string | URL; | ||
|
|
||
| /** | ||
| * The authorization server metadata (endpoints, capabilities), | ||
| * or `undefined` if metadata discovery failed. | ||
| */ | ||
| authorizationServerMetadata?: AuthorizationServerMetadata; | ||
|
|
||
| /** | ||
| * The OAuth 2.0 Protected Resource Metadata from RFC 9728, | ||
| * or `undefined` if the server does not support it. | ||
| */ | ||
| resourceMetadata?: OAuthProtectedResourceMetadata; | ||
| } | ||
|
|
||
| /** | ||
| * Discovers the authorization server for an MCP server following | ||
| * {@link https://datatracker.ietf.org/doc/html/rfc9728 | RFC 9728} (OAuth 2.0 Protected | ||
| * Resource Metadata), with fallback to treating the server URL as the | ||
| * authorization server. | ||
| * | ||
| * This function combines two discovery steps into one call: | ||
| * 1. Probes `/.well-known/oauth-protected-resource` on the MCP server to find the | ||
| * authorization server URL (RFC 9728). | ||
| * 2. Fetches authorization server metadata from that URL (RFC 8414 / OpenID Connect Discovery). | ||
| * | ||
| * Use this when you need the authorization server metadata for operations outside the | ||
| * {@linkcode auth} orchestrator, such as token refresh or token revocation. | ||
| * | ||
| * @param serverUrl - The MCP resource server URL | ||
| * @param opts - Optional configuration | ||
| * @param opts.resourceMetadataUrl - Override URL for the protected resource metadata endpoint | ||
| * @param opts.fetchFn - Custom fetch function for HTTP requests | ||
| * @returns Authorization server URL, metadata, and resource metadata (if available) | ||
| */ | ||
| export async function discoverOAuthServerInfo( | ||
| serverUrl: string | URL, | ||
| opts?: { | ||
| resourceMetadataUrl?: URL; | ||
| fetchFn?: FetchLike; | ||
| } | ||
| ): Promise<OAuthServerInfo> { | ||
| let resourceMetadata: OAuthProtectedResourceMetadata | undefined; | ||
| let authorizationServerUrl: string | URL | undefined; | ||
|
|
||
| try { | ||
| resourceMetadata = await discoverOAuthProtectedResourceMetadata( | ||
| serverUrl, | ||
| { resourceMetadataUrl: opts?.resourceMetadataUrl }, | ||
| opts?.fetchFn | ||
| ); | ||
| if (resourceMetadata.authorization_servers && resourceMetadata.authorization_servers.length > 0) { | ||
| authorizationServerUrl = resourceMetadata.authorization_servers[0]; | ||
| } | ||
| } catch { | ||
| // RFC 9728 not supported -- fall back to treating the server URL as the authorization server | ||
| } | ||
|
|
||
| // If we don't get a valid authorization server from protected resource metadata, | ||
| // fall back to the legacy MCP spec behavior: MCP server base URL acts as the authorization server | ||
| if (!authorizationServerUrl) { | ||
| authorizationServerUrl = new URL('/', serverUrl); | ||
| } | ||
|
|
||
| const authorizationServerMetadata = await discoverAuthorizationServerMetadata(authorizationServerUrl, { fetchFn: opts?.fetchFn }); | ||
|
|
||
| return { | ||
| authorizationServerUrl, | ||
| authorizationServerMetadata, | ||
| resourceMetadata | ||
| }; | ||
| } | ||
|
|
||
| /** | ||
| * Begins the authorization flow with the given server, by generating a PKCE challenge and constructing the authorization URL. | ||
| */ | ||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.