DEV Community: Descope

OAuth vs. API Keys for Agentic AI

Mrunank Pawar — Fri, 17 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

If you're a senior developer or architect, you've likely weighed the OAuth vs. API keys tradeoff many times to balance simplicity against security and convenience against control. But those API security concerns always assumed traditional API clients: web apps, mobile apps, and predictable server-to-server integrations. Agentic AI systems challenge those assumptions.

Unlike traditional API clients, agentic AI systems are autonomous, tool-using, and inherently non-deterministic. They make real-time decisions, chain multiple API calls together, and sometimes take actions their creators never explicitly programmed. When an AI agent can decide to delete your production database or book a flight on your behalf, the stakes of API authentication are high, and accidents happen. In this article, you'll reexamine the outstanding debate between OAuth and API keys through the lens of agentic AI.

What are API keys?

If you've used paid APIs from services like Claude, OpenAI, or Mailgun, you've already used API keys. API keys are simple, static credentials; typically long alphanumeric strings that act as both identifier and password rolled into one. They're given by API providers and included in requests, usually as a header or query parameter, to authenticate the caller.

How API keys work

The workflow is straightforward. A developer generates an API key from a provider's dashboard, embeds it in their application, and sends it with every API request:

GET /data HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_live_a8f3j29dk3j2d9fj2k3d
Accept: application/json

The server validates the key against its database and either grants or denies access. It doesn't involve any redirects, token exchanges, or complexity.

Traditional use cases

API keys have been used in machine-to-machine (M2M) authentication for years, in controlled environments such as internal microservices, CI/CD pipelines, monitoring tools, etc.

Strengths / benefits of API keys

There's a reason API keys remain popular:

Simple to implement and deploy: No complicated flows, no authorization servers, no token management infrastructure.
Minimal overhead: No redirects, no token juggling, no refresh logic.
Useful for low-risk, tightly controlled systems: Where you trust the environment and the code using the key.

For instance, if a script syncs data between two internal databases at 3 a.m., using API keys is perfectly fine.

Limitations of API keys

The following are some shortcomings of API keys:

Long-lived and static by default: API keys have no built-in expiration mechanism. Once issued, a key remains valid until explicitly revoked. How and when it's revoked depends on provider tooling and team discipline.
No scopes: API keys have no standardized concept of permissions. When it does exist, access control is defined ad hoc, per provider. The result is inconsistent granularity across services and a lack of interoperability.
Hard to rotate at scale: Rotating keys across dozens of services means coordinating deployments and risking downtime.
No built-in user delegation: API keys represent the application, not a specific user. There's no way to say "this action was taken by Alice".
Limited auditability and traceability: Log entries show the API key was used, but not by whom, why, or in what context.

It's worth noting that individual providers have closed some of these gaps independently. For example: GitHub supports fine-grained personal access tokens (PATs) with repository-level scoping and expiration. AWS allows per-key policy for its Key Management Service (KMS). Anthropic and OpenAI both offer workspace-scoped keys with configurable permissions. But each of these is a proprietary implementation: different APIs, different defaults, different enforcement. An agentic system that calls tools across five providers encounters five separate permission models with no single standard determining how keys are issued, scoped, rotated, or revoked. OAuth's value in this context isn't that it can do things API keys theoretically can't, but that it does them consistently, interoperably, and by a shared specification.

What OAuth provides over API keys

If you've ever clicked "Login with Google" or "Login with LinkedIn" on a website, you've seen OAuth 2.0 in action.

OAuth 2.0 fundamentally rethinks API authentication by separating two concerns that API keys conflate: who you are (authentication) and what you can do (authorization).

Instead of a single static credential, OAuth uses short-lived access tokens granted through explicit authorization flows. These tokens carry specific permissions (called scopes) that define exactly what actions the bearer can perform.

Here are the key ideas of OAuth that make it more secure inherently:

Separation between authentication and authorization: With API keys, proving your identity and getting permissions are the same thing. OAuth splits these apart. An identity provider verifies who you are, an authorization server decides what you can access, and a resource server validates your token. Each component has a single, well-defined job.

Fine-grained scopes defining permissions: Instead of all-or-nothing access, you request specific scopes like read:calendar or write:events. The authorization server issues a token that carries only those permissions. The API server enforces these boundaries automatically.

A simplified OAuth request looks like this:

GET /oauth/authorize?
  response_type=code
  &client_id=cal_agent_a8f3j29dk3
  &redirect_uri=https://myagent.com/callback
  &scope=read:calendar+write:events
  &state=x8f2k9d3j2a
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256 HTTP/1.1
Host: auth.calendar.com

Token-based, short-lived, revocable access: Access tokens typically expire within an hour. When they do, the client uses a refresh token to get a new one without user intervention. But here's the key advantage: you can revoke a refresh token instantly, cutting off access without changing client credentials or redeploying code. The blast radius (extent of damage or impact in case of a leak) of a compromised token is limited to minutes, not months.

Standardized token exchange and per-action downscoping: OAuth defines a standardized mechanism for exchanging one token for another with different scopes, audiences, and lifetimes through OAuth Token Exchange (RFC 8693).

This enables a critical pattern for agentic AI systems: an agent can hold a base delegated token, then exchange it at runtime for narrowly scoped, ephemeral tokens tailored to each specific action or tool invocation.

For example:

An agent exchanges its base token for a calendar:read token when analyzing schedules
It exchanges again for a refund:create token scoped to a specific transaction
Each exchanged token is audience-restricted to the exact API being called and expires within minutes

This ensures agents always operate with the minimum permissions required at the moment of action, dramatically reducing blast radius and preventing privilege accumulation over time.

API keys lack any standardized, interoperable mechanism for token exchange or dynamic downscoping. Any similar behavior must be custom-built, inconsistent, and difficult to audit.

Ability to represent human intent through consent flows: Before any client gets access, the user sees a consent screen listing exactly what permissions are being requested. They click "Allow" or "Deny". This explicit grant means the client (say: an agent) operates with delegated authority, not stolen credentials. Since the user gives permission, it gets recorded.

The diagram below shows how authentication, scopes, consent, and token lifecycle work together in the OAuth flow:

OAuth benefits for modern architectures

The capabilities of OAuth translate into concrete architectural advantages, especially as systems become more distributed and autonomous.

Delegation model aligns with trust boundaries: OAuth is designed for third-party access. An AI agent accessing your Google Calendar is fundamentally a third party, even if you built it yourself. OAuth's delegation model reflects this reality. The agent doesn't hold your password. It holds a limited access that you approved.

Granular access provides least privilege by default: Scopes enforce the principle of least privilege automatically. An agent building calendar summaries gets read:calendar only. An agent scheduling meetings gets read:calendar and write:events. An agent never gets delete:account unless you explicitly grant it.

Revocation and observability of token usage: Every access token is traceable to a specific authorization grant, user, scope set, and timestamp. Your authorization server logs show exactly which agent did what, when, and under whose authority. If an agent misbehaves, you can revoke its token without affecting other systems or users.

Better fit for ecosystems with distributed autonomy and risk: When multiple agents operate semi-independently, each with different trust levels and capabilities, OAuth provides the identity and permission infrastructure to manage that complexity safely. You're not sharing one master key across a dozen autonomous systems. You're issuing narrowly scoped, individually revocable tokens.

Agentic AI: a new category of API client

Traditional API clients follow a script. A cron job runs at midnight, calls API endpoints sequentially, processes the data, and exits. A mobile app waits for user taps, makes predictable API calls, and displays results. The behavior is deterministic. Agentic AI systems are largely autonomous, operating on goals rather than hardcoded instructions. They learn from context, adapt to situations, and generate action sequences you never explicitly programmed.

Consider a customer support agent built with an LLM. A user asks, "Why was I charged twice last month?" The agent doesn't follow a fixed script. Instead, it:

Reasons that it needs to check billing history.
Calls your payments API to retrieve customer transactions.
Analyzes the results and notices a duplicate charge.
Decides to check your refunds API to see if it was already addressed.
Determines it wasn't refunded.
Calls your refunds API to initiate a refund.
Responds to the user with confirmation.

As a developer, you don't program steps 1 through 7 explicitly. Instead, you give the agent access to tools (the APIs), describe what each tool does, and let it figure out the sequence. The agent chains multiple API calls, makes contextual decisions, and takes financial action autonomously.

This is fundamentally different from a webhook that processes a payment and triggers a predefined workflow. The agent's behavior emerges from its training and the situation at hand. It operates beyond simple scripts or predictable machine-to-machine workflows.

Why these characteristics matter for auth

This autonomy creates new security requirements that API keys were never designed to handle:

Need for granular, action-bound permissions: When an AI agent can dynamically choose which APIs to call, you cannot give it blanket access to everything. You need to constrain it to specific actions: read billing data, yes; initiate refunds up to $100 USD, maybe; delete customer accounts, absolutely not.
Need to audit and trace agent actions at fine resolution: When something goes wrong, you need logs that show exactly what the agent did, why, and under whose authority. "API key used at 3:47 PM" is not enough. You need "Agent-CustomerSupport-v2 initiated $47 USD refund for user Alice under scope refunds:create:limited at 3:47 PM."
Need for safe delegation of user authority without exposing secrets: The agent acts on behalf of users, but it should never hold their passwords or master credentials. It needs delegated, scoped authority that represents user intent.
Need for revocable, time-bounded permissions to reduce blast radius: If an agent starts misbehaving for any reason, you should be able to cut off its access immediately with instant revocation.

API keys can't deliver this level of control. You need OAuth for its granular scope enforcement and built-in token revocation.

Comparing API keys vs. OAuth in agentic AI scenarios

Let's look at how a few real-life scenarios could use API Keys vs. OAuth.

Scenario 1: an agent managing a user's calendar

Consider an AI assistant that helps users manage their work calendar by reading events, finding conflicts, and suggesting optimal meeting times.

With API keys

The agent uses a static key with full calendar access:

import requests

API_KEY = "sk_live_calendar_full_access_key"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Agent can read, write, delete anything
events = requests.get("https://api.calendar.com/events", headers=headers)
requests.delete("https://api.calendar.com/events/important-meeting", headers=headers)

The problems are serious. The API key grants complete access to all calendar operations. The agent can delete events, modify attendees, or clear entire calendars, even though it only needs to read events. If the key leaks through logs, prompt injection, or model output, attackers gain full calendar control. There's no user consent, no audit trail showing which specific agent performed which action, and no way to distinguish agent requests from legitimate server operations in logs.

With OAuth

The user explicitly grants limited access through a consent flow:

from requests_oauthlib import OAuth2Session

# Agent requests only read access
oauth = OAuth2Session(
    client_id='calendar_agent_client',
    scope=['read:calendar']
)

# User sees: "Calendar Agent wants to: Read your calendar events"
# User clicks "Allow"
# Agent receives a token limited to reading
token = oauth.fetch_token(
    'https://auth.calendar.com/token',
    authorization_response=callback_url
)

# This works
events = oauth.get('https://api.calendar.com/events')

# This fails - token doesn't have write:calendar scope
oauth.post('https://api.calendar.com/events', json={...})  # 403 Forbidden

The token expires after an hour. If the agent misbehaves, the user revokes access instantly from their security settings. Audit logs clearly show: "calendar_agent_client accessed user Alice's calendar with scope read:calendar at 2:34 PM". The blast radius is contained.

Scenario 2: an agent automating developer tooling

Now let's consider an AI agent that helps developers by automatically creating GitHub issues from Slack conversations, assigning them to the right team members, and updating project boards.

With API keys

A GitHub personal access token with full repo access sits in the agent's configuration:

GITHUB_TOKEN = "ghp_full_repo_access_token"
headers = {"Authorization": f"token {GITHUB_TOKEN}"}

# Agent can do anything
requests.post("https://api.github.com/repos/company/prod/issues",
    headers=headers,
    json={"title": "Bug found"})

# Including destructive operations it shouldn't
requests.delete("https://api.github.com/repos/company/prod",
    headers=headers)

The static token allows the agent to delete repositories, modify branch protection rules, or leak source code. There's no time limit, no scope restriction, and no clear audit trail linking actions back to the specific agent instance.

With OAuth

The agent requests narrowly scoped access:

# Agent requests specific permissions
oauth = OAuth2Session(
    client_id='dev_agent_client',
    scope=['repo:issues:write', 'project:read']
)

# Token is bound to specific repos and actions
token = oauth.fetch_token(...)

# Agent can create issues
oauth.post('https://api.github.com/repos/company/prod/issues',
    json={"title": "Bug found"})

# But cannot delete repos or access code
oauth.delete('https://api.github.com/repos/company/prod')  # 403 Forbidden

OAuth scopes restrict the agent to creating issues and reading project boards. The token expires after an hour and can be revoked if the agent starts creating spam issues. GitHub's audit log shows exactly which agent, acting under whose authority, performed each action.

Scenario 3: multi-agent workflows

Now consider an agentic system where multiple specialized agents collaborate: one agent researches competitors, another drafts marketing copy, and a third publishes content to your CMS.

With API keys

All agents share the same CMS API key:

SHARED_CMS_KEY = "cms_full_access_key"

# Research agent (should only read)
research_agent.set_credentials(SHARED_CMS_KEY)

# Writing agent (should read and draft)
writing_agent.set_credentials(SHARED_CMS_KEY)

# Publishing agent (should publish drafts)
publishing_agent.set_credentials(SHARED_CMS_KEY)

# All have identical, full access

This creates multiple problems. The research agent can accidentally publish content. The writing agent can delete published articles. If any agent is compromised, all three are compromised because they share credentials. Server logs show "CMS key used" but not which agent or why. There's no way to represent each agent's actual role and permissions.

With OAuth

Each agent gets its own identity and scoped token:

# Research agent - read-only access
research_oauth = OAuth2Session(
    client_id='research_agent',
    scope=['content:read']
)

# Writing agent - read and draft
writing_oauth = OAuth2Session(
    client_id='writing_agent',
    scope=['content:read', 'content:draft']
)

# Publishing agent - publish only
publishing_oauth = OAuth2Session(
    client_id='publishing_agent',
    scope=['content:publish']
)

Each agent operates with least privilege. The research agent cannot modify content. The writing agent cannot publish. The publishing agent cannot delete. If the writing agent is compromised through prompt injection, the attacker gains only drafting capabilities, not publishing or deletion. Audit logs clearly attribute each action to a specific agent identity with specific permissions.

Why the Model Context Protocol mandates OAuth

The Model Context Protocol (MCP) is an open standard defining how AI systems should securely interact with external tools and data sources. MCP provides a structured way for agents to discover available tools, understand their capabilities, and invoke them safely.

While MCP makes authorization optional for low-risk scenarios, it mandates OAuth 2.1 when agents access user data or act on behalf of users, precisely the scenarios where autonomous agents make real-time decisions about tools and actions.

MCP encourages OAuth 2.1 for the ability for every tool to explicitly define its required access scopes. When an agent wants to use a tool, it must authenticate using OAuth flows designed for agents running on servers without a traditional user interface (i.e., headless). This typically means device flow (where users authorize on a separate device by entering a code) or authorization flows with Proof Key for Code Exchange (PKCE): a security extension that prevents authorization code theft by requiring a secret only the legitimate client knows. These flows ensure users grant explicit consent for the specific permissions each tool needs.

MCP requires auditable, revocable, and safe delegation of authority. Each tool invocation is traceable to a specific token, scope set, and user consent. When an agent misbehaves or a tool becomes compromised, admins can revoke access immediately without affecting other tools or redeploying code.

API keys lack the granularity, traceability, and revocation mechanisms MCP's security model requires. By mandating OAuth, MCP ensures agentic systems operate within clearly defined, user-controlled permission boundaries.

When API keys still make sense

OAuth isn't always the perfect choice. There are legitimate scenarios where API keys remain a more practical choice.

Non-agentic M2M automation: Internal microservice calls on private networks don't need OAuth's complexity. When Service A calls Service B within your infrastructure, both under your complete control, a rotated API key works fine. The same applies to simple backend processes with predictable behavior (i.e., nightly ETL jobs, monitoring scripts, deployment pipelines). These systems follow deterministic logic with no autonomous decision-making.

Low-risk or high-control environments: Internal admin tools accessible only from corporate networks, behind VPNs, with IP restrictions and vault-managed secrets, can safely use API keys. The infrastructure itself enforces security boundaries.

Startups or prototypes: Early-stage products validating product-market fit can use API keys to move fast. However, OAuth migration might be required for scaling.

Did you know? Major AI providers like OpenAI and Anthropic still use API keys for millions of users because they're authenticating developer applications, not autonomous agents acting on behalf of end users. When those applications need to perform user-specific actions with granular permissions, OAuth becomes necessary at that layer.

Quick implementation guidance and best practices

Use this decision tree to choose authentication based on your requirements:

For OAuth in agentic AI systems

Implement narrow scopes: Avoid wildcard permissions like admin:* or full_access. Define granular scopes that match actual operations: calendar:read, issues:create, content:draft.
Prefer short-lived access tokens with automatic refresh: Set access token expiration to one hour or less. Use refresh tokens to obtain new access tokens without user intervention.
Require explicit user consent flows: Users must see and approve exactly what permissions they're granting.
Bind agent identity to token issuance: Each agent instance should have its own client ID. This allows per-agent revocation and helpful audit trails.
Enable complete audit logging: Log every token issuance, refresh, and API call with agent identity, scope, timestamp, and user context.
Use Authorization Code Flow with PKCE and Device Code Flow: For agents running on servers or in automated environments, these flows provide secure authentication without traditional browser redirects.

For API keys

Rotate regularly and automatically: Implement 90-day rotation schedules with zero-downtime deployment strategies.
Store keys in secure vaults: Use dedicated secret management systems like Google Secrets Manager or similar.
Apply API rate limits and behavioral analytics: Monitor for unusual patterns that might indicate compromise.
Restrict IP addresses or environments: Limit key usage to known networks or infrastructure.
Transition to OAuth once agents enter the ecosystem: Plan this migration before adding autonomous capabilities.

Conclusion

Agentic AI is transforming API authentication requirements. The simplicity of API keys comes at a cost: no granular permissions, no revocation, and limited auditability. OAuth provides the delegation model, scoped access, and security controls that autonomous systems demand. With protocols like MCP mandating OAuth for tool access, the industry is converging on a clear standard for intelligent, autonomous systems.

OAuth implementation is becoming necessary for AI agents. Descope provides purpose-built authentication for agentic AI systems, with pre-configured OAuth flows, granular scope management, and agent identity infrastructure that scales from prototype to production.

Add Authentication and RBAC to a Webflow App

Mrunank Pawar — Wed, 15 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

Authentication and authorization are essential for controlling user access and actions within applications, ensuring the right people can do the right things. However, implementing these features can be complex and error-prone, especially in Webflow, where server-side logic isn't easily accessible. Ineffective management of sessions and user roles can expose your application to security vulnerabilities.

Consider a typical Webflow content management system (CMS) where team members collaborate on content but their access must vary based on their roles. Writers should manage only their own articles, while editors require full control to publish, delete, or oversee other authors' work. Role-based access control (RBAC) simplifies this by assigning roles—such as Writer or Editor—to users and granting permissions accordingly.

Traditionally, implementing authentication and RBAC required significant backend development and ongoing maintenance. With Descope, you can add these features to your Webflow app without writing complex backend code. Descope provides a visual workflow editor, Descope Flows, for authentication and integrated RBAC functionality, enabling you to add these features to your Webflow app without backend complexity. This tutorial will guide you through securing your Webflow CMS with Descope social login, email verification, and role-based permissions.

Setting up your Descope project and configuring an authentication flow

Before implementing authentication and RBAC in your application, let's set up the development environment and configure Descope to meet your needs.

Head over to the Descope website and create your free account. Once you've successfully created an account, you'll be guided through creating an authentication flow that matches your application's needs:

For a CMS application, you want to offer both email-based and social authentication to give users some flexibility in their preferred sign-in method.

Navigate to the Flows section in the Descope Console and click Start from scratch:

Since this flow handles both new user registration and existing user authentication for the CMS, you can name it "publishpro auth flow". The flow editor presents a visual canvas where you design the authentication experience:

Creating and adding elements to the authentication interface

You can now build the authentication interface by creating a Sign Up or Sign In screen. Click the + button to drag and drop a new screen. Inside the screen, click the screen body text element. On the right panel of the editor, go to the Content section and update the text to "Welcome to PublishPro". Then, scroll down to the Style section and set the style to the H2 element, as shown here:

Drag and drop a Container element from the list of elements in the left panel of the screen. Then drag and drop an Email input element and a Button element inside this container. Select the Button and rename its Text value to "Submit" on the right panel. Then adjust its width to fit that of the container by toggling the Fill container button. Here's what it should look like:

Adding social login

This setup handles email OTP authentication, providing a passwordless option for users. Next, you'll add social login as an alternative authentication method.

To clearly distinguish between the two authentication methods, add a divider element between the methods. On the left panel, scroll down to the TEXT section and drag and drop a Divider element below the Button element:

While still on the left panel, scroll to the BUTTONS section and add a Google button from the list of OAuth providers right under the divider. You can choose other OAuth providers from the existing list, but this example uses only Google:

With that in place, you can click the Done button to return to the canvas. Here, you see the newly created screen, so connect it to the START of the flow, as follows:

Linking the submit and socials buttons

The next step is to link the Submit and Socials buttons on the newly created Sign Up or Sign In screen to their respective actions, ensuring they trigger the intended functionality when clicked. Click the + button and select Action. Then, search for and add both Sign Up or In / OTP / Email and Sign Up or In / OAuth actions to the canvas. Connect the Submit button to the Sign Up or In / OTP / Email action to handle email authentication and connect the Socials button to the Sign Up or In / OAuth action to handle social login:

These custom actions contain both actions and screens that handle the common flows inherent in OTP and OAuth authentication methods.

Handling new and existing users

You also need to differentiate between new and existing users to customize their authentication experience. This can be done using the Condition option. Click the + button and select Condition to open a dialog for configuring an If-Else check. Set the step name to New/Existing User. In the If block, name it "New user" and use the authInfo.firstSeen key with the Is True operator to identify first-time logins. For the Else block, simply name it "Existing" since it automatically handles returning users. Save the condition to complete the setup:

Connect both Verify Code / OTP / Email and Sign Up or In / OAuth actions to the newly created condition so it performs the check every time a user logs in:

Next, a new screen, New user, needs to be added so that new users can provide their username and full name. To do this, create a new screen and add a Container element to the screen. Then inside the container, drag and drop the Display Name and Given Name inputs from the INPUTS section on the left panel. Also, add a button and change its text value to Continue. Remember to remove the screen body text element and save the new screen:

After creating the screen, you need to add an action to update the user's profile. Click the + button, select Action, and in the Actions dialog that appears, search for and select Update User / Attributes. Edit the action to map the input fields from the New user screen (form.displayName for Display Name and form.givenName for Given Name) to their corresponding user attributes, ensuring new users' profile information is properly stored:

Completing the flow

With the user detail collection screen and the update actions in place, you need to complete the flow by connecting these last two components. Start by connecting the New user screen's Submit button to the Update User / Attributes action, which ensures that when new users submit their details, the information gets properly stored in their user profile. The flow then needs two distinct paths to completion. The first path connects the Update User / Attributes action to the END node, handling new users who have just provided their additional information. The second path connects the Existing branch from the New/Existing user condition directly to the END of the flow, creating a streamlined experience for returning users who don't need to provide additional details. These connections work together to create two separate journeys through the authentication flow—one that collects necessary information from first-time users and another that provides a faster route for those returning to your application.

Here is the final version of the flow you just created:

Save the flow and click the Run button to test run the flow directly on the Descope Console:

Understanding the PublishPro application

The starter application is a CMS that currently lacks any authentication or access control.

Here is the Webflow app. Currently, anyone, without signing in, can access the dashboard, see all articles in the system, and access creation, editing, deletion, and publishing features:

While the application includes a navigation bar with a Sign In button, it lacks any functionality since authentication isn't implemented. This unrestricted access highlights two key security needs: protecting the dashboard behind authentication and implementing different access levels for various user roles.

Implementing authentication

Now that the authentication flow is set up in Descope, let's integrate it into the CMS application. You need to add the Descope web component and implement the authentication logic.

Adding the required scripts

To start, let's add the required Descope scripts, Descope web component, and user profile widget scripts to the Head code section of the Webflow app. These scripts provide the core functionality for the authentication system and user profile management. On the Webflow dashboard, under the Custom code tab of the site's settings, add the following scripts:

<script async src="https://unpkg.com/@descope/web-component@latest/dist/index.js"></script>
<script async src="https://static.descope.com/npm/@descope/user-profile-widget@0.0.113/dist/index.js"></script>

Remember to save the changes by clicking the Save button to successfully add the scripts to the Webflow app:

Descope provides a list of widgets that you can easily integrate alongside your authentication code to manage users' sessions:

Click the Show Code button and select the Web Component option to see the sample code included in the preceding code snippet.

Adding authentication and user profile modals

Next, create a Code embed element for the authentication. You need two key components: an authentication modal and a user profile modal. These components handle user sign-in and profile management, respectively.

For the authentication modal, create it under the Body element and name it auth-modal:

<!-- Auth Modal -->
<div class="auth-modal">
  <div class="auth-container">
    <descope-wc
      project-id="YOUR_PROJECT_ID"
      flow-id="publishpro-auth-flow"
      theme="light"
    />
  </div>
</div>

Make sure to replace YOUR_PROJECT_ID with the project ID from your Descope Console:

Next, let's also create the user profile modal next to the Sign In button and name it user-profile:

<!-- Authenticated State -->
<div id="user-profile" class="user-profile">
  <span id="user-name" class="user-name"></span>
  <div
    id="profile-widget-container"
    class="profile-widget-container"
  >
    <descope-user-profile-widget
      project-id="YOUR_PROJECT_ID"
      widget-id="user-profile-widget"
      theme="light"
    />
  </div>
</div>

Remember to replace the YOUR_PROJECT_ID with your project ID as well here:

Since authentication is being implemented, the dashboard of the app should be visible only to authenticated users. Let's create a new Combo class named w-hide with style display: none !important to hide the dashboard from unauthorized users. Add this new class to the existing main_wrapper class as well as to the auth-modal and the user-profile modal:

Enhancing with custom styles

You can use the <style> tag to add custom styles for the modals and other utility classes created in the remaining part of the project. This includes styles for the auth-modal, user-profile, and widget-containers. Navigate back to the dashboard, check under the Custom code tab, and add the following CSS below the two <script> tags in the Head code section:

<style>
  .auth-modal {
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background-color: rgba(0, 0, 0, 0.5);
    display: flex;
    justify-content: center;
    align-items: center;
    z-index: 999;
  }

  .auth-container {
    background-color: #ffffff;
    padding: 20px;
    border-radius: 8px;
    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
  }

  .user-profile {
    display: flex;
    align-items: center;
    gap: 1rem;
  }

  .user-name {
    color: #ffffff;
    font-weight: 500;
  }

  /* Utility Classes */
  ._w-hide {
    display: none !important;
  }

  .user-profile {
    position: relative;
    display: flex;
    align-items: center;
    gap: 1rem;
  }

  .user-name {
    color: #ffffff;
    font-weight: 500;
    cursor: pointer;
    padding: 8px;
  }

  .user-name:hover {
    background-color: rgba(255, 255, 255, 0.1);
    border-radius: 4px;
  }

  .profile-widget-container {
    position: absolute;
    top: 100%;
    right: 0;
    margin-top: 8px;
    display: none;
    z-index: 1000;
  }

  /* Add some shadow and background to the widget */
  descope-user-profile-widget {
    background: white;
    border-radius: 8px;
    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1),
      0 2px 4px -1px rgba(0, 0, 0, 0.06);
  }
</style>

Remember to click the Save button for the styles to take effect on the project:

Implementing custom authentication

Next, let's add custom authentication to your Webflow app. To do this, go to the Custom code tab, scroll down to the Footer code section, and paste the code before the closing </body> tag. Let's break this down into easy steps.

To begin, you need to wait for the DOM to be fully loaded. Then set up the necessary DOM elements and initialize event listeners:

<script async>
document.addEventListener('DOMContentLoaded', function () {
  // Get references to all the UI elements needed to be manipulated
  const authModal = document.querySelector('.auth-modal');
  const mainWrapper = document.querySelector('.main_wrapper');
  const signInButton = document.querySelector('.sign-in-btn');
  const userProfile = document.querySelector('.user-profile_container');
  const userName = document.getElementById('user-name');
  const profileWidgetContainer = document.getElementById('profile-widget-container');
  const sidebar = document.querySelector('.sidebar_wrapper');
  const dashboard = document.querySelector('.dashboard_wrapper');

  // Initialize Descope authentication components
  const authComponent = document.querySelector('descope-wc');
  authComponent.addEventListener('success', handleAuthSuccess);
  authComponent.addEventListener('error', handleAuthError);

  // Set up the profile widget with logout handling
  const profileWidget = document.querySelector('descope-user-profile-widget');
  profileWidget.logout = handleLogout;

This preceding initialization code ensures the app has access to all the necessary elements and sets up the Descope authentication component with its event listeners. Think of it as gathering all the tools before starting work.

Making the authentication interface interactive

Next, you need to handle user interactions with the authentication interface. This includes showing the login modal and managing the profile widget:

  // Show the auth modal when users click sign in
  signInButton.addEventListener('click', function () {
    authModal.classList.remove('_w-hide');
  });

  // Toggle the profile drop-down when users click their name
  userProfile.addEventListener('click', function() {
    if (profileWidgetContainer.style.display !== "block")
      profileWidgetContainer.style.display = "block";
    else
      profileWidgetContainer.style.display = "none";
  });

  // Handle returning from social login
  const urlParams = new URLSearchParams(window.location.search);
  const isDescopeOAuthReturn = urlParams.has("descope-login-flow");
  if (isDescopeOAuthReturn) {
    authModal.classList.remove("_w-hide");
  }

These event listeners create the interactive elements of the authentication system. The code responds to user actions like clicking the sign-in button or toggling their profile menu. You also handle the special case of users returning from the social login.

Managing user sessions

The heart of the authentication system lies in how successful logins, errors, and logouts are handled. The following functions manage the user's session and update the interface accordingly:

  function handleAuthSuccess(e) {
    const { refreshJwt, user } = e.detail;

    // Store the user's session data securely
    localStorage.setItem('DSR', refreshJwt);
    localStorage.setItem('user_data', JSON.stringify(user));

    const userDataString = localStorage.getItem('user_data');
    const userData = JSON.parse(userDataString);

    // Show authenticated UI
    authModal.classList.add('_w-hide');
    signInButton.classList.add('_w-hide');
    userProfile.classList.remove('_w-hide');
    sidebar.classList.remove('_w-hide');
    dashboard.classList.remove('_w-hide');
    mainWrapper.classList.remove('_w-hide');

    if (user.name) {
      userName.textContent = user.name;
      userName.title = "Click to manage profile";
    }

    window.location.reload();
  }

  function handleAuthError(err) {
    console.error('Auth Error:', err);
  }

  function handleLogout(error) {
    if (error) {
      console.error('Logout Error:', error);
      return;
    }

    // Clean up session data and refresh
    localStorage.removeItem('DSR');
    localStorage.removeItem('user_data');
    window.location.reload();
  }

When authentication succeeds, the app securely stores the user's session data and updates the UI to show they're logged in. If something goes wrong, it logs the error. The logout function cleans up by removing stored data and refreshing the page.

Finally, handle session persistence so users don't need to log in every time they visit:

  // Check if user already has a valid session
  const token = localStorage.getItem('DSR');
  const userDataString = localStorage.getItem('user_data');
  const payload = JSON.parse(atob(token.split('.')[1]));
  const expiration = payload.exp * 1000;

  if ((Date.now() < expiration) && userDataString) {
    const userData = JSON.parse(userDataString);

    authModal.classList.remove('_w-hide');
    signInButton.classList.add('_w-hide');
    signInButton.classList.add('_w-hide');
    userProfile.classList.remove('_w-hide');
    mainWrapper.classList.remove('_w-hide');

    if (userData.name) {
      userName.textContent = userData.name;
    }
  } else {
    localStorage.removeItem('DSR');
    localStorage.removeItem('user_data');
  }
});
</script>

This code checks for an existing session when the page loads. If found, it automatically restores the user's authenticated state without requiring them to log in again.

Testing the authentication

To test this implementation, you can either publish your app or use the Webflow preview feature. The code creates a seamless authentication experience where users can sign in, maintain their session across page loads, and safely sign out when needed:

Users can manage their profile through the profile widget that appears when clicking their name:

Implementing RBAC

With authentication in place, you can now implement RBAC to manage different user permissions within the CMS. The application defines two roles with distinct permissions: Writers can create and edit their own articles, and Editors have full access, including publishing and deleting articles.

Creating roles and permissions

To create the roles and permissions in the Descope Console, navigate initially to the Authorization section. Under the RBAC tab, locate the Permissions section in the right panel. You're creating four distinct permissions that represent the core actions in the CMS. Start by clicking + Permission to create CreateArticleDrafts—this fundamental permission enables users to create new article drafts in the system. When setting up this permission, include a clear description explaining its purpose, such as "Allows creation of new article drafts in the CMS."

Continue adding permissions by creating UpdateArticleDrafts, which controls the ability to edit existing drafts. Follow this with the DeleteArticleDrafts to manage article removal privileges and, finally, PublishArticleDrafts to control who can publish articles publicly. For each permission, take time to write a descriptive explanation that will help you and future administrators understand its intended use.

Once your permissions are in place, move to the Roles panel to establish the two key roles needed for the CMS. Begin with the Writer role by clicking + Role. Writers need the ability to create and modify content, so assign them the CreateArticleDrafts and UpdateArticleDrafts permissions. Include a description, like "Content creators who can write and edit drafts," to clearly define their responsibilities.

Next, create the Editor role, which requires more comprehensive access. Editors need oversight of the entire content lifecycle, so assign them all four permissions: CreateArticleDrafts, UpdateArticleDrafts, DeleteArticleDrafts, and PublishArticleDrafts. Add a description, such as "Content managers with full article control," to document their broader responsibilities.

Here's the Authorization page with RBAC set up:

This permission structure mirrors common editorial workflows where writers focus on content creation and editors manage the overall publication process. Writers can develop and refine content, while editors maintain quality control through their additional abilities to remove content and determine what gets published.

Assigning roles

Once you have created the roles, head over to the Users section and update the existing users by assigning them roles as you chose:

Let's modify the application to show or hide features based on user roles. Update the Footer code script to include the following permission-checking functionality:

function checkPermission(user, permission) {
  const hasEditorRole = user.roleNames &&
    user.roleNames.some(role =>
      role.toLowerCase() === 'editor'
    );
  const hasWriterRole = user.roleNames &&
    user.roleNames.some(role =>
      role.toLowerCase() === 'writer'
    );

  // Editor has all permissions
  if (hasEditorRole) {
    return true;
  }

  // Writer has create and update permissions
  if (hasWriterRole) {
    return ['create', 'update'].includes(permission);
  }

  return false;
}

When the checkPermission function is called, it checks the user's roles using case-insensitive comparison (toLowerCase()) and then makes permission decisions based on a simple rule: if the user is an editor, they can access everything; but if the user is a writer, they only get access to create and update actions. Any other role or permission combination results in no access being granted.

Implementing permissions

Now, you need to tell the application which UI elements should be restricted based on user roles. You do this by adding custom data attributes to the buttons. These attributes act like permission labels, telling the code which buttons should be visible to which users.

Open the Webflow Editor and navigate to the Settings tab in the right panel. For each button in the interface, you add the appropriate permission attribute based on its function. Add data-permission="update" to Edit buttons, data-permission="delete" to Delete buttons, and data-permission="publish" to Publish buttons. These attributes work with an updateUIBasedOnPermissions function to dynamically show or hide buttons based on the user's role:

Updating the UI

With that in place, you can update the UI based on the user's roles when they authenticate. To do so, let's create the updateUIBasedOnPermissions function by updating the Footer code script to include the following snippet:

function updateUIBasedOnPermissions(user) {
  const permissions = ['create', 'update', 'delete', 'publish'];

  permissions.forEach(permission => {
    const elements = document.querySelectorAll(`[data-permission="${permission}"]`);
    const shouldDisplay = checkPermission(user, permission);

    elements.forEach(element => {
      element.style.display = shouldDisplay ? 'inline-block' : 'none';
    });
  });

  if (user.roleNames) {
    const isEditor = user.roleNames.some(role => role.toLowerCase() === 'editor');
    const isWriter = user.roleNames.some(role => role.toLowerCase() === 'writer');

    document.querySelectorAll('[data-role="editor"]').forEach(element => {
      element.style.display = isEditor ? 'block' : 'none';
    });

    document.querySelectorAll('[data-role="writer"]').forEach(element => {
      element.style.display = isWriter ? 'block' : 'none';
    });
  }
}

The updateUIBasedOnPermissions function manages the visibility of UI elements based on a user's role and permissions by checking all elements with specific data attributes (data-permission and data-role) and showing or hiding them accordingly.

To ensure this function is called when a user successfully authenticates, update the handleAuthSuccess function as shown here:

function handleAuthSuccess(e) {
  const { refreshJwt, user } = e.detail;

  localStorage.setItem('DSR', refreshJwt);
  localStorage.setItem('user_data', JSON.stringify(user));

  const userDataString = localStorage.getItem('user_data');
  const userData = JSON.parse(userDataString);

  const userDataString = localStorage.getItem('user_data');
  const userData = JSON.parse(userDataString);

  // Update UI based on roles and permissions
  updateUIBasedOnPermissions(userData);

  // Show authenticated UI
  authModal.classList.add('_w-hide');
  signInButton.classList.add('_w-hide');
  userProfile.classList.remove('_w-hide');
  sidebar.classList.remove('_w-hide');
  dashboard.classList.remove('_w-hide');
  mainWrapper.classList.remove('_w-hide');

  if (user.name) {
    userName.textContent = user.name;
    userName.title = "Click to manage profile";
  }

  window.location.reload();
}

In addition, update the initial authentication check to include permission-based UI updates:

// Check auth state on load
const token = localStorage.getItem('DSR');
const userDataString = localStorage.getItem('user_data');
const payload = JSON.parse(atob(token.split('.')[1]));
const expiration = payload.exp * 1000;

if ((Date.now() < expiration) && userDataString) {
  const userData = JSON.parse(userDataString);

  // Update permissions
  updateUIBasedOnPermissions(userData);

  signInButton.classList.add('_w-hide');
  userProfile.classList.remove('_w-hide');
  sidebar.classList.remove('_w-hide');
  dashboard.classList.remove('_w-hide');
  mainWrapper.classList.remove('_w-hide');

  if (userData.name) {
    userName.textContent = userData.name;
  }
} else {
  localStorage.removeItem('DSR');
  localStorage.removeItem('user_data');
}

Updating the sidebar

Finally, you need to apply the permission system to the sidebar's Quick Actions buttons to ensure they follow the same role-based rules as the other interface elements. In the Webflow Editor, open the Settings panel for the New Articles button in the sidebar. Just as you did with the other buttons, add the data-permission="create" attribute to ensure only users with article-creation permissions can see this button.

The Analytics button requires a different approach since it's a feature specifically for editors. Open its Settings panel and add the data-role="editor" attribute. Using a role-based attribute here makes sense because analytics access is tied to the editor role itself rather than a specific permission.

These attribute additions connect the Quick Actions buttons to the permission-checking system built, ensuring consistent access control throughout the interface. When a user logs in, these buttons automatically show or hide based on their assigned role, just like the other UI elements:

The next step would be to implement these same permission checks on your backend API using one of the Descope SDKs, but that's beyond the scope of this tutorial since the focus is on the frontend implementation with Webflow.

Conclusion

In this tutorial, you transformed a basic CMS into a secure, role-aware application using the Descope authentication and authorization capabilities. What makes this implementation particularly powerful is how robust security features were achieved without complex backend code, making it perfect for Webflow applications. Through the Descope visual flow editor, you created a customized authentication flow that offers both email OTP and social login options, providing users with flexible, secure authentication methods.

The integration of the Descope web component and user profile widget, combined with RBAC, demonstrates how modern authentication can be implemented in Webflow applications without sacrificing security or user experience. This tutorial transforms a vulnerable Webflow app into a more secure CMS where content creators and editors can collaborate safely within their designated roles.

To stay up to date with more developer tutorials, subscribe to the Descope blog or follow us on LinkedIn.

Modernize Auth Without Changing Your Firebase Sessions

Mrunank Pawar — Mon, 13 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

If your app is built on Firebase, authentication tends to sit right at the center of everything. Firestore rules, Cloud Functions, Storage access, and even analytics all assume there's a valid Firebase user session.

At the same time, Firebase Auth can feel limiting once you want to go beyond basic email/password or simple social login. Adding things like passkeys, flexible MFA, or more nuanced sign-in and recovery flows usually means a lot of custom work — or compromises in UX.

Descope External Tokens is designed for exactly this situation. It lets you run Descope Flows natively in your app, then hand off to Firebase at the very end so you still end up with a real Firebase session.

In other words: Descope handles authentication while Firebase continues to power everything else in your app.

External Tokens 101

By using Descope External Tokens with Firebase, Descope is the place where authentication happens, and Firebase is the place where sessions are consumed.

The flow looks like this:

The user signs in using a Descope Flow (passwordless, social, passkeys, MFA — whatever you've defined).
When the Flow finishes successfully, Descope returns an externalToken. That token is a Firebase custom auth token, signed by Descope using your Firebase admin credentials.
Your app calls signInWithCustomToken with Firebase.
Firebase creates a normal session, just as if the user had signed in directly with Firebase Auth.
Once that's done, your app is "Firebase authenticated" in the usual way.

Why use External Tokens

This pattern is useful if:

You want to use Descope's auth flows and UI
You don't want redirects or awkward webviews
You already rely heavily on Firebase services
You don't want to rebuild your backend or security rules

You're not replacing Firebase, you're simply plugging Descope into it.

Setting up the Firebase External Token Connector

To generate Firebase custom tokens, Descope needs access to your Firebase project's service account. This is done through a Firebase External Token connector.

This integration allows you to continue using Firebase's services while replacing Firebase Auth with Descope Flows.

Configuring the connector in Descope

In the Descope Console, navigate to the Connectors page and create a new connector using the Firebase template. You'll be asked to provide:

Connector Name: A unique name to help distinguish this connector (especially useful if you have multiple Firebase projects or environments).
Connector Description: A short description explaining what the connector is used for.
Service Account private key: The JSON credentials from your Firebase project. This allows Descope to securely sign Firebase custom tokens.

Getting the Firebase service account JSON

To generate a service account key in Firebase:

Open the Firebase Console and select your project
Click the gear icon and go to Project settings
Open the Service Accounts tab
Click Generate new private key
Download the JSON file

Open the file and copy the entire contents, including the surrounding braces.

Back in the Descope Console, paste this JSON into the Service Account field of the Firebase connector configuration. After saving, use the Test button to confirm the credentials were added correctly.

At this point, the connector itself is fully configured.

Enabling the connector for External Tokens

Once the connector exists, it needs to be enabled for use in authentication flows.

Go to Project Settings in the Descope Console
Open the External Token section and enable External Tokens
Select the Firebase connector you just created

From this point on, Descope will automatically generate a Firebase custom token at the end of a successful flow.

What the authentication response looks like

After a user successfully completes a Descope Flow, the authentication response includes an externalToken field. This value is the Firebase custom token your app should exchange immediately.

Here's what an example response looks like:

{
  "cookieDomain": "",
  "cookieExpiration": 0,
  "cookieMaxAge": 0,
  "cookiePath": "/",
  "externalToken": "FIREBASE_TOKEN",
  "firstSeen": false,
  "idpResponse": null,
  "refreshJwt": "DESCOPE_REFRESH_TOKEN",
  "sessionExpiration": 1750879215,
  "sessionJwt": "DESCOPE_SESSION_TOKEN",
  "user": {}
}

A React web example

On the web, the integration is straightforward: run a Descope Flow, grab the external token, and pass it to Firebase.

Firebase setup

import { initializeApp } from "firebase/app";
import { getAuth } from "firebase/auth";

const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_PROJECT.firebaseapp.com",
  projectId: "YOUR_PROJECT_ID",
  appId: "YOUR_APP_ID",
};

export const app = initializeApp(firebaseConfig);
export const auth = getAuth(app);

Running a Flow and creating a Firebase session

import { AuthProvider, Descope } from "@descope/react-sdk";
import { signInWithCustomToken } from "firebase/auth";
import { auth } from "./firebase";

export default function App() {
  const onSuccess = async (e: any) => {
    const externalToken = e?.detail?.externalToken;
    if (!externalToken) {
      throw new Error("Missing Firebase external token");
    }
    await signInWithCustomToken(auth, externalToken);
    console.log("Firebase user:", auth.currentUser?.uid);
  };

  return (
    <AuthProvider projectId="YOUR_DESCOPE_PROJECT_ID">
      <Descope
        flowId="YOUR_FLOW_ID"
        onSuccess={onSuccess}
        onError={(e) => console.error(e)}
      />
    </AuthProvider>
  );
}

At this point, Firestore rules, Storage access, and Functions all work exactly as they did before.

A React Native example

Note: The Descope React Native SDK does not currently support Expo. If you're using Expo, follow the Expo OIDC integration instead.

Install the SDK

npm install @descope/react-native-sdk

For iOS:

cd ios && pod install

Wrap your app

import { AuthProvider } from "@descope/react-native-sdk";

export default function AppRoot() {
  return (
    <AuthProvider projectId="YOUR_DESCOPE_PROJECT_ID">
      <App />
    </AuthProvider>
  );
}

Running a Flow and creating a Firebase session

import { FlowView, useSession } from "@descope/react-native-sdk";
import auth from "@react-native-firebase/auth";

function LoginScreen() {
  const { manageSession } = useSession();

  return (
    <FlowView
      flowOptions={{
        url: "https://auth.descope.io/login/YOUR_PROJECT_ID",
        androidOAuthNativeProvider: "google",
        iosOAuthNativeProvider: "apple",
      }}
      onSuccess={async (jwtResponse) => {
        // Save the Descope session
        await manageSession(jwtResponse);

        // Exchange the external token for a Firebase session
        const externalToken = jwtResponse.externalToken;
        await auth().signInWithCustomToken(externalToken);
      }}
      onError={(err) => console.error(err)}
    />
  );
}

After this runs:

Descope manages the auth session lifecycle
Firebase manages the infrastructure session
Your app can safely use both

Descope Auth, Firebase sessions

Descope External Tokens give you a practical way to modernize authentication without undoing the work you've already invested in Firebase. You can build richer, more flexible sign-in experiences using Descope Flows, while continuing to rely on Firebase for sessions, access control, and the rest of your backend.

The integration point is intentionally simple: authenticate with Descope, exchange the returned token with Firebase, and move on. There's no custom token service to maintain, no changes to your Firebase rules, and no need to rethink how your app is structured.

It's also worth noting that External Tokens aren't the only way to connect Descope and Firebase. If you prefer not to use signInWithCustomToken at all, Descope can also be configured as a federated OIDC identity provider for Firebase. In that setup, Firebase handles the session directly after an OIDC login — but the tradeoff is that the authentication flow includes an OIDC redirect.

Both approaches are valid. External Tokens are usually the better fit when you want a fully native, no-redirect experience, especially on mobile. OIDC federation can be a good option if redirects are acceptable and you want Firebase to remain the system that completes the sign-in.

Either way, Descope lets you evolve authentication independently of the rest of your Firebase stack: and that flexibility is often the biggest win.

Sign up for Descope to begin your drag & drop auth journey. Have questions about our platform? Book a demo with our auth experts.

Adding Authentication and Remote Support to a Local MCP Server

Mrunank Pawar — Fri, 10 Apr 2026 15:00:00 +0000

This blog was originally published on Descope.

Model Context Protocol (MCP) servers allow developers to connect large language models (LLMs) to external tools and resources through a standardized protocol. Some MCP servers are designed to run locally, often because they need to access resources that are in the same environment as the AI agent. Others are designed to run remotely, such as when exposing shared APIs, cloud-hosted tools, or team-wide services. Remote access is powerful, but without proper controls, it can easily become a security risk.

An unsecured MCP server exposed to the internet can be discovered by automated scanners, abused by unauthorized users, or even used to extract sensitive data from connected resources. Nevertheless, with proper authentication and authorization in place, remote MCP servers can unlock new collaboration models. Teams can share cloud-hosted tools and services, manage who can access which resources, and even integrate audit logs for compliance and observability. This makes MCP servers safer and more practical in enterprise or team-based environments.

In this guide, you'll learn how to take a local Playwright MCP server and make it remote-ready with authentication powered by Descope. You'll expose your server for secure remote access, add user authentication using Descope Flows, and implement role-based access control (RBAC) to ensure only authorized users can access sensitive tools.

Prerequisites

To complete this tutorial, you need the following:

A Descope account
Node.js v18+ installed on your local machine.
The assets ZIP folder downloaded and extracted. The folder includes a preprepared Descope flow that you will use later in this guide.
A code editor and a web browser.

Preparing the local MCP server

The Playwright MCP server exposes a set of tools that let LLMs interact with Playwright to perform actions such as running browser tests, inspecting pages, taking screenshots, and more. For example, you can use it to build an AI agent that automates quality assurance by navigating to a web application, filling out forms, and verifying that the UI behaves correctly. These tasks otherwise require manual testing or complex custom scripts.

When running locally, the Playwright MCP server is accessible only from your own machine. This is ideal for initial development and testing as there's no risk of unauthorized access. However, if you want to expose this server remotely, for example, to integrate it into a cloud-based workflow or share it with your team, you need to make it accessible over the internet. This is where you need to start thinking about security; anyone who invokes the server's URL can invoke its tools and potentially run arbitrary browser automation on your infrastructure.

Let's go ahead and set up the Playwright MCP server locally. Start by creating a new project folder and initializing a Node.js project:

mkdir descope-playwright-mcp-auth
cd descope-playwright-mcp-auth
npm init -y

Install the Playwright MCP server, which is offered as an npm package by Microsoft:

npm install @playwright/mcp

Open the package.json file and replace the scripts section with the following content that provides a command to run the MCP server as a standalone server and adds the port flag to enable HTTP transport:

"scripts": {
  "start:mcp": "mcp-server-playwright --port 3001"
},

You can now run the Playwright MCP server by executing the following command in the terminal:

npm run start:mcp

You should get the following output:

> descope-playwright-mcp-auth@1.0.0 start:mcp
> mcp-server-playwright --port 3001

Listening on http://localhost:3001
Put this in your client config:
{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:3001/mcp"
    }
  }
}
For legacy SSE transport support, you can use the /sse endpoint instead.

To test that the Playwright MCP server is running as expected, you can use MCP Inspector. The MCP Inspector is a browser-based debugging tool that lets you interact with MCP servers without writing any client code. It's perfect for quickly verifying that your server is exposing the right tools and responding correctly before integrating it with an actual AI agent. On a separate terminal, execute the following command to start the MCP Inspector:

npx @modelcontextprotocol/inspector@0.17.2 --transport http --server-url http://localhost:3001/mcp

The --transport flag specifies how the client communicates with the MCP server. MCP supports three transport types: http (streamable HTTP), sse (server-sent events (SSE) for streaming), and stdio (standard input/output for local processes). Since the Playwright MCP server is running as an HTTP server on port 3001, you're using the http transport to connect to it.

This opens a browser tab where you can see the MCP Inspector interface. On the interface, select the Connect button to connect to your MCP server:

Once you're connected, you can perform actions such as listing the tools or invoking them:

Making the MCP server remote-capable

So far, the Playwright MCP server is listening on localhost:3001, which means it's accessible only from your own machine. No external connections can reach it because it's bound to localhost (127.0.0.1). This isolation makes it safe for local testing, but it also means teammates can't connect or share the same tools. To enable collaboration, you need to expose it over the network, but doing so requires proper authentication and authorization to prevent unauthorized access.

There are several approaches you can use to make the MCP server remotely accessible:

Binding to all interfaces (--host 0.0.0.0) exposes your server directly to your network but offers no authentication.
Using an authentication proxy offers programmatic control over authentication and authorization.

For this guide, you will use the authentication proxy approach with Express. This gives you full control over authentication logic and RBAC. It also integrates well with the Descope MCP Express SDK, which is designed to allow you to easily add MCP specification-compliant authorization to your MCP server. The authentication proxy sits between clients and the MCP server, and validates every request before forwarding it.

Start by installing the required dependencies for the authentication proxy:

npm i express cors http-proxy @descope/mcp-express dotenv
npm i -D typescript @types/node @types/express @types/cors @types/http-proxy ts-node

Create a new file named .env to store your configuration and add the following:

AUTH_PROXY_PORT=3000
MCP_SERVER_PORT=3001

This defines the ports assigned to the Playwright MCP server and the authentication proxy.

Define your TypeScript configuration by creating a new file named tsconfig.json and add the following:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

To implement the proxy logic, create a new file named src/auth-proxy.ts and add the following:

import "dotenv/config";
import express from "express";
import cors from "cors";
import httpProxy from "http-proxy";

const app = express();
app.use(cors());

const AUTH_PROXY_PORT = process.env.AUTH_PROXY_PORT || 3000;
const MCP_SERVER_PORT = process.env.MCP_SERVER_PORT || 3001;

// Create proxy instance targeting the localhost-bound MCP server
const proxy = httpProxy.createProxyServer({
  target: `http://localhost:${MCP_SERVER_PORT}`,
  changeOrigin: true,
  ws: false,
});

// Handle proxy errors
proxy.on("error", (err, req, res) => {
  console.error("Proxy error:", err);
  try {
    (res as any).writeHead?.(500, { "Content-Type": "text/plain" });
    (res as any).end?.("Proxy error");
  } catch (e) {
    // Ignore if already closed
  }
});

// Proxy all /mcp requests
app.use("/mcp", (req: any, res: any) => {
  proxy.web(req, res);
});

app.listen(AUTH_PROXY_PORT, () => {
  console.log(`Server running on port ${AUTH_PROXY_PORT}`);
});

process.on("SIGINT", () => {
  console.log("Shutting down server...");
  process.exit();
});

This code sets up a simple Express proxy server that listens on port 3000 and forwards all /mcp requests to the local Playwright MCP server running on port 3001. It uses http-proxy for request forwarding, applies cors to allow cross-origin access, and includes basic error handling.

Note: Please note that this setup supports HTTP transport only. Clients attempting to use SSE via the /sse endpoint or WebSocket connections do not function with this configuration. Supporting SSE requires additional setup to handle streaming responses, and WebSocket support requires the ws proxy option enabled. For most remote MCP deployments, HTTP transport is sufficient and easier to secure.

To make sure that the proxy is working as expected, run the MCP server using the command npm run start:mcp. In a separate terminal, run the proxy server:

npx nodemon --exec 'ts-node' src/auth-proxy.ts

Note: The --exec ts-node flag explicitly tells nodemon to use ts-node to execute the TypeScript file.

Run the MCP Inspector:

npx @modelcontextprotocol/inspector@0.17.2 --transport http --server-url http://localhost:3000/mcp

Note: Note that the --server-url flag is now pointing to the proxy server.

Once the MCP Inspector interface launches, you should be able to connect to the MCP server, list tools, and invoke them.

At this stage, your MCP server is accessible to anyone who can reach the exposed host and port. There's no authentication, no encryption (TLS), and no request validation. This means that anyone can potentially connect to your MCP server and invoke any tool.

Introducing authentication with Descope

As you saw in the previous section, anyone who discovers your proxy server's URL can connect to your MCP server and invoke any available tool. In production or shared development environments, this opens doors to unauthorized access and abuse. For a Playwright MCP server, this can mean unauthorized users running browser automation on your infrastructure, executing scripts that capture sensitive data from your environment, or triggering resource-intensive operations that consume server resources. Without authentication, you have no control over who has access to your tools and no way to audit usage or attribute usage to specific users.

Descope simplifies securing your MCP server with its visual, low-code flow editor. Instead of writing authentication logic from scratch, you can build complete authentication flows through a drag-and-drop interface. These flows define the entire authentication journey, from the user sign-in method, multifactor authentication (MFA), consent screens for third-party client access, and the process when authentication fails or succeeds. This approach lets you implement enterprise-grade security in minutes rather than days, while maintaining full control over the authentication experience.

The primary step to implementing authentication with Descope is to create a project. On your Descope console, click the project drop-down on the top navigation pane, and select + Project:

On the Create project form, provide "descope-playwright-mcp-auth" as the name of the project and select Create:

Next, navigate to the Flows page from the sidebar and click the Import flow button:

Upload the mcp-auth-consent.json file from the assets you downloaded earlier. This opens the flow in the Flow editor:

This flow has been created using the Descope flow editor by dragging and dropping authentication components, such as the user.loggedIn condition, authentication screens, verification actions, and consent conditions, onto the canvas and connecting them to define authentication logic. You can build similar flows either from scratch or from a template and use the available components. This tutorial uses a preprepared flow that includes the auth logic and consent flow to save time, but feel free to explore the editor and customize it later.

The flow starts by checking if the user is logged in. If they're not, they are redirected to a screen where they can sign in using either an emailed one-time password (OTP) or Google single sign-on (SSO). Once logged in, the flow checks if the third-party application (the MCP client) has been authorized. If not, they're redirected to a screen where the scopes being requested by the app are displayed, and the user can choose whether to authorize the app or not.

With the auth and consent flow in place, you need to set up Dynamic Client Registration (DCR). This protocol allows third-party client applications to register themselves automatically with your Descope project, instead of being manually preconfigured. When an MCP client, like the MCP connector, connects to your MCP server, it automatically initiates the DCR process by sending a registration request to the proxy's /oauth/register endpoint (provided by the Descope MCP Express SDK). The proxy handles the client registration, creates OAuth credentials for the client, and returns them so the client can proceed with authentication. All this happens behind the scenes. The MCP Inspector takes care of the DCR flow automatically once you point it to your proxy's URL, which is why you don't see explicit DCR code in the client implementation.

To set up DCR, navigate to the Inbound Apps page on your Descope console and select DCR Settings:

On the DCR Settings page, toggle the switch to enable DCR; and in the Approved scopes list section, provide the following:

Name: "openid"
Description: "Allows this app to confirm your identity and access basic profile information, such as your assigned roles."
Mandatory: Toggle to make sure this scope is mandatory

Next, scroll down to the User consent flow section, and in the Consent flow drop-down, select the flow you imported in the previous steps and save the settings:

Now that the DCR is configured, you need to obtain credentials that your proxy server uses to communicate with the Descope APIs. The proxy needs these credentials to validate tokens, manage client registrations, and enforce authentication policies.

Start by obtaining the project ID, which identifies your Descope project and tells the proxy which project's authentication rules to enforce. You can get this by navigating to the Project page:

You also need a management key to give your proxy server permission to perform administrative operations, like managing direct client registrations. Navigate to the Management Keys page, select + Management Key, and provide the key details by specifying the name and the roles:

Integrating Descope into the Playwright MCP server

At this point, you have completed setting up Descope. You enabled DCR so MCP clients can register automatically, configured the authentication and consent flow that users go through, and obtained credentials your proxy server needs to enforce authentication. The next step is to use these credentials to build the authentication proxy.

With your Descope project set up, you can now integrate authentication into the proxy. The goal is to make sure that every request is verified before it's proxied to the MCP server.

Before diving into the implementation, it's important to understand how the authentication flow works:

The MCP client, in this case, the MCP Inspector, registers with your proxy via the DCR.
You're redirected to the authentication/consent flow you set up earlier in Descope.
You log in and consent to the request scopes.
Descope issues an access token to the MCP client.
The MCP client includes this token in its requests to the proxy server.
The proxy server validates the token before forwarding the request to the MCP server.

To handle auth in the proxy, use the Descope MCP Express SDK you installed earlier. Start by adding the following to your .env file:

DESCOPE_PROJECT_ID=<YOUR-DESCOPE-PROJECT-ID>
DESCOPE_MANAGEMENT_KEY=<YOUR-DESCOPE-MANAGEMENT-KEY>
SERVER_URL=http://localhost:3000

The SERVER_URL ENV variable refers to the URL that exposes your MCP server; in this case, it's the proxy URL. Make sure to replace the placeholders for DESCOPE_PROJECT_ID and DESCOPE_MANAGEMENT_KEY with the values you obtained from your Descope console.

Next, open the src/auth-proxy.ts file and add the following imports:

import {
  descopeMcpAuthRouter,
  descopeMcpBearerAuth,
  DescopeMcpProvider,
} from "@descope/mcp-express";

Just below the MCP_SERVER_PORT definition, add the Descope MCP provider configuration:

const descopeProvider = new DescopeMcpProvider({
  projectId: process.env.DESCOPE_PROJECT_ID!,
  managementKey: process.env.DESCOPE_MANAGEMENT_KEY!,
  serverUrl: process.env.SERVER_URL!,
  dynamicClientRegistrationOptions: {
    authPageUrl: `https://api.descope.com/login/${process.env
      .DESCOPE_PROJECT_ID!}?flow=mcp-auth-consent`,
  },
});

// Add OAuth metadata and DCR endpoints
app.use(descopeMcpAuthRouter(undefined, descopeProvider));

// Protect your MCP endpoints with bearer authentication
app.use(["/mcp"], descopeMcpBearerAuth(descopeProvider));

This code initializes DescopeMcpProvider with your Descope project credentials and the proxy server URL. It also configures the DCR by specifying the URL to the auth and consent flow you set up earlier in the Descope console. The descopeMcpAuthRouter() function adds the required OAuth metadata endpoints and the DCR /register endpoint. The descopeMcpBearerAuth() function protects the specified endpoints by checking the incoming request for a bearer auth token and attaches the user information to req.auth.

Adding authorization to the Playwright MCP server

At this point, your proxy requires authentication but doesn't enforce RBAC, which restricts access to tools based on user roles. Authorization determines what authenticated users are allowed to do. For example, you may want to prevent regular users from installing browser binaries (which can consume significant resources or introduce security risks) while allowing admins full access to all tools.

For this guide, you'll use the already defined Tenant Admin role in Descope to represent a user with full access to all Playwright MCP tools. Only a user with this role can invoke the browser_install tool. In a production environment, you define custom roles and permissions that map to specific MCP tools or categories of tools. You maintain a configuration file or database that maps tool names to required roles and then check user roles against this mapping before allowing tool invocation. This tutorial uses a simple hard-coded check with a built-in Tenant Admin role to demonstrate the authorization pattern.

Start by adding the following import statement to the src/auth-proxy.ts file:

import { Readable } from "stream";

Next, add the following code before the line where you proxy /mcp requests:

app.use("/mcp", express.json(), async (req: any, res: any, next: any) => {
  // Only check authorization for POST requests with a body
  if (req.method == "POST" && req.body) {
    const mcpReq = req.body;

    // Check if the MCP method is a tools call
    if (mcpReq.method === "tools/call") {
      const toolName = mcpReq.params?.name;
      console.log(`Accessing tool: ${toolName}`);

      // If the tool is an admin tool, verify user has admin role
      if (toolName === "browser_install") {
        const authInfo = await descopeProvider.descope.validateJwt(
          req?.auth?.token!
        );
        const isAdmin = descopeProvider.descope.validateRoles(
          authInfo,
          ["Tenant Admin"]
        );

        if (!isAdmin) {
          console.log(
            `Unauthorized access attempt to admin tool: ${toolName}`
          );
          return res.status(403).json({
            jsonrpc: "2.0",
            error: {
              code: -32000,
              message: `Access denied: Tool '${toolName}' requires Tenant Admin role.`,
            },
            id: mcpReq.id || null,
          });
        }
      }
    }

    // Convert object back to string for the proxy
    req.body = JSON.stringify(mcpReq);
    req.headers["content-length"] = Buffer.byteLength(req.body).toString();
  }
  next();
});

This middleware intercepts all requests to the /mcp endpoint and uses express.json() to parse incoming JSON bodies so they can be inspected. The middleware specifically looks for tool invocation requests (identified by tools/call method) and checks the tool name against your authorization rules. For the restricted browser_install tool, it validates the user's JWT using the Descope SDK and ensures that they have the Tenant Admin role. Unauthorized requests are blocked with a 403 error, while valid requests continue through to the MCP server. The middleware reconstructs the request body and updates its headers so it can be properly proxied to the MCP server.

Finally, update the proxy handler to properly forward the reconstructed body:

app.use("/mcp", (req: any, res: any) => {
  proxy.web(req, res, {
    buffer: Readable.from([req.body ?? ""]),
  });
});

This code creates a readable stream from the reconstructed request body because the proxy library expects streaming data, not a plain string. After the middleware parses and potentially modifies the JSON body, you need to convert it back into a stream format that the proxy can forward to the upstream MCP server.

Your proxy now enforces both authentication and RBAC before forwarding requests to the MCP server.

Testing the integrations

You've set up authentication and authorization, so let's test that authenticated users can connect to your MCP server, unauthorized users are blocked, and RBAC properly restricts admin-only tools.

Start by running your local MCP server:

npm run start:mcp

In a separate terminal, run the auth proxy:

npx nodemon --exec 'ts-node' src/auth-proxy.ts

In another terminal, run the MCP Inspector:

npx @modelcontextprotocol/inspector@0.17.2 --transport http --server-url http://localhost:3000/mcp

Note: If you have another machine running on the network, you can run the MCP Inspector on it with the command npx @modelcontextprotocol/inspector@0.17.2 --transport http --server-url http://<AUTH-PROXY-MACHINE-IP>:3000/mcp, where <AUTH-PROXY-MACHINE-IP> is the IP address of the machine that is running both the MCP server and the auth proxy.

Once the MCP Inspector UI launches, select Connect to connect to your MCP server. You are then redirected to Descope to sign in:

Consent to the requested scopes:

Once you authorize the MCP client, you'll be connected to the MCP server:

At this point, if you try to invoke the browser_install tool, you will get an error that confirms RBAC is working as expected:

You now need to assign the user the Tenant Admin role to confirm that they can invoke the browser_install command if they have the appropriate roles. To do this, navigate to the Descope Users page and edit your user to assign them the Tenant Admin role:

Go back to the MCP Inspector UI, disconnect from the MCP server, and connect again. You are then prompted to sign in and consent to the requested scopes. Once you've done this, you can successfully invoke the browser_install command:

You can access the full code on GitHub.

Audit logging for compliance

For production environments, logging user activity is important for security monitoring and regulatory compliance. The current setup logs basic activity (such as tool access and authorization results) to the console. This is useful for local testing but not sufficient for production.

In a production environment, you should enhance this by doing the following:

Application-level logging: Capture detailed information about each request, including the timestamps, user IDs, roles, tools accessed, params used, and status of whether the request was granted. Send these logs to a centralized logging service, such as Amazon CloudWatch or Datadog, for long-term retention and analysis.
Descope audit logs: Descope automatically tracks all authentication events, login attempts, token generation, and role assignments. You can view these on the Audit page and export them for compliance reporting.
Compliance considerations: Different regulations (System and Organization Controls (SOC) 2 type 2, Health Insurance Portability and Accountability Act (HIPAA), General Data Protection Regulation (GDPR)) have specific requirements for log retention periods, tamper-proof storage, and access controls. Ensure your logging strategy aligns with your organization's compliance needs.

With proper audit logging, you gain full visibility into who is accessing your MCP server and what actions they're performing. As a result, you can quickly detect suspicious activity or unauthorized access attempts.

Conclusion

In this guide, you transformed a basic, local-only Playwright MCP server into a secure, remote-capable service. You learned how to upgrade from the default stdio transport to a remote-capable transport, expose it to remote connections through a proxy, protect it behind an authentication layer, and enforce fine-grained authorization using Descope.

Leaving an MCP server exposed without protection is a serious security risk. By adding authentication and authorization layers, you prevent unauthorized access while enabling collaborative, enterprise-grade workflows. This approach makes it possible for teams to connect to shared MCP servers with confidence that only approved users and roles can perform sensitive operations.

Descope provides purpose-built identity infrastructure for AI agents and MCP servers. Teams building external-facing MCP servers can add OAuth 2.1, PKCE, and secure DCR in three lines of code. Teams building AI agents can offload token management and storage for third-party tool connections. Teams building internal-facing MCP servers can implement policy-based AI agent access to corporate tools.

Whether you're building your first MCP server or scaling agentic workflows to production, Descope eliminates auth complexity so you can focus on building AI experiences. Explore Descope's AI-focused demos, check out the MCP documentation, or get started with a Free Forever account.

Add Authentication and MFA to Unreal Engine with Descope

Mrunank Pawar — Wed, 08 Apr 2026 16:55:57 +0000

This blog was originally published on Descope

Unreal Engine (UE) is widely known for its ability to create high-fidelity, immersive gaming experiences. Some of the most popular games today have been created with this more-than-capable engine, including games like Fortnite and Rocket League. Its visual scripting, robust C++ foundation, and cross-platform support make it a top choice for game development, from indie developers to AAA studios.

But building a great game isn't just about graphics or gameplay. When you start adding features like multiplayer, player profiles, cross-device syncing, and monetization, secure, seamless authentication becomes nonnegotiable. Making sure that only verified users can access key features or data is essential for both user safety and developer control. Descope is a flexible identity platform that allows developers to embed authentication and multifactor authentication (MFA) flows into their apps with minimal friction. With support for magic links, OTPs, and social logins, Descope makes it easier to build secure login flows that will feel like a natural part of your game.

In this tutorial, you'll learn how to add authentication and MFA to a UE game using Descope. Along the way, we'll cover the different approaches game developers typically consider when implementing authentication, walk through a real-world integration using Descope's OpenID Connect (OIDC) support, and demonstrate how to display user details and handle logouts in game.

Approaches to game authentication

Game developers generally have three options when it comes to implementing authentication. The first is to rely on a storefront's built-in identity system, such as Epic Games or Steam. These systems offer smooth onboarding within their ecosystems and can integrate well with features like matchmaking, achievements, and leaderboards. However, they also come with some trade-offs: limited customization, dependency on a single platform, and constraints around marketing access or monetization outside the store.

The second option is to purchase an authentication plugin from Fab, Epic Games' new unified marketplace for digital assets. While this can help to kickstart development, the quality and reliability of these plugins can vary. Many still require manual setup and ongoing maintenance or lack support for features like MFA. For teams working on production-grade titles, these limitations often become apparent late in development, right when integration changes are most costly.

Finally, you could opt to build your own authentication system from the ground up. This offers the most control but comes at a high cost in terms of engineering time, ongoing security maintenance, and compliance.

However, a custom authentication system does bring some advantages that the other options might not be able to offer:

Maintain consistent player identity across storefronts and devices
Implement subscriptions or microtransactions outside of the game platform
Get better user analytics and tracking
Reduce reliance on third-party platforms
Strengthen overall security with flexible MFA options

Descope helps you to bridge this gap by offering a secure, developer-first approach to authentication and MFA. This approach works across platforms, can be integrated into your game's UX, and doesn't require you to become an authentication expert.

In the following sections, you'll learn how to implement a secure, user-friendly authentication flow in Unreal Engine using Descope: from setting up your Descope project to integrating it with your UE game, configuring authentication flows, and adding multifactor authentication. By the end, you'll have a working login system with MFA, profile fetching, and logout functionality ready to plug into your own game.

Prerequisites

Before you get started, you're going to need a few tools and services downloaded, installed, and ready to go:

Unreal Engine v5.6+ (installed via the Epic Games Store launcher). Instructions for installing the full UE can be found here. The tutorial might work on an older version, but your mileage may vary.
Visual Studio or Visual Studio Community Edition, depending on your licensing needs.
A Descope account.

Visual Studio: specific modifications for Unreal Engine

Visual Studio's installer allows you to set up the IDE for different workloads or project types. If you've previously only used VS for Python projects, you'll have it set up in a particular way that won't work with UE, which requires a few specific components for it to fully work.

Launch the VS installer and click Modify to modify your installation of Visual Studio:

Under the Workloads tab, in the Desktop & Mobile section, you need to make sure that these three components are selected:

.NET desktop development
Desktop development with C++
WinUI application development

Still under Workloads, in the Gaming section, make sure that Game development with C++ is selected:

Once you've downloaded and installed all of the components, your Visual Studio environment is ready to go.

Note: If, for whatever reason, things don't seem to be working, or the installed version of UE is starting up with errors, consult the help pages on Epic Games' website to troubleshoot these errors.

Setting up Descope

Once you've set up your Descope account, you can start designing your authentication workflow.

First, log in to your Descope console via this link.

Navigate to Flows and then select Start from template.

The flow template library allows you to filter by use cases and methods. Select Enchanted Link and Social (OAuth/OIDC) for your methods, and MFA for your use case. Select the Sign up or in version of the templates that matched your selected filters.

You can rename your flow and give it a unique ID if you want. Once you're happy, click Create.

Once your new flow has been created, you can customize the flow to behave the way you want it. In this tutorial, we'll remove the social login buttons for Google and Apple, and add a Discord button instead.

Hover over the Welcome Screen element on the flow and select Edit.

Delete the Google and Apple social buttons, and drag in a Discord button from the sidebar.

Remember to save your flow once you're happy with the changes you've made.

Your custom authentication flow has now been set up and is ready to be used in your Unreal Engine project.

Creating your Unreal Engine game

With the prerequisites in place, the first step is to set up the new Unreal Engine project that you will add authentication to. Start off by opening Unreal Engine either from the Epic Games Launcher or from the installed location.

Then, create a blank game project and give it a name. This tutorial will use UNREAL_AUTH_DEMO as the project name. Make sure to select C++ as your project type.

If everything went well, you'll see an empty game world showing up in the editor:

If it didn't go well and your editor refused to start, now would be the time to consult the Setting Up Visual Studio page to see if you're missing any components that need to be installed first.

Otherwise, you're ready to create your menu component that will allow your users to sign up or in.

Create your main menu

In the UE editor, at the bottom, expand your Content Drawer. Create a UI folder under Content to keep things organized.

Add a User Interface widget blueprint:

Click User Widget as the parent class when prompted:

Name your widget something practical like LoginMenu:

Once you're in the designer, you're going to need the following on your menu blueprint:

Two buttons, one named SigninButton and another named SignoutButton.
Both buttons need to have the Is Variable option enabled.
A textbox named TextResult, also with Is Variable enabled.

Once your menu has been created, you should have a hierarchy that looks similar to this:

And while your menu might look slightly different, it should look similar to this:

This menu is now ready to be displayed in your UE level.

Display your menu

Now that you have a login menu, you'll want it to appear when your game starts.

In the UE editor:

Create a new empty level (for example, you can name it MainMenuLevel).
Open the level blueprint.
On Begin Play, add a Create Widget node, select your LoginMenu widget, then connect it to an Add to Viewport node.

Save your level blueprint, exit the blueprint editor, and click Play from the level editor to see your new menu inside the level:

Create your custom login widget class

Next, you'll add some simple C++ logic to connect to the menu.

Create a new C++ class (UserWidget parent) and name it LoginUIWidget.

Wire up basic button click events to confirm your UI is responding.

Update LoginUIWidget.h to declare the buttons, text block, and click handlers:

#pragma once

#include "CoreMinimal.h"
#include "Blueprint/UserWidget.h"
#include "LoginUIWidget.generated.h"

UCLASS()
class UNREAL_AUTH_DEMO_API ULoginUIWidget : public UUserWidget
{
    GENERATED_BODY()

public:
    virtual void NativeConstruct() override;

    UFUNCTION()
    void OnSigninClicked();

    UFUNCTION()
    void OnSignoutClicked();

protected:
    UPROPERTY(meta = (BindWidget))
    class UButton* SigninButton;

    UPROPERTY(meta = (BindWidget))
    class UButton* SignoutButton;

    UPROPERTY(meta = (BindWidget))
    class UTextBlock* TextResult;
};

Note the following:

Replace UNREAL_AUTH_DEMO_API with your actual project name and API.
Ensure the UButton and UTextBlock names match your blueprint widget variables.

Then update LoginUIWidget.cpp to register the button click handlers:

#include "LoginUIWidget.h"
#include "Components/Button.h"
#include "Components/TextBlock.h"

void ULoginUIWidget::NativeConstruct()
{
    Super::NativeConstruct();

    if (SigninButton) SigninButton->OnClicked.AddDynamic(this, &ULoginUIWidget::OnSigninClicked);
    if (SignoutButton) SignoutButton->OnClicked.AddDynamic(this, &ULoginUIWidget::OnSignoutClicked);
}

void ULoginUIWidget::OnSigninClicked()
{
    UE_LOG(LogTemp, Log, TEXT("Sign in button pressed!"));
    // login logic here
}

void ULoginUIWidget::OnSignoutClicked()
{
    UE_LOG(LogTemp, Log, TEXT("Sign out button pressed!"));
    // logout logic here
}

This test code does two things:

Hooks up the Sign In and Sign Out buttons
Logs a message to the UE output log when either button is pressed

Save these two files. Now, you'll need to reparent your existing login menu blueprint to use this new class's logic.

Reparent your login menu blueprint

Open up the LoginMenu blueprint from the content drawer. Then, select File > Reparent Blueprint. You'll be able to search for LoginUIWidget (the new class you just created) and then select it. This will reparent your blueprint's logic to the custom from earlier.

Note: At this point, you might run into an annoying bug that some people have with UE5 and VS 2022. If you do not see the class listed when you search for it, you'll need to do the following steps:

Close the Unreal Engine editor.

In Visual Studio, select Build > Build unreal_auth_demo or the project name you chose.

Wait for the build process to finish, and open the Unreal editor again.

Sometimes, you can use the build process without having to close the editor, and there are ways to fix it, but that's beyond the scope of this tutorial. In any case, if you've followed the steps, you should be able to reparent the blueprint to your custom class.

Save your blueprint once you've finished the reparent process.

Change your default level and test the button

Back in the editor, go to Edit > Project Settings, and then click Maps & Modes on the left sidebar menu. Change your Editor Startup Map and your Game Default Map to point to the MainMenuLevel you created.

Now, you can test your custom button code logic. Play the game using the same green play button from before, and click the Sign in button.

In your editor, you'll see a drawer called Output Log. Expand this drawer, scroll to the bottom, and see if your custom output message is there.

If you see the messages, that means your code is working.

Get some information from Descope

Before you can connect Unreal Engine to Descope, you need to gather some details about how the game will communicate with Descope during the login process. These details come from OAuth 2.0 and OpenID Connect (OIDC), which are the standards we'll use to handle authentication with Descope.

OAuth and OIDC

OAuth 2.0 is a protocol that lets an app (in this case, your game) request authorization for a user through a trusted provider like Descope. Instead of handling passwords directly, your game gets a temporary authorization code that can be exchanged for tokens.

OpenID Connect (OIDC) builds on OAuth 2.0 and adds identity information. That's how your game can get details like the player's username, email, or profile data.

In practice, this means your Unreal Engine project will:

Redirect the player to Descope's login page.
Descope will authenticate the user (e.g., via Discord login + MFA).
Descope will send your game back an authorization code.
Your game exchanges that code for tokens that prove the user is authenticated.

To make this work, your game needs some values from Descope's OIDC configuration.

Getting the OIDC Settings

In your Descope console:

Navigate to Federated Apps.
Click OIDC Default Application. (On the free tier, this is the only one available for editing.)
Scroll down to the SP Configuration section and note the following values:
- Client ID: identifies your Unreal Engine app to Descope.
- Authorization URL: the endpoint your game uses to start the login flow.
- Token URL: the endpoint your game calls to exchange the authorization code for tokens.
- Logout URL: the endpoint that clears the user's session when they sign out.

These values form the backbone of the login flow. In the next step, you'll wire them into the Unreal Engine code so the game can start and complete the OAuth process.

While you're on this screen, update the Flow Hosting URL to point to the custom flow you created earlier:

Modify your custom class

Next, let's update LoginUIWidget.h to declare the functions, variables, and UI bindings that power the authentication flow:

#pragma once

#include "CoreMinimal.h"
#include "Blueprint/UserWidget.h"
#include "LoginUIWidget.generated.h"

/**
 *
 */
UCLASS()
class UNREAL_AUTH_DEMO_API ULoginUIWidget : public UUserWidget
{
    GENERATED_BODY()

public:
    virtual void NativeConstruct() override;

    UFUNCTION()
    void OnSigninClicked();

    UFUNCTION()
    void OnSignoutClicked();

    UFUNCTION()
    void SetLoginState(bool bNewLoginState);

    UFUNCTION()
    void UpdateUI();

protected:
    UPROPERTY(meta = (BindWidget))
    class UButton* SigninButton;

    UPROPERTY(meta = (BindWidget))
    class UButton* SignoutButton;

    UPROPERTY(meta = (BindWidget))
    class UTextBlock* TextResult;

    // Login state
    UPROPERTY(BlueprintReadOnly, Category = "Login")
    bool bIsLoggedIn = false;

    // Descope OIDC Parameters
    FString ClientId;
    FString RedirectUri;
    FString RedirectLogoutUri;

    // Descope endpoint URLs
    FString AuthUrl;
    FString TokenUrl;
    FString LogoutUrl;
    FString UserInfoUrl;

    FString CapturedAuthCode;

    // PKCE values
    FString CodeVerifier;
    FString CodeChallenge;
    FString State;

    // Tokens
    FString IdToken;
    FString AccessToken;
    FString RefreshToken;

    void GeneratePKCEParameters();
    void StartOAuthLogin();
    void ListenForAuthCodeInBackground();
    void PerformSignout();
    void RevokeTokens();
    void ClearSessionData();

    // Fetching user data variables and functions
    FString UserEmail;
    FString UserName;

    UFUNCTION()
    void FetchUserProfile(const FString& Token);

    UFUNCTION()
    void ExchangeAuthCodeForTokens(const FString& Code);
};

At a high level, this header sets up:

UI hooks: SigninButton, SignoutButton, TextResult
Authentication state: bIsLoggedIn, tokens, and PKCE parameters
Core functions: StartOAuthLogin, ExchangeAuthCodeForTokens, FetchUserProfile, and PerformSignout
Networking: a socket listener (ListenForAuthCodeInBackground) to receive the redirect from Descope

With the header file in place, you can now implement the functionality in LoginUIWidget.cpp. This is where the actual behavior for our authentication flow lives—handling button clicks, generating PKCE parameters, launching the OAuth login, listening for the redirect from Descope, exchanging the authorization code for tokens, and finally fetching the user's profile information to display in the game.

The next code snippet is large, so it's recommended to copy the code directly from the Github repo, here. Just remember to update the following variables with the values you retrieved from Descope earlier:

ClientId
RedirectUri
RedirectLogoutUri
AuthUrl
TokenUrl
LogoutUrl
UserInfoUrl

Here are the most important parts of the .cpp:

PKCE support (GeneratePKCEParameters) for secure OAuth logins
Browser-based login (StartOAuthLogin) using the system browser
Local redirect listener (ListenForAuthCodeInBackground) to capture the authorization code and exchange it for tokens
Profile fetching (FetchUserProfile) to display the user's email and username
Thread safety and timeouts—runs the socket in a background thread, logs any errors to the UE output log

Finally, because this project uses new features like network sockets and HTTP calls, you'll need to enable the corresponding Unreal Engine modules in your project's build configuration. Open your project's build file (ProjectName.Build.cs) and add the required dependencies, as shown below:

using UnrealBuildTool;

public class unreal_auth_demo : ModuleRules
{
    public unreal_auth_demo(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

        // PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput" });
        PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "Networking", "HTTP", "Json", "JsonUtilities", "Sockets" });

        PrivateDependencyModuleNames.AddRange(new string[] { });

        // Uncomment if you are using Slate UI
        // PrivateDependencyModuleNames.AddRange(new string[] { "Slate", "SlateCore" });

        // Uncomment if you are using online features
        // PrivateDependencyModuleNames.Add("OnlineSubsystem");

        // To include OnlineSubsystemSteam, add it to the plugins section in your uproject file with the Enabled attribute set to true
    }
}

Build your code again using Build -> Build unreal_auth_demo. Once it's finished building, you can open up the Unreal editor again.

Testing it all

Once your editor is open, run the game using the green play button again.

Notice that your Sign Out button is not visible. This is because of the changes in the UpdateUI() method to show and hide the different buttons based on your logged-in state.

Click Sign In. A browser window will open with the following login UI:

This is the right authentication flow that you set up earlier on Descope's flow designer. Click Sign in with Discord.

The first time you sign in, Descope will ask for some extra information about you and verify your identity using MFA.

If you entered your number correctly, you should receive a verification code via SMS:

Once you've entered the code, your screen should look like this:

This process should only happen the first time you sign in with a new user. Click Submit to continue.

Discord will open up with the following dialog:

Click Authorize and you should see the following:

Descope will now call the configured callback URL (in your case, http://localhost:3000) to tell your server that the login was successful and to give you an authorization code:

In the background, your code will use the ExchangeAuthCodeForTokens and FetchUserProfile methods to fetch proper authentication tokens and to retrieve user information. Once that's complete, it will update the UI in your game:

Notice now that the Sign In button has been replaced with a Sign Out button.

Try giving that button a click:

You've now successfully integrated Descope as your auth provider for your Unreal Engine 5 game.

As mentioned before, all of the code used in this tutorial is available here.

Conclusion

Adding authentication and MFA to an Unreal Engine game doesn't necessarily mean writing your own identity system or locking yourself into a single storefront. With Descope, you can implement secure, flexible login flows, including social login and multifactor authentication, using modern standards like OIDC and PKCE.

In this tutorial, you built a working login system in Unreal Engine from the ground up. You integrated Descope with Discord for social login, captured the authorization code using a local socket, exchanged it for tokens, and fetched the authenticated user's profile to update your game's UI. You now have a foundation for cross-platform identity, security, and personalization inside your UE game.

Descope offers even more beyond what was covered here: drag-and-drop flow builders, passwordless authentication, risk-based access policies, and more. If you're building a connected game and want your auth system to scale with you, book a demo with Descope, or check out their documentation and explore how it can fit the identity strategy for your game or website.

The Developer’s Guide to JWT Storage

Mrunank Pawar — Mon, 06 Apr 2026 17:07:00 +0000

This blog was originally published on Descope

JSON Web Tokens (JWTs) are compact, self-contained tokens used to securely transmit information between parties while maintaining data integrity. Many authorization providers use JWTs to provide a tamper-proof way of identifying an authenticated user in an application and checking what they're authorized to do.

Unfortunately, securely storing JWTs is often overlooked, which can expose some serious vulnerabilities. For example, cross-site scripting (XSS) attacks can steal JWTs, letting malicious actors impersonate users and access sensitive data. Therefore, you need to store JWTs securely to protect users and potentially save your organization millions by preventing data breaches.

This guide will explore essential JWT security considerations, popular browser storage methods, and their benefits and drawbacks, best practices, and troubleshooting tips for working with JWTs. By the end, you'll be well-informed about the available JWT storage methods and choose the most appropriate solution for your use case.

Understanding JWT storage

JWTs are compact, self-contained tokens used to transmit user information in requests to a server. Given HTTP's stateless nature, once an application receives the token, it must be stored and used for subsequent API requests to the server.

The JWT lifecycle consists of three stages: creation, storage, and usage. First, an authorization server generates the JWT after the user is successfully authenticated. Second, the application stores the token, typically in the browser. Third, the application includes the token in the authorization header when making requests to the resource server, which verifies the token before processing the request.

Here's a diagram of the process:

Security is critical when storing JWT storage. Storing it improperly can lead to token theft, making it possible for attackers to impersonate users or elevate their privileges. Common attack vectors include the following:

Arbitrary signature attacks: Arbitrary signature attacks occur when servers fail to verify token signatures, allowing attackers to modify claims and escalate privileges or impersonate users. While this is primarily a server-side issue, secure JWT storage makes it harder for attackers to obtain a valid token to study and manipulate.
none algorithm attacks: The none algorithm attack happens when servers mistakenly accept unsigned JWTs due to the alg parameter being set to none. JWT storage is not entirely related to this attack. However, it's harder for attackers to put together a malicious token if they can't gain access to the valid one.
Algorithm confusion attacks: In algorithm confusion attacks, attackers exploit mismatches between the signing and verification algorithms, generating valid tokens with their own keys. If tokens are stored insecurely, attackers can more easily obtain them to study the algorithm used and attempt to craft tokens with manipulated algorithms and secrets.
Kid manipulation: Key ID (kid) manipulation exploits vulnerabilities in the kid parameter by injecting malicious commands into the token's key verification process. As with other attack vectors, kid manipulation is more straightforward if attackers obtain a valid JWT. However, the vulnerability needs to be fixed on the server side.
Brute force attacks: Brute force attacks target weak or simple symmetric encryption secrets, allowing attackers to generate malicious tokens by guessing the secret. Secure JWT storage is crucial in preventing brute-force attacks. If tokens are stored insecurely, attackers can easily obtain valid tokens to use as a reference when attempting to guess the secret.

To mitigate these risks, it's crucial that you implement proper server-side token verification, disable insecure algorithms, use strong encryption, and validate all parameters in the token. When storing tokens in a client-side application, you must do so securely to prevent unauthorized access to valid tokens, which attackers could study and manipulate.

Common JWT storage methods

Several options are available for storing tokens client-side in the browser. Each has its strengths and weaknesses, and you must assess your application requirements and decide which technique is best suited.

For example, session or in-memory storage might be ideal if user sessions are generally short and get logged out when they're done. However, you might consider cookies or local storage for longer-lived user sessions.

Local storage

Local storage provides a simple API for storing user data across sessions in the browser. Its simplicity and robustness across sessions make it a popular choice for storing JWTs in the browser. However, it's important to note that local storage is vulnerable to XSS attacks, where attackers can inject malicious scripts to access stored data, including JWTs. Make sure to implement appropriate safety measures to prevent this.

Run the following code to store a JWT in local storage after receiving it:

// Store JWT
localStorage.setItem('jwtToken', response.data.token);

// Use JWT in request
const token = localStorage.getItem('jwtToken');
const response = await fetch('https://example.com/api/data', {
    headers: {
        'Authorization': `Bearer ${token}`
    }
});

// Clear JWT (log out)
localStorage.removeItem('jwtToken');

Local storage has some pros and cons that you should carefully consider:

Pros:

Easy to implement
Accessible from JavaScript code
Accessible across browser tabs
Persistent between page refreshes
Generous storage limit (5MB)

Cons:

Vulnerable to XSS attacks
No automatic token expiration mechanism

Local storage is a popular choice for storing JWTs as it lets you persist tokens across pages and is easy to access from JavaScript. However, make sure you patch XSS vulnerabilities to prevent malicious actors from stealing tokens.

Cookies

Cookies offer additional security compared to other client-side storage options. They require server-side modifications to create secure cookies containing the token. When properly configured, cookies are less vulnerable to XSS attacks, but they can still be susceptible to cross-site request forgery (CSRF) attacks.

Use the HttpOnly flag to ensure client-side JavaScript cannot access the cookies. The Secure flag ensures the cookie is sent only over a secure channel that's not susceptible to man-in-the-middle attacks. Finally, the SameSite attribute can be used with other anti-CSRF strategies to help prevent CSRF attacks.

Here's a basic example of storing a JWT in a cookie using Express:

app.post('/login', (req, res) => {
    const token = generateJWT(user);

    // Insert the token into the `auth_jwt` cookie in the response
    res.cookie('auth_jwt', token, {
        httpOnly: true,
        secure: true,
        maxAge: 60 * 60 * 1000 // 1 hour
    });
});

Run the following code to make a request with the cookie in client-side JavaScript code:

const response = await fetch('/protected', {
    method: 'GET',
    // Set credentials to same-origin so cookies are included
    credentials: 'same-origin'
});

The following is to verify the token on the server using Express:

app.get('/protected', (req, res) => {
    const jwt = req.cookies.auth_jwt;
    if (!verifyToken(jwt)) {
        return res.status(401).json({ message: 'Token is invalid' });
    }

    // Continue processing the request here since the JWT is valid
});

Logging the user out involves simply clearing the cookie:

app.get('/logout', (req, res) => {
    res.clearCookie('auth_jwt');
    return res.status(200).json({ message: 'User logged out.' });
});

Consider the following pros and cons regarding cookie storage before using it for your JWTs:

Pros:

Enhanced security against XSS attacks (with HttpOnly flag)
Automatically included in requests
Built-in security features (Secure flag and SameSite attribute)
Server-side control over token storage lets the server revoke tokens if necessary before processing requests. This could happen if a user logs out of another system and a back-channel logout request is sent to the server.
Accessible across browser tabs
Persistent between page refreshes

Cons:

Vulnerable to CSRF attacks (mitigate with the SameSite attribute and anti-CSRF mechanisms)
Limited storage capacity (around 4KB)
Often requires additional server-side logic
Possibly tricky to work with when working across domains

Cookie storage is a great solution as it provides a good balance of security and functionality. However, remember to implement proper security measures, like using the HttpOnly, Secure, and SameSite flags, along with anti-CSRF mechanisms.

Session storage

Session storage is a JavaScript API in the browser that lets you persist data for a single page until it's closed. This means that the data stored is lost as soon as the page is closed. Also, if a user opens another page in a different tab or window, it will have its own session storage.

Session storage is slightly more secure than local storage, as session storage gets cleared when the page closes. However, session storage is still vulnerable to XSS attacks. Use the OWASP cheat sheet and a Content Security Policy to prevent these attacks. However, be aware that malicious browser extensions can still access session storage.

Here's how to use session storage for JWTs:

// Store JWT
sessionStorage.setItem('jwtToken', token);

// Retrieve JWT
const token = sessionStorage.getItem('jwtToken');

// Use JWT in request
const response = await fetch('https://example.com/api/data', {
  headers: { 'Authorization': `Bearer ${token}` }
});

// Remove JWT (logout)
sessionStorage.removeItem('jwtToken');

Before using session storage, consider the following pros and cons:

Pros:

Easy to implement
Accessible to client-side scripts
Automatic clearing of tokens when the page is closed
Generous storage limit (5MB)

Cons:

Vulnerable to XSS attacks
Lost token between page refreshes and tabs

Session storage offers a simple way to store JWTs and automatically clears them when the page is closed. Tokens are also accessible from client-side scripts. However, be sure to protect your app against XSS attacks to prevent stolen tokens.

In-memory storage

In-memory storage keeps the JWT in the web application's memory using a JavaScript variable or a web worker, rather than persisting it in browser storage. This approach is helpful in single-page applications (SPAs) where the page doesn't refresh often.

In-memory storage can be considered slightly more secure since the token is obscured from the attacker. Attackers can't use a standard browser API to retrieve it. However, with enough patience, an attacker could still figure out where the token is being stored and retrieve it through an XSS attack. Malicious actors can also try to access the in-memory JWT using a debugger. Similar to other storage techniques, having a well-defined Content Security Policy and implementing XSS preventive measures are vital.

The following snippet demonstrates how to store a JWT in memory using a JavaScript class with a private variable storing the JWT:

class TokenService {
    #token = null;

    setToken(newToken) {
        this.#token = newToken;
    }

    getToken() {
        return this.#token;
    }

    clearToken() {
        this.#token = null;
    }
}

const tokenService = new TokenService();

// Store JWT
tokenService.setToken(response.data.token);

// Use JWT in request
const response = await fetch('https://example.com/api/data', {
    headers: {
        // token is the global variable
        'Authorization': `Bearer ${tokenService.getToken()}`
    }
})

// Clear JWT (logout)
tokenService.clearToken();

In-memory might seem slightly more secure than some other methods, but it still has some cons, which might influence your decision to go with this approach:

Pros:

Harder to retrieve via XSS attacks
Accessible to client-side scripts
Automatic token clearing when navigating pages and tabs
No storage limitations

Cons:

Still vulnerable to sophisticated XSS attacks
Lost token between page refreshes and tabs

In-memory offers a balance between security and convenience. It's slightly harder to retrieve using XSS attacks, but you should still take preventive measures to prevent these attacks in the first place.

Best practices for JWT storage

Regardless of which storage method you use, there are some best practices you should follow to minimize authentication and authorization vulnerabilities in your application.

Encryption of stored tokens

Storing tokens unencrypted makes it possible for an attacker to decode the token and see what claims are associated with it. JSON Web Encryption (JWE) is a standardized method of encrypting JWTs. The encryption happens on the server before the token is sent to the client, and the encryption keys are kept on the server or in a dedicated key management service.

Since the client cannot access the encryption key, they cannot view any of the claims in the token.

Token expiration and rotation

JWT expiration times dictate when a token is no longer valid. Once a token expires, you must retrieve a new one using a refresh token. A refresh token is a token issued along with the original JWT that lets you request a new JWT when the current one expires. When issuing a new JWT using a refresh token, the authorization server first ensures the user's session is still active and then sends the new token if it is.

You can further enhance the security of your JWT and refresh token by rotating the refresh tokens. This means that every time you request a new JWT using a refresh token, a new refresh token is generated along with the new token and returned. The refresh token returned is the only valid token that can be used to get the next JWT. For a deeper look at this, check out The Developer's Guide to Refresh Token Rotation.

You should also set an expiration period for your refresh tokens, as this adds an extra layer of security. Even if the attackers can access the refresh token, they might not use it in time.

Handling of token revocation

If a server uses only the JWT expiry time claim to determine whether a token has expired, then a token can still be valid after a user is logged out or blocked from an application. While shortening the JWT expiry time can help minimize the risk, there's still a window of time where a token is valid after the user's session has ended.

By implementing a blocklist, the server can use the token's expiry time and the blocklist to determine if the token is valid. When a user logs out or their account is banned, the authorization server sends a back-channel logout request to other servers, indicating that this user's session has ended. Each server can use this event to update its blocklist with the user's details. Then, when another request is sent using that user's JWT, it can get picked up as invalid even if it hasn't expired yet.

While most applications are okay with a JWT lasting a little longer than a user session, some might require stricter security. Implementing token revocation lets you derive the benefits of JWT while offering an efficient way of immediately blocking tokens.

Protection against XSS and CSRF attacks

Every storage method discussed in this article can be prone to XSS and CSRF attacks.

To prevent XSS attacks, use cookie authentication so JavaScript can't access the JWT. However, if your frontend JavaScript needs access to the JWT, you can implement a Content Security Policy to restrict which scripts can run on the page.

If you use cookie authentication, ensure your cookies are set up correctly. They should be HttpOnly and marked as Secure. Additionally, configure SameSite to restrict when the cookie gets sent in requests from third-party URLs. Other anti-CSRF mechanisms, like anti-forgery tokens, can also help secure against CSRF attacks.

There's no perfect solution when it comes to XSS and CSRF attacks. Assess your requirements, decide which storage mechanism you will use, and then cater to the vulnerabilities that come with that method.

Troubleshooting common issues

JWTs can be challenging to troubleshoot when things go wrong. The following are some useful tips for troubleshooting JWT issues.

Debugging JWT storage issues

If you're struggling to figure out if the JWT is being stored successfully or not, use the Application tab in your browser's developer tools to analyze the local storage, session storage, and cookies associated with the current page:

If the token appears in your chosen storage mechanism, verify that the token is in the correct format. It should consist of three parts separated by dots.

You can also monitor the lifecycle of the token logging messages. This can help identify where the token is not being processed or stored correctly in your code.

Handling token expiration elegantly

Tokens expire, so make sure you implement refresh tokens and use them to retrieve new tokens when the old ones expire.

When using refresh tokens, it's better to proactively refresh a token before it expires by monitoring its expiry time and triggering a refresh a few seconds before the expiry time. Otherwise, you might send a token that's still valid for a split second when the request is sent, but it expires when the server receives it.

If a refresh request fails, retry it as a network issue could be the cause. If it fails again, redirect the user to the authentication screen with a message notifying them that they must log in to continue using the application. This makes your application more robust when it encounters authentication errors.

Dealing with cross-domain storage hurdles

Cookies are typically associated with a specific domain, and the browser sends the cookie only when a request is made to that particular domain. However, what if your application needs to make requests to multiple domains using the same token? For example, an application's frontend might be on a different domain than the API.

If so, you should consider a backend-for-frontend (BFF) for your application. A BFF consolidates all those API calls to different services into a single service. This way, your cookie needs to be configured only for your BFF's domain. The BFF can then proxy the request to the appropriate service with the JWT.

JWT storage on mobile

Until now, you've seen how JWTs can be stored in a browser context. But what about mobile apps? Many apps need to access restricted APIs that require authentication.

JWT storage solutions like HttpOnly cookies work well in a web application but are more complex in mobile apps, given the absence of browser-specific mechanisms like cookie management. Your app would need to manually store the cookie and attach it to every request to the API. When storing the cookie, you also need to make sure it's secure and not accessible by other apps or the end-user.

Fortunately, mobile platforms offer secure storage to store sensitive secrets like JWTs. On Android, you can use Keystore to encrypt JWTs, which you can then store using SharedPreferences. Similarly, iOS lets you use Keychain to encrypt and store secrets on the user's device. Using these services is similar to how you'd store JWTs in local storage on the web: after the user logs in, retrieve the JWT and store it.

When storing JWTs in a mobile app, remember that these devices are more prone to theft, so create short-lived JWTs that get rotated often using refresh tokens. You could even store a session identifier instead of the JWT in the mobile app. With a session identifier, the app makes a request to the server, which does a database lookup to retrieve the associated JWT and validate it.

While slightly more complex to set up, this approach makes it even harder for a malicious user to access the underlying JWT since it's stored and accessed on the server. This solution also gives you more control over mobile app sessions since you can terminate a session with immediate effect, unlike JWTs, which only end a session when they expire (or are added to a blacklist, as discussed above).

Conclusion

In this guide, you've discovered how local storage, session storage, cookies, and in-memory storage can be used for storing JWTs securely in web applications. The guide discussed the security implications of each approach and some pros and cons. You were then introduced to some best practices that should be followed regardless of your storage method. These include encrypting the JWTs, expiring tokens and rotating their refresh keys, handling token revocation, and protecting against XSS and CSRF attacks. Finally, the guide also provided insights into securely storing JWTs in mobile applications.

JWTs are one of the most popular forms of authentication in modern systems. As new use cases emerge, JWTs are tweaked to work in those scenarios. For example, JWTs were initially designed to be stateless, meaning servers could verify a token without looking it up in an external system. However, some use cases require immediate token revocation, which brought about stateful JWT authentication, where the server also stores information about the token to verify it's still valid.

The stateless nature of JWTs has also made them a popular choice when building scalable applications since each server can verify the token by decoding the token passed in requests. JWTs and their use cases are evolving constantly, and it's crucial that you continuously reassess your application's authentication configuration, including how you store JWTs in applications, to ensure no new security vulnerabilities or loopholes appear.

Adding Authentication and SSO to a Streamlit App

Mrunank Pawar — Fri, 03 Apr 2026 17:07:00 +0000

This blog was originally published on Descope

Streamlit makes it simple to turn Python scripts into shareable data apps. As these apps move from personal notebooks to team and company use, adding secure authentication and single sign-on (SSO) becomes essential. Authentication protects sensitive data and gates features by user identity. SSO lets people sign in once and move across apps without repeating logins.

In this tutorial, you'll use Descope, a drag & drop CIAM platform to add:

Single sign-on
Social login
Role-based access control (RBAC) to a Streamlit app.

Prerequisites

Before diving into the integration process, ensure you understand the basics of Python and Streamlit. You also need a Descope account, but don't worry if you don't have one yet—you'll learn how to set one up shortly. The free tier will be sufficient for you to follow along.

Creating a project in Descope

The first step is to connect your Streamlit app with Descope by creating a project in the Descope console.

Go to the Descope sign-up page and register for a free account (or log in if you already have one).
From the top-left menu in the console, select + Project to create a new project.

Your project dashboard is the hub where you'll:

Create and manage projects
Assign user roles
Configure authentication flows
Adjust project-level settings

In Settings > Project, you'll see your Project ID. This is a unique identifier that links your Streamlit app to Descope.

Best practice: Never paste this ID directly into your code. Instead, store it securely as an environment variable or in .streamlit/secrets.toml. Later in this tutorial, we'll show you how to use it safely inside your app.

Creating a Streamlit app

With your Descope project set up, let's move to the Streamlit side. We'll start with a bare-bones app and then integrate authentication step by step.

Create a new directory for your app. Optionally, set up a Python virtual environment inside it.
Install Streamlit with the following command:

pip install streamlit

In the new directory, create a file called app.py and paste the following code:

import streamlit as st

st.title("Demo App")
st.write("This is a demo app with Descope-powered authentication and SSO")

You need a project ID to initialize Descope, so copy yours from the console settings, create a .streamlit/secrets.toml file in the root directory of your app, and include the project ID, like this:

Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zm47gp82oqbzwm28qihp.png)

Implementing OAuth social logins in Steamlit

Before diving into enterprise SSO, let's start with something many users expect out of the box: social logins. OAuth providers like Google or GitHub let people sign in with accounts they already trust. This removes friction during signup and reduces the need to manage yet another password.

By adding OAuth, your Streamlit app instantly feels more professional and user-friendly—and when paired with SSO later, you'll cover both casual and enterprise login scenarios.

Configuring Descope as a federated identity provider for Streamlit

In this section, we walk you through setting up Descope as a federated identity provider (IdP) for Streamlit and seamlessly integrating Google login with the application you created earlier.

In the Descope console, go to: Build > Authentication Methods > Social Login (OAuth/OIDC)

Here you'll see a full list of supported providers. Select Google for this example:

Note: The Descope console provides an authentication account for all common social logins. There's also an option to specify a different account for authentication if you prefer.

Next, configure the redirect URL. This is the location users will return to after completing authentication. Since we're working locally, set it to your app's address, http://localhost:8501, in the configuration provided, like this:

Remember, you can also provide the redirect URL programmatically in your Streamlit code for added flexibility later.

Integrating Descope with your Streamlit app as its OAuth provider

Now let's wire your app to Descope so it can trigger the OAuth login flow and handle the response.

Install its Python SDK to facilitate the interaction:

pip install descope

You need a project ID to initialize Descope, so copy yours from the console settings, create a .streamlit/secrets.toml file in the root directory of your app, and include the project ID, like this:

DESCOPE_PROJECT_ID = "XXXXX"

Initialize Descope in your app:

import streamlit as st
from descope.descope_client import DescopeClient

DESCOPE_PROJECT_ID = str(st.secrets.get("DESCOPE_PROJECT_ID"))
descope_client = DescopeClient(project_id=DESCOPE_PROJECT_ID)

st.title("Demo App")
st.write("This is a demo app with Descope-powered authentication and SSO")

Create a "Sign in with Google" button that launches the OAuth flow using the descope_client.oauth.start() method:

# … collapsed repeated code
descope_client = DescopeClient(project_id=DESCOPE_PROJECT_ID)

st.warning("You're not logged in, pls login")
with st.container(border=True):
    if st.button("Sign In with Google", use_container_width=True):
        oauth_response = descope_client.oauth.start(
            provider="google", return_url="http://localhost:8501"
        )
        url = oauth_response["url"]
        # Redirect to Google
        st.markdown(
            f'<meta http-equiv="refresh" content="0; url={url}">',
            unsafe_allow_html=True,
        )

st.title("Demo App")
# …

When clicked, this button triggers the OAuth flow. Descope generates a Google sign-in URL and redirects the user there.

Your Streamlit app should now look like this:

Click the Sign In with Google button, and you are redirected back to the app with a code query parameter after successfully authenticating via Google. This flow is known as the authorization code flow. In the next step, you'll exchange the returned code for a token that authenticates your users.

You can use the Streamlit st.query_params method to capture the code from the URL, and the descope_client.sso.exchange_token() method to trade it for a token. Along with the token, Descope also provides user data and a refresh token that renews the short-lived session token. By storing this information in Streamlit's session_state, you can persist authentication details across multiple runs and conditionally display your app's content only when a valid token is present.

To persist tokens and user data, update your code as follows:

import streamlit as st
from descope.descope_client import DescopeClient
from descope.exceptions import AuthException

DESCOPE_PROJECT_ID = str(st.secrets.get("DESCOPE_PROJECT_ID"))
descope_client = DescopeClient(project_id=DESCOPE_PROJECT_ID)

if "token" not in st.session_state:
    # User is not logged in
    if "code" in st.query_params:
        # Handle possible login
        code = st.query_params["code"]
        # Reset URL state
        st.query_params.clear()
        try:
            # Exchange code
            with st.spinner("Loading..."):
                jwt_response = descope_client.sso.exchange_token(code)
            st.session_state["token"] = jwt_response["sessionToken"].get("jwt")
            st.session_state["refresh_token"] = jwt_response["refreshSessionToken"].get(
                "jwt"
            )
            st.session_state["user"] = jwt_response["user"]
            st.rerun()
        except AuthException:
            st.error("Login failed!")

    st.warning("You're not logged in, pls login")
    with st.container(border=True):
        if st.button("Sign In with Google", use_container_width=True):
            oauth_response = descope_client.oauth.start(
                provider="google", return_url="http://localhost:8501"
            )
            url = oauth_response["url"]
            # Redirect to Google
            st.markdown(
                f'<meta http-equiv="refresh" content="0; url={url}">',
                unsafe_allow_html=True,
            )
else:
    # User is logged in
    try:
        with st.spinner("Loading..."):
            jwt_response = descope_client.validate_and_refresh_session(
                st.session_state.token, st.session_state.refresh_token
            )
            # Persist refreshed token
            st.session_state["token"] = jwt_response["sessionToken"].get("jwt")
        st.title("Demo App")
        st.write("This is a demo app with Descope-powered authentication and SSO")
        st.subheader("Welcome! you're logged in")
        if "user" in st.session_state:
            user = st.session_state.user
            st.write("Name: " + user["name"])
            st.write("Email: " + user["email"])
        if st.button("Logout"):
            # Log out user
            del st.session_state.token
            st.rerun()
    except AuthException:
        # Log out user
        del st.session_state.token
        st.rerun()

At this point, your app only displays content when a user is logged in. You've successfully implemented Streamlit authentication with OAuth, laying the foundation for full Streamlit SSO with enterprise providers like Okta in the next section.

Implementing SAML SSO in Streamlit

The Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between an IdP and a service provider (SP). In this setup, platforms like Okta act as the IdP, while your Streamlit app functions as the SP.

SAML SSO allows users to access multiple applications with a single login. This is especially valuable for organizations managing many apps, since it reduces friction for users and administrators alike.

In the SSO model, organizations that use your Streamlit app are represented as tenants. Each tenant groups users, permissions, and related configurations, giving you a way to handle enterprise customers with their own SSO setup.

Configuring Okta as the IdP and Descope as the SP

For this example, you'll use Okta as the IdP while Descope acts as the SP that integrates with your Streamlit app.

In the Descope console, create a new tenant: Go to the Tenants page and click + Tenant.

In the tenant Authentication Methods section, choose the SAML protocol. Enter your email domain in the SSO Domains field under Tenant Details.

Because Descope mediates communication between Okta and your app, the two need a secure, trusted connection. This connection is established by exchanging metadata XML documents between both platforms. The good news: Descope's built-in Okta integration makes this process much simpler.

Go to your Okta account and click Admin to access your admin dashboard:

Navigate to Applications > Applications and click Browse App Catalog to explore a comprehensive list of available integrations:

Search for Descope in the catalog and add the integration. This creates a new Okta app automatically.

In the General Settings tab, provide a label for your new Okta app.

Switch to the Assignments tab and assign users who should have access to your Streamlit app via SSO:

Switch to the Sign-On Options tab and select SAML 2.0. Copy the Metadata URL then paste it into your tenant's SSO configuration in Descope. Next, copy the ACS URL and Entity ID from Descope into the Advanced Sign-on Settings in Okta:

Expand the Attribute Statements section in Okta. Map the following values:
- firstName > user.firstName
- lastName > user.lastName
- email > user.email
- uid > user.id

These mappings define how user attributes are passed from Okta to Descope.

Back in Descope, update your tenant's SSO Mapping settings so attributes from Okta align correctly with Descope's schema.

Once this is complete, you've established a working SAML SSO configuration between Okta, Descope, and your Streamlit app.

It's worth noting that Descope also provides a self-service SSO configuration designed for multi-tenant environments. With this setup, each tenant can maintain its own SSO configuration, and tenant admins can manage their Descope SSO settings directly through your application.

To enable this, you can either:

Embed the out-of-the-box sso-config flow into your app's admin interface, or
Generate a configuration link that tenant admins can use directly.

For detailed implementation guidance, refer to the Descope documentation.

Implementing the SSO flow in Streamlit

Now that you've configured SAML SSO between Okta and Descope, the next step is to implement the flow inside your Streamlit app. This will let users authenticate through Okta and seamlessly return to your app. So let's add another button under the Sign In with Google button that starts the SSO flow when clicked.

First, you'll need your tenant ID from the Descope console:

Go to your tenant's settings.
Copy the Tenant ID.
Add it to your .streamlit/secrets.toml file with the DESCOPE_TENANT_ID key.
Update the st.container element in your code like this:

# … collapsed repeated code
TENANT_ID = str(st.secrets.get("DESCOPE_TENANT_ID")) # Get tenant ID from secret
# …
    with st.container(border=True):
        # … google button here
        if st.button("Sign in with SSO", use_container_width=True):
            sso_response = descope_client.sso.start(
                tenant=TENANT_ID, return_url="http://localhost:8501"
            )
            url = sso_response["url"]
            # Redirect to Okta
            st.markdown(
                f'<meta http-equiv="refresh" content="0; url={url}">',
                unsafe_allow_html=True,
            )
# …

Your Streamlit app should now look like this:

Click Sign In with SSO to go to Okta for verification. Sign in with one of the users you assigned earlier. After successful authentication, you're redirected back to your Streamlit app with a code query parameter—just like in the OAuth flow. Since you already implemented the code exchange, you'll be signed in automatically:

Managing authorization and user privileges

While authentication verifies the user's identity, authorization controls their access to resources and features based on predefined roles and permissions. The Descope console includes tools to manage user roles and permissions so you can enforce access control in your Streamlit app. After login, Descope returns role information you can use to tailor the UI and gate functionality.

All roles and permissions live under the Authorization page. A Tenant Admin role is created by default. Let's assign that role to a user and then conditionally display admin-only content in the app.

Go to the Users page, click the kebab menu of the user you want to update, and click Edit:

In the modal, select Tenant Admin in the Roles field and click Save:

Update your code to show an admin indicator:

# … collapsed repeated code
        if "user" in st.session_state:
            # …
            if "Tenant Admin" in user["roleNames"]:
                # Show admin-specific content
                st.success("ADMIN", icon="🤖")
# …

This should now be the view of the admin user when they're signed in:

This approach ensures that only authorized users see privileged features, improving both the security and integrity of your app.

You can find the full code on GitHub.

Streamlit SSO and authentication with Descope

You just wired Streamlit SSO with Descope end to end: created a Descope project, added OAuth social login, implemented SAML SSO with Okta, and gated features with roles. You now have a secure pattern you can reuse across Streamlit apps, from personal dashboards to multi-tenant products.

Ready to keep going? Use your Free Forever account to extend your app with passwordless options, adaptive MFA, and SCIM provisioning. Have questions or edge cases to discuss? Book time with the team for a focused walkthrough.

Next.js 14 Authentication and RBAC with App Router

Mrunank Pawar — Wed, 01 Apr 2026 23:44:55 +0000

This blog was originally published on Descope

Ensuring your application is secure through resilient authentication and authorization mechanisms is crucial in the Next.js 14 development process. This helps to ensure that only authenticated users can access the protected resources of your application and that each user can access only the resources they are allowed to access.

In this guide, you'll learn how to implement Next.js 14 authentication and role-based access control (RBAC) using the App Router and Descope. Whether you're building a new application or enhancing an existing one, this guide will equip you with the skills to create secure login and access controls.

In this guide

Set up Descope authentication in Next.js 14
Implement magic link login flows
Add role-based authorization (RBAC)
Protect routes with middleware
Manage user sessions and tokens

Understanding Next.js 14 authentication and RBAC

Before implementing Next.js 14 authentication, let's clarify the core concepts you'll work with in this tutorial.

Authentication vs. authorization

Both authentication and authorization are integral to developing a secure Next.js 14 application, but they serve distinct purposes. Authentication is the process of verifying a user’s identity and is typically achieved through a set of login credentials, such as email and passwords, magic links, passkeys or other auth methods. Authorization determines whether the authenticated user is allowed to access specific resources or perform certain actions. This tutorial implements both using Next.js 14 with App Router.

Want to learn more about the basics? See our complete guide: Authentication vs. Authorization: What's the Difference?

RBAC in this tutorial

This tutorial uses role-based access control (RBAC) to manage who can do what in the blogging app:

Editor role: Can create and edit posts
Admin role: Can view and publish posts

Instead of assigning permissions to individual users, you'll assign them to roles. Then you’ll assign users to roles. This makes managing permissions scalable as your app grows. To learn more about RBAC concepts, benefits, and implementation strategies, see: What Is RBAC: Your Simple Guide

Next.js 14 and App Router

Next.js 14 supports both client-side rendering (CSR) and server-side rendering (SSR), each with different implications for authentication and authorization:

Client-side rendering (CSR): The client renders content after the initial page load. This can cause a brief flash of unauthorized content before auth state is verified. You can improve UX with loading indicators or skeleton screens during auth checks.
Server-side rendering (SSR): The server handles rendering before sending the content to the client. This approach prevents unauthorized content flashes since the server clocks the request until it verifies the auth state.

Comparing frameworks? See our comparison: Svelte vs Next.js

This tutorial uses SSR with App Router, Next.js 14's file-system-based routing solution, to implement authentication that verifies on the server before rendering.

Setting up Descope for Next.js 14 authentication

Descope simplifies adding Next.js 14 authentication and authorization by offering an intuitive SDK and visual flows to build authentication screens.

Descope Flows is a visual no-code interface to build screens and authentication flows for common user interactions with your application, such as login, sign-up, user invites, and multi-factor authentication (MFA). This feature abstracts away the implementation details of authentication methods, session management, and error handling, allowing you to focus on building the core features of your application rather than handling these complexities.

Using Descope eliminates the need to write authentication and authorization logic from scratch, saving valuable development time and reducing the risk of security vulnerabilities. Descope's infrastructure ensures your application's authentication and authorization mechanisms are secure, scalable, and easy to maintain.

The following sections explain how you can implement these features in a Next.js application using Descope. To follow along, you need the following:

Creating a Descope project

To demonstrate Next.js 14 authentication with RBAC, you'll build a simple blogging application using the editor and admin roles described above.

To begin, you’ll need to create a new project. On the Descope Console, create a new project with the name descope-nextjs-auth-rbac:

Navigate to the project setup. Select Consumers under Who uses your application? and then click Next:

Select Magic Link for Which authentication methods do you want to use? and then click Next:

Skip the MFA method step and click Go ahead without MFA. You can always set this up later:

On the next page, you can view the flows generated for your project. Click Next to generate these flows:

Once the flows are generated, select Project from the sidebar and take note of your project ID, which you’ll use in the next step:

Next, you need to obtain a management key. Select Company from the sidebar, select the Management Keys tab on the Company page, and click the + Management Key button to create a new management key. Provide the key name and, under Project Assignment, select Use this management key for all the projects in the company. Click the Generate Key button and copy the value of your key:

Once you have the key, you can implement authentication for the Next.js application. You will come back to the console to set up the RBAC.

Exploring the starter template

This walkthrough uses a simple web app shell. To keep this guide focused on authentication and authorization, we've prepared a starter template for the blogging application. In this section, you'll clone and set up the template.

To clone the template to your local machine, execute the following command in the terminal:

git clone --single-branch -b starter-template https://github.com/kimanikevin254/descope-nextjs-auth-rbac.git

Navigate into the project directory and install all the dependencies:

cd descope-nextjs-auth-rbac && npm i

shell

Create a .env project in the root folder and add the following content, which defines the location of the SQLite database:

DATABASE_URL="file:./dev.db"

shell

Run a Prisma migration for the models defined in the prisma/schema.prisma file:

npx prisma migrate dev --name init

shell

Run the app with the command npm run dev and navigate to http://localhost:3000/ on your web browser. You should see a dashboard where the posts are displayed. At the moment, no posts are available:

Users are able to write posts by clicking the Start Writing button, which directs them to the Write a Post page that has a rich text editor:

At this stage, the template is ready, but don’t create any posts until you have implemented authentication and authorization.

Adding authentication to Next.js 14

This section walks you through implementing authentication in your Next.js 14 application using Descope. You'll use code examples and screenshots to guide each step.

Key steps

Install the Descope Next.js SDK
Wrap your app with Descope authentication
Configure the “sign up or in” function
Protect routes with authentication middleware
Test the authentication flow

To get started, execute the following command in the terminal to install the Descope Next.js SDK, which you’ll use to implement authentication:

npm i @descope/nextjs-sdk

javascript

Open the app/layout.js file and replace the existing code with the following to wrap the whole application with the Descope Auth Provider:

import { Inter } from "next/font/google";
import "./globals.css";
import { AuthProvider } from "@descope/nextjs-sdk";

const inter = Inter({ subsets: ["latin"] });

export const metadata = {
   title: "Descope - Next.js Auth",
   description:
       "Demonstrating how to add auth & RBAC to Next.js 14 with Descope",
};

export default function RootLayout({ children }) {
   return (
       <AuthProvider projectId={process.env.DESCOPE_PROJECT_ID}>
           <html lang="en">
               <body
                   className={`${inter.className} max-w-screen-lg mx-auto py-4`}
               >
                   {children}
               </body>
           </html>
       </AuthProvider>
   );
}

javascript

You will set the value of DESCOPE_PROJECT_ID in the .env file later on.

You can use the sign-up-or-in flow that you generated when configuring the project to allow the user to sign in to the application. The sign-up-or-in flow presents the user with a Welcome screen where they are prompted to provide their email address.

Once the user provides the email address and clicks the Continue button, a magic link is sent to the provided email address. Once the user clicks the magic link, Descope verifies the link, and the user is authenticated. The flow then checks if the user is new or returning. If the user is new, they are prompted to provide additional information(their name), and their details are updated.

Here’s a visual representation of the flow in practice:

Open the app/sign-in/page.js file and replace the existing code with the following:

"use client";

import { Descope } from "@descope/nextjs-sdk";
import axios from "axios";
import { useRouter } from "next/navigation";

export default function Page() {
   const router = useRouter();

   // Register user or redirect to home
   const handleEvent = async (event) => {
       try {
           if (event.detail.firstSeen !== true) {
               return router.replace("/");
           }

           // Register the user
           const { data } = await axios.post("/api/register", {
               descopeUserId: event.detail.user.userId,
               email: event.detail.user.email,
               name: event.detail.user.name,
           });

           if (data.error) {
               alert("Something went wrong");
           } else {
               return router.replace("/");
           }
       } catch (error) {
           console.log(error);
       }
   };
   return (
       <Descope
           flowId="sign-up-or-in"
           onSuccess={(e) => handleEvent(e)}
           onError={(e) => alert("Something went wrong. Please try again.")}
       />
   );
}

javascript

In the preceding code, once the user signs up or in successfully, the event data returned from this component is passed to the handleEvent function.

This function checks if the user is new by examining event.details.firstSeen. If the user is not new, they are redirected to the home screen. Otherwise, it sends a POST request to the /api/register endpoint with the user’s details to register the user. If the registration is successful, the user is redirected to the home page; otherwise, an error message is displayed.

The /api/register endpoint is defined in the app/api/register/route.js files, and it adds the user to the local database.

You also need to set up a middleware to enforce authentication for all the pages in this application. Create a file named middleware.js in the project root folder and add the following code:

import { authMiddleware } from "@descope/nextjs-sdk/server";

export default authMiddleware({
   projectId: process.env.DESCOPE_PROJECT_ID,
   redirectUrl: process.env.SIGN_IN_ROUTE,
});

export const config = {
   matcher: ["/((?!.+\\.[\\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
};

shell

This code uses the authMiddleware function provided by the Descope Next.js SDK to protect all routes and redirect unauthenticated users to the sign-in page.

Update the .env file with the following:

DESCOPE_PROJECT_ID=<YOUR-PROJECT-ID>
DESCOPE_MANAGEMENT_KEY=<YOUR-MANAGEMENT-KEY>

SIGN_IN_ROUTE="/sign-in"

javascript

Make sure to replace the placeholder values with the values you obtained earlier.

The authentication for your Next.js application is now complete.

Before you test it, open the app/write/page.js file. In this file, notice that the savePost function requires the Descope user ID. You can retrieve this using the hooks provided by the Next.js SDK.

Add the following import statement to the file:

import { useUser } from "@descope/nextjs-sdk/client";

javascript

Add the following statement that retrieves the user just before the savePost function:

const { user } = useUser();

javascript

You can now test the authentication flow.

On your browser, navigate to http://localhost:3000. You are redirected to http://localhost:3000/sign-in since you have not signed in. It should look like this:

Provide your email address, click the link sent to your inbox, and provide your name since this is the first time you’re signing in. Then you are redirected to the home page:

This confirms that the authentication is working as expected.

Adding authorization to Next.js 14

Currently, anyone can log in to the application, create posts, submit them for approval, and approve the posts. For this example, you want to specify that editors can write posts and then submit them for approval, and admins can publish the posts.

Key steps

Create roles and assign permissions in Descope
Control UI visibility based on user roles
Validate roles in API routes
Configure session tokens for authorization
Test role-based permissions

Before you implement this functionality, click the Start Writing button and create a few posts to test the application with:

Go to the Descope Console, select Authorization from the sidebar, and click the + Role button. In the Add Role modal, provide “editor” as the name and “Can write posts and submit them for approval” as the description. Then click the Add button:

Repeat the process to create a role for the admin. Provide “admin” as the role and “Can toggle a post’s published status” as the description.

Assign the “editor” role to the user who is logged in to the application. In the Descope Console, select Users from the sidebar to edit the user details:

On the user details modal, select + Add Tenant / Role, assign the editor role, and click Save:

Open the app/page.js file and add the following import statement:

import { useUser } from "@descope/nextjs-sdk/client";

javascript

Add the following code before the fetchPosts function.

const { user } = useUser();

javascript

This hook allows you to retrieve the user’s details.

Locate the following lines of code in the same file:

<Link
   href={"/write"}
   className="px-4 py-1 border rounded-lg bg-black text-white"
>
   Start Writing
</Link>

javascript

Replace it with the following to display only the Start Writing button to editors:

{
   user?.roleNames?.includes("editor") && (
       <Link
           href={"/write"}
           className="px-4 py-1 border rounded-lg bg-black text-white"
       >
           Start Writing
       </Link>
   )
}

javascript

Open the app/posts/[postId]/page.js file and add the following lines of code in their respective locations (indicated by the comments):

import { useUser } from "@descope/nextjs-sdk/client"; // After the import statement

const { user } = useUser(); // Before the return statement

javascript

Locate the following lines of code:

<Button
   variant="default"
   className="px-6 mt-6"
   onClick={() => togglePublishedStatus()}
>
   {post.published ? "Unpublish" : "Publish"}
</Button>

javascript

Replace it with the following to specify that only admins can publish/unpublish a post:

{
   user?.roleNames?.includes("admin") && (
       <Button
           variant="default"
           className="px-6 mt-6"
           onClick={() => togglePublishedStatus()}
       >
           {post.published ? "Unpublish" : "Publish"}
       </Button>
   )
}

javascript

For additional security, you also validate these roles in the API router handlers. In the lib folder, create a new file named descope.js and add the following code:

import { createSdk } from "@descope/nextjs-sdk/server";

export const descopeSdk = createSdk({
   projectId: process.env.DESCOPE_PROJECT_ID,
   managementKey: process.env.DESCOPE_MANAGEMENT_KEY,
});

javascript

This code initializes a Descope client instance and exports it for use in other parts of the application.

Open the app/api/posts/create/route.js file and add the following code just after const data = await request.json():

// Make sure the user has the editor role
const userRoles = descopeSdk.getJwtRoles(data.sessionToken);

if (!userRoles?.includes("editor")) {
   throw new Error("User is not an editor");
}

javascript

This code ensures that the user has the editor role. If not, it throws an error.

Remember to add the following import statement:

import { descopeSdk } from "@/lib/descope";

javascript

Open the app/api/posts/toggleStatus/route.js file and add the following code just after const data = await request.json() to throw an error if the user making the request does not have the admin role:

// Make sure the user has the admin role
const userRoles = descopeSdk.getJwtRoles(data.sessionToken);

if (!userRoles?.includes("admin")) {
   throw new Error("User is not an admin");
}

javascript

Remember to add the following import statement:

import { descopeSdk } from "@/lib/descope";

javascript

With the route handlers verifying the user roles, you need to make sure that the session token is passed in the request body. Start by opening the app/write/page.js file and retrieving the session token using the useSession hook:

const { sessionToken } = useSession();

javascript

Make sure the useSession hook is imported into the file:

import { useSession, useUser } from "@descope/nextjs-sdk/client";

javascript

Add the retrieved session token to the body of the POST request in the savePost function:

const { data } = await axios.post("/api/posts/create", {
   title,
   content,
   descopeUserId: user?.userId,
   sessionToken,
});

javascript

Open the app/posts/[postId]/page.js file and retrieve the session token using the useSession hook:

const { sessionToken } = useSession();

javascript

Make sure the hook is imported into the file:

import { useSession, useUser } from "@descope/nextjs-sdk/client";

javascript

Replace the togglePublishedStatus function with the following code that ensures that the session token is passed to the route handlers:

const togglePublishedStatus = async () => {
   try {
       const { data } = await axios.put("/api/posts/toggleStatus", {
           postId: params.postId,
           sessionToken,
       });

       setPost(data.data);
   } catch (error) {
       alert("Something went wrong");
       console.log(error);
   }
};

Now, all the authorization checks are complete. You can test to see if everything is working as expected.

Navigate to http://localhost:3000/sign-in and log in to the application. Since you assigned the editor role to the user, you can see the Start Writing button:

Click on a post to open the details page. However, you cannot see the Publish/Unpublish button since only admins are allowed to see it:

Now, go back to the Descope Console and assign the user the admin role.

Go back to the application and refresh the page. Since the user now has the admin role, they can see the button to Publish/Unpublish a post:

This confirms that the authorization flow is working as expected.

You can access the complete Next.js 14 authentication code on GitHub.

Next steps for Next.js 14 authentication

Your authentication system is production-ready. You can extend it by adding social logins, MFA, or additional roles—all without writing custom auth logic.

This flexibility is what makes Descope's CIAM platform powerful for production applications. Use no-code workflows to add authentication methods, configure authorization rules, and manage users at scale, so you can focus on your application's core features instead of authentication infrastructure.

Start building with a Free Forever account today. Have questions about implementing RBAC or Next.js authentication? Book time with our experts.

Adding Authentication and SSO to a Reflex App

Mrunank Pawar — Fri, 27 Mar 2026 19:56:05 +0000

This blog was originally published on Descope

Reflex is an open-source full-stack web framework written in and for Python that lets you build both frontend UI and backend logic in pure Python, i.e., you don’t need to manually write JavaScript or separately manage a React/Vue frontend and a separate backend.

By adding Descope to your Reflex application, you can immediately take advantage of a full-fledged identity platform—complete with passwordless authentication, MFA, passkeys, social login, enterprise SSO, and customizable user journeys.

This lets you keep writing your entire Reflex project in Python while relying on Descope to seamlessly deliver the advanced authentication and security capabilities needed for real-world, scalable applications.

Let’s begin!

Prerequisites

It’s helpful to familiarize yourself with Python and Reflex. You’ll also need a Descope account, but don’t worry if you don’t have one yet—you’ll learn how to set one up shortly. The free tier will be sufficient for you to follow along.

Create a Descope Project

The first step in connecting your Reflex app to Descope is to create a new Project in the Descope Console.

Go to the Descope sign-up page and register for a free account (or log in if you already have one).
From the top-left menu in the console, click + Project to set up a new project.

In Settings > Project, you’ll find your Project ID, which is a unique identifier used to link your Reflex app to Descope.

Best practice: Never paste this ID directly into your code. Instead, store it securely as an environment variable in a .env file. We’ll configure this later in the blog.

Create the Reflex app

With your Descope Project set up, let’s move to the Reflex side. We’ll start with a dashboard app template and then integrate authentication step-by-step.

Create a new directory for this app and clone the company dashboard template. Optionally, set up a Python virtual environment inside it.
Add reflex-descope-auth to the requirements.txt file. Note: This is the Reflex Descope Auth plugin, which uses standard OIDC protocols to handle the login process in a reliable, familiar way.
Now run this command to install all the dependencies using the command below:

pip install -r requirements.txt

Next, create a .env file and set these environment variables in the project.

DESCOPE_PROJECT_ID=<your-descope-project-id>
DESCOPE_FLOW_ID=<your-flow-id>
DESCOPE_LOGOUT_REDIRECT_URI=http://localhost:3000
SESSION_SECRET=<secure-random-secret>

You can generate a secret using Python’s secrets module:

python -c "import secrets; print(secrets.token_hex(32))"

This is what your project structure should look like:

.
├── .gitignore
├── app
│   ├── __init__.py
│   ├── app.py
│   ├── components
│   │   ├── __init__.py
│   │   ├── documents_table.py
│   │   ├── header.py
│   │   ├── key_metrics.py
│   │   ├── sidebar.py
│   │   └── visitors_chart.py
│   └── states
│       ├── __init__.py
│       ├── auth_state.py
│       └── dashboard_state.py
├── apt-packages.txt
├── assets/
├── .env
├── requirements.txt
└── rxconfig.py

Log in a user

In the app.py file, we’ll add a button that calls start_login, a built-in method that initiates the login flow and redirects users to the Descope authorization endpoint.

def index() -> rx.Component:
    """The main page, which serves as the login entry point."""
    return rx.el.div(
        rx.el.section(
            rx.el.div(
                rx.el.button(
                    "Login with Descope",
                    on_click=AuthState.start_login,
                    class_name=(
                        "mt-8 px-8 py-3 text-white bg-red-600 rounded-lg font-semibold "
                        "hover:bg-blue-700 transition-colors shadow-md"
                    ),
                ),
                class_name="flex flex-col items-start max-w-xl",
            ),
            class_name="container mx-auto flex flex-col lg:flex-row items-center justify-between gap-12 px-4 py-16",
        ),
        class_name="w-full bg-gray-50",
    )

The dashboard_page function defines the main authenticated dashboard view of the application. It’s registered as a Reflex page using the @rx.page() decorator with the root route (/).

When a user visits this page, the on_load parameter triggers the AuthState.check_login method to verify if the user is authenticated. If the user isn’t logged in, they’ll be redirected to the login flow automatically.

@rx.page(route="/", on_load=AuthState.check_login)
def dashboard_page() -> rx.Component:
    """The main dashboard page."""
    return rx.el.div(
        sidebar(),
        rx.el.main(
            header_bar(),
            rx.el.div(
                key_metrics_section(),
                visitors_chart_section(),
                documents_table_section(),
                class_name="p-6 space-y-6",
            ),
            class_name="w-full h-[100vh] overflow-y-auto",
        ),
        class_name="flex flex-row bg-gray-50 h-[100vh] w-full overflow-hidden",
        on_mount=DashboardState.load_initial_data,
    )

The callback page handles the authentication redirect after a user logs in. It’s defined using the @rx.page() decorator and mapped to the /callback route.

When the user returns to this route after completing authentication, the on_load parameter calls AuthState.auth_redirect. This method processes the login response, typically validating tokens, storing session data, and determining whether the login succeeded or failed.

@rx.page(route="/callback", on_load=AuthState.auth_redirect)
def callback() -> rx.Component:
    return rx.el.div(
        rx.cond(
            AuthState.error_message != "",
            rx.el.div(
                rx.el.h1("Login Failed", class_name="text-red-500"),
                rx.el.p(AuthState.error_message),
                rx.el.button(
                    "Try Again",
                    on_click=AuthState.start_login,
                    class_name="px-4 py-2 text-white bg-blue-600 rounded-md hover:bg-blue-700",
                ),
                class_name="flex flex-col items-center space-y-4",
            ),
            rx.el.div(
                rx.el.p("Processing login..."), class_name="flex items-center space-x-2"
            ),
        ),
        class_name="flex items-center justify-center h-screen",
    )

The auth_error page provides a dedicated route for handling login failures. It’s defined at the /auth-error path and serves as a fallback whenever something goes wrong during the authentication process. For example, if token validation fails, the user denies consent, or the callback flow encounters an unexpected error.

@rx.page(route="/auth-error")
def auth_error() -> rx.Component:
    return rx.el.div(
        rx.el.h1("Login Failed", class_name="text-red-500"),
        rx.el.p(AuthState.error_message),
        rx.el.button(
            "Try Again",
            on_click=AuthState.start_login,
            class_name="px-4 py-2 text-white bg-blue-600 rounded-md hover:bg-blue-700",
        ),
        class_name="flex flex-col items-center space-y-4 h-screen justify-center",
    )

We’ll also add additional routes to this file to handle page protection and move the dashboard to a dedicated page.

app.add_page(dashboard_page, route="/dashboard")
app.add_page(callback, route="/callback")
app.add_page(auth_error, route="/auth-error")

Define AuthState in Reflex

Authentication in Reflex is handled through reactive state classes. The reflex-descope-auth plugin provides a base class called DescopeAuthState, which already implements the full authentication lifecycle for you. By subclassing it, we can customize how our app handles redirects and session checks after a user logs in or out. The reflex-descope-auth plugin validates Descope tokens only once during finalize_auth. After that, Reflex simply stores the session in state and does not re-check the exp or rexp claims in the token automatically.

finalize_auth is a built-in method that completes the authentication process after the redirect from Descope, exchanges the authorization code for tokens, verifies ID token, and creates a session token for the user.

By using yield, Reflex processes each step reactively—first finalizing auth, then deciding the next redirect.

import reflex as rx
from reflex_descope_auth import DescopeAuthState


class AuthState(DescopeAuthState):
    @rx.event
    async def auth_redirect(self):
        yield DescopeAuthState.finalize_auth()
        if getattr(self, "error_message", None):
            yield rx.redirect("/auth-error")
            return
        yield rx.redirect("/dashboard")

    @rx.event
    def check_login(self):
        if not self.logged_in:
            return rx.redirect("/")

check_login() is a custom method that acts as a page guard for any route that should only be accessible to authenticated users. It works by:

Checking the reactive state variable self.logged_in (which is automatically managed by DescopeAuthState).
If the user isn’t authenticated (self.logged_in is False), it immediately returns a redirect to the homepage (/), which serves as the login page.

This ensures that only valid sessions can access private pages like /dashboard.

Implementing OAuth social logins, magic links, and SSO

Once your Reflex app is wired up with the Reflex Descope Auth plugin, adding new authentication methods becomes incredibly simple. Descope flows let you drag, drop, and configure options like OAuth social logins, magic links, and SAML/OIDC SSO without changing any of your Reflex code.

If you want users to sign in with Google, GitHub or any other providers, you can configure these OAuth providers in the authentication methods in the console and add the OAuth action in the flow. For passwordless experiences, you can switch to magic link login by adding the built-in magic link action in your flow. And when your app needs enterprise authentication, you can add a SSO action to the same flow.

If you’d like to try SSO end-to-end, you can spin up a tenant and walk through the setup using the Mock SAML Testing guide. And if your organization already uses a SAML IdP such as Okta, ADFS, or PingFederate, you can simply plug in its metadata URL in place of the mock provider.

With everything controlled through Descope’s visual flow editor, your Reflex integration remains the same, with the plugin automatically handling redirects and token exchange. Here’s an example flow that combines the social login, magic link and SSO authentication:

One of the biggest hurdles is enabling each customer to set up Single-Sign-On (SSO) with their own identity provider (IdP). Descope’s SSO Setup Suite simplifies how organizations configure Single Sign-On (SSO) for their tenants. Instead of manually exchanging metadata and troubleshooting IdP configurations, the suite offers a guided, self-service flow that allows tenant admins to set up and test their SSO integration (SAML or OIDC) end-to-end.

With built-in steps for attribute mapping, SCIM provisioning, and domain routing, it significantly reduces setup time and support overhead by empowering customers to get their SSO running smoothly with minimal developer involvement.

Displaying the user name and logging out a user

Once a user successfully signs in, we can use AuthState.userinfo to display the user’s profile details such as their name, while AuthState.logged_in tracks the current authentication status. userinfo comes from the JWT claims inside the session token. The plugin extracts claims from the token and userinfo simply reads from there. To be able to add custom attributes, you can define custom claims in Descope.

In the code snippet below, the header displays a personalized welcome message along with a Logout button when the user is signed in and AuthState.logout will allow the user to log out.

import reflex as rx
from app.states.auth_state import AuthState


def header_bar() -> rx.Component:
    """The header bar component."""
    return rx.el.div(
        rx.el.div(
            rx.cond(
                AuthState.logged_in,
                rx.el.div(
                    rx.el.span(
                        f"Welcome, {AuthState.userinfo.get('name', 'User').to(str).split(' ')[0]}",
                        class_name="text-sm font-medium text-gray-700",
                    ),
                    rx.el.button(
                        "Logout",
                        on_click=AuthState.logout,
                        class_name="px-4 py-1 text-sm text-white bg-red-600 rounded-md hover:bg-red-700",
                    ),
                    class_name="flex items-center space-x-4",
                ),
                rx.fragment(),
            )
        ),
        class_name="flex items-center justify-between h-12 px-6 bg-white border-b border-gray-200",
    )

The dashboard will then look similar to this:

Reflex SSO and authentication with Descope

With Descope, implementing authentication in a Reflex app becomes both simple and highly flexible. Descope’s flows let you design every step of the user journey without managing complex logic yourself. The Reflex Descope Auth plugin then brings these flows directly into your application, handling the redirects and tokens. Together, they give you a powerful, low-code way to add secure, customizable authentication to any Reflex project.

If you have any questions about Descope or a customer identity project we can help with, book a demo with our auth experts.

Add Authentication and SSO to Your Gradio App

Mrunank Pawar — Wed, 25 Mar 2026 20:46:42 +0000

This blog was originally published on Descope

Gradio is an open source Python package that allows you to create web-based interfaces for AI models, APIs, or any Python function. Its simplicity and flexibility make it a popular choice among developers who want to quickly prototype and deploy web-based interfaces without worrying about frontend development.

Secure authentication methods are needed for these applications to help prevent sensitive data and models from being exposed and ensure that only authorized users can access certain features. Descope is an authentication and user management platform that simplifies the process of adding secure authentication to your applications. It offers a range of authentication methods and out-of-the-box support for OAuth 2.0 and OpenID Connect (OIDC), which makes it easy to implement authentication in your Gradio app.

In this guide, you’ll learn how to integrate Descope authentication and single sign-on (SSO) into a Gradio application. You’ll add basic auth to your Gradio application using magic links and social login. You’ll also implement SSO into the application by configuring Descope to use Okta as an identity provider(IdP).

Why is adding SSO important for these types of apps?

Many Gradio applications are used for business-to-business (B2B) purposes, where different organizations need secure access to their machine-learning models or APIs. In such cases, SSO is essential for several reasons:

Seamless access: Employees can log in using their company credentials instead of managing separate usernames and passwords.
Improved security: SSO reduces password fatigue and minimizes security risks associated with weak or reused passwords.
Better user management: IT administrators can enforce access policies, control permissions, and revoke access centrally through identity providers like Okta or Azure AD.

Prerequisites

To follow this tutorial, you need the following:

A Descope account
An Okta developer account
Python 3 installed on your local machine
Git CLI installed on your local machine
A code editor and a web browser

Creating a Gradio application

To keep the focus on implementing authentication and SSO, the tutorial uses a prepared starter template that you’ll build on. To clone it to your local machine, execute the command below:

git clone --single-branch -b starter-template https://github.com/kimanikevin254/descope-gradio-auth-sso.git

The Gradio application you just cloned is mounted within a FastAPI application. This setup is necessary because Gradio only supports authentication with external OAuth providers, such as Descope, when it is mounted inside a FastAPI app.

Here’s an overview of the most important files in this project:

app/core/config.py: Loads environment variables and sets application configurations using Pydantic.
app/ui/gradio_apps/: Contains three simple Gradio applications:
- admin_dashboard.py: Displays user info and a logout button. In a real-world app, this would handle admin-specific features.
- user_dashboard.py: Similar to the admin dashboard but for regular users. This is where you would implement non-admin functionalities.
- login_page.py: A simple login page that prompts users to log in with a login button.
app/ui/gradio_mount.py: Defines the GradioMounter class, which mounts all Gradio apps to the FastAPI application.
.env.example: Defines the environment variables you will require in this project.

You’ll explore the other files later.

With the files cloned to your local machine, you can move on to setting up the application. Start by creating a virtual environment, activating it, and installing all the dependencies:

python3 -m venv .venv # Create the virtual environment

source .venv/bin/activate #Activate it

pip install -r requirements.txt # Install dependencies

Rename the .env.example file to .env:

mv .env.example .env

Run the application using the command fastapi dev app/main.py and navigate to http://localhost:8000/auth/ to view the login page created using Gradio:

To view the admin dashboard, navigate to http://localhost:8000/gradio/admin:

To view the user dashboard, navigate to http://localhost:8000/gradio/user:

As you can see, all the dashboards are publicly available, which poses some security risks. In the next sections, you’ll add authentication to protect them and authorization to make sure that only users with the appropriate role can access the admin dashboard.

Setting up Descope

To integrate Descope as an external OAuth provider for your Gradio application, you’ll need to apply some configurations in your Descope console.

Open your Descope console and create a new project by clicking the project dropdown and selecting + Project:

Provide a project name on the Create project form and click Create:

You need to define a flow that will support the authentication methods you require for this project: magic links, social login, and SSO. To simplify the process, this tutorial uses a preconfigured flow included in the starter template. You’ll find it in the root folder as sign-up-or-in.json. You only need to import it into Descope. To do this, navigate to Flows > sign-up-or-in and select Import flow / Export flow > Import flow inside the flow editor. This will allow you to upload the flow from your local machine:

The flow you just imported offers three login options on the welcome screen: magic link, SSO, and social login. If a user chooses the magic link, they receive an email with a link. Clicking the link prompts new users to provide extra details while existing users get a JWT and complete the process. For social login or SSO, users are redirected to their provider, and after successful authentication, they receive a JWT, ending the flow.

Authenticating with Descope

With Descope fully set up, you can now integrate it as a custom OAuth provider for your Gradio application. You’ll need to configure an OIDC app in the Descope dashboard to obtain the necessary endpoints and credentials for the authorization code flow.

Here are the required credentials:

Client ID: A unique public identifier assigned to the application
Client secret: A confidential key shared only between the application and the authorization server
Authorization endpoint: The URL that starts the authentication process
Access token endpoint: The URL used to exchange an authorization code for access tokens
User info endpoint: The URL that retrieves details about the authenticated user
Redirect URL: The destination where users are sent after completing authentication
JWKs URI: The URL where the authorization server’s public keys are stored for verifying tokens
Scopes: Permissions that define what data and actions the application can access on behalf of the user

You will define these in the .env file. Some values for the variables are already included in the starter template, as are common for everyone. To get the ones that are not provided, navigate to Applications > OIDC default application on your Descope console. Scroll down to the SP Configuration section, copy the value of the Client ID, and assign it to the OAUTH_CLIENT_ID variable in the .env file:

Make sure you also replace the placeholder inside the OAUTH_JWKS_URI's value with the same client ID.

The OAUTH_SCOPES variable in the .env file specifies the scopes your application will request from Descope. However, Descope does not include the descope.claims (user’s roles, permissions, and tenants) and descope.custom_claims (user’s custom claims) scopes in its response by default unless explicitly configured.

To enable these scopes, go to the OIDC default application details page. In the IDP Configuration section, add descope.claims and descope.custom_claims under Supported Claims. Make sure to save the changes:

To obtain the value for the OAUTH_CLIENT_SECRET variable, navigate to M2M > + Access Key on your Descope console. On the Generate Access Key page, provide a name for your key and select Generate Key. Copy the value of the generated key and assign it to the OAUTH_CLIENT_SECRET variable in the .env file:

You now have all the required values for implementing the authentication logic. Open the app/core/auth.py file and add the following method to the Auth class to initialize the OAuth client with the necessary settings:

# Initialize the OAuth client with settings
def init_oauth(self, settings):
   self.settings = settings
   self.oauth.register(
    name=self.settings.OAUTH_CLIENT_NAME,
    client_id=self.settings.OAUTH_CLIENT_ID,
    client_secret=self.settings.OAUTH_CLIENT_SECRET,
    authorize_url=self.settings.OAUTH_AUTHORIZE_URL,
    access_token_url=self.settings.OAUTH_ACCESS_TOKEN_URL,
    redirect_uri=self.settings.OAUTH_REDIRECT_URI,
    jwks_uri=self.settings.OAUTH_JWKS_URI,
    userinfo_endpoint=self.settings.OAUTH_USERINFO_ENDPOINT,
    client_kwargs={'scope': self.settings.OAUTH_SCOPES},
   )

Add the following methods to the same class. These methods will redirect the user to the authorization endpoint set up for the OAuth client and exchange the returned authorization code for an access token:

# Redirect to authorization endpoint
async def authorize_redirect(self, request: Request, redirect_uri: str):
   return await getattr(self.oauth, self.settings.OAUTH_CLIENT_NAME).authorize_redirect(request, redirect_uri)

# Exchange authorization code for access token   
async def authorize_access_token(self, request: Request):
   try:
    return await getattr(self.oauth, self.settings.OAUTH_CLIENT_NAME).authorize_access_token(request)
   except OAuthError as error:
    raise HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail=f"OAuth error: {error.error}"
    )

Add the following method to the same class to retrieve the currently authenticated user from the session:

# Get the current authenticated user name
   def get_current_user(self, request: Request) -> Optional[str]:
    user = request.session.get("user")
    if user:
        return user['email']

This method helps check if a request is authenticated when accessing API routes. If the user is not authenticated, you can take appropriate action, such as redirecting them to the login page.

You’ll also need a method to protect Gradio apps by ensuring the user is authenticated and has the necessary roles. Add the following method to the Auth class:

# Authenticate user and authorize based on path and roles
# To protect Gradio app routes
def authenticate_and_authorize(self, request: Request) -> Optional[str]:
   path = request.url.path
   user = request.session.get("user", {})
   tenants = user.get('tenants', [])
   roles = set()

   if isinstance(tenants, dict):
    for data in tenants.values():
        roles.update(data.get('roles', []))

   # Avoid blocking the gradio queue requests
   if '/gradio_api/queue' in path and user:
    return user['email']

   if user and self.settings.ADMIN_ROLE in roles and path == self.settings.ADMIN_DASHBOARD_PATH:
    print('pass. returning', user['email'])
    return user['email']
   elif user and path == self.settings.USER_DASHBOARD_PATH:
    return user['email']
   else:
    return None

Add the following method to the Auth class to determine which Gradio app an authenticated user should see based on their roles:

# Determine the Gradio app to show the user based on their roles
def get_user_redirect_path(self, request: Request) -> str:
   user = request.session.get("user", {})
   tenants = user.get('tenants', [])
   roles = set()

   if isinstance(tenants, dict):
    for data in tenants.values():
        roles.update(data.get('roles', []))
   else:
    print('You have not set up tenants in your Descope account. You can only access the user dashboard since the roles needed to access the admin dashboard are set up via the tenant.')

   if not user:
    return self.settings.LOGIN_PAGE_PATH

   if self.settings.ADMIN_ROLE in roles:
    return self.settings.ADMIN_DASHBOARD_PATH
   else:
    return self.settings.USER_DASHBOARD_PATH

To ensure the OAuth client is correctly initialized when the application starts, open the app/main.py file and add the following code immediately after the middleware configuration:

# Initialize OAuth client
auth.init_oauth(settings)

Set up all the auth routes by adding the code to the app/api/routes/auth_router.py file:

# Redirect to OAuth login provider
@router.get('/login')
async def login(request: Request):
   redirect_uri = request.url_for('auth_callback')
   return await auth.authorize_redirect(request, redirect_uri)

# Handle OAuth callback after successful login
@router.get("/auth/callback", name="auth_callback")
async def auth_callback(request: Request):
   try:
    token = await auth.authorize_access_token(request)
    user = token.get("userinfo")
    request.session["user"] = dict(user)
    return RedirectResponse(url="/", status_code=HTTP_302_FOUND)
   except HTTPException as e:
    # Log the error
    print(f"Authentication error: {e.detail}")
    return RedirectResponse(url="/auth/error", status_code=HTTP_302_FOUND)

# Log out the current user   
@router.get('/logout')
async def logout(request: Request):
   auth.logout(request)
   return RedirectResponse(url="/", status_code=HTTP_302_FOUND)

# Authentication error page
@router.get("/error")
async def auth_error():
   return {"error": "Authentication failed. Please try again."}

This code defines routes that allow the user to log in, handle the OAuth callback, and log out of the application.

Set up the dashboard routes that will display the appropriate dashboards to the user based on their roles by replacing the existing route in the app/api/routes/dashboard_router.py file with the following:

# Main entry point, redirects based on user role
@router.get("/")
def index(request: Request):
   user = auth.get_current_user(request)
   if user:
    redirect_path = auth.get_user_redirect_path(request)
    return RedirectResponse(url=redirect_path, status_code=HTTP_302_FOUND)
   else:
    return RedirectResponse(url=auth.settings.LOGIN_PAGE_PATH, status_code=HTTP_302_FOUND)

# Routing endpoint for Gradio dashboards
@router.get("/gradio")
async def route_dashboard(request: Request):
   redirect_path = auth.get_user_redirect_path(request)
   return RedirectResponse(url=redirect_path, status_code=HTTP_302_FOUND)

Lastly, protect the Gradio dashboards by replacing the mount_admin_dashboard and mount_user_dashboard methods in the app/ui/gradio_mount.py file with the following:

# Mount the admin dashboard with authorization   
def mount_admin_dashboard(self):
   with gr.Blocks() as admin_dashboard_wrapper:
    admin_dashboard.main.render()

   self.app = gr.mount_gradio_app(
    self.app,
    admin_dashboard_wrapper,
    path=self.settings.ADMIN_DASHBOARD_PATH,
    auth_dependency=self.auth.authenticate_and_authorize
   )

# Mount the user dashboard with authorization
def mount_user_dashboard(self):
   with gr.Blocks() as user_dashboard_wrapper:
    user_dashboard.main.render()

   self.app = gr.mount_gradio_app(
    self.app,
    user_dashboard_wrapper,
    path=self.settings.USER_DASHBOARD_PATH,
    auth_dependency=self.auth.authenticate_and_authorize
   )

This code adds the auth_dependency parameter before mounting these apps, which runs before any Gradio-related route in your FastAPI app. This ensures that proper authentication and authorization checks are performed before displaying the dashboards.

You can now log in to the application using either magic links or social login.

Implementing SSO with OIDC using Descope

OIDC is an identity layer built on top of the OAuth 2.0 framework. It allows applications to authenticate users securely by delegating authentication to a trusted IdP, such as Okta. OIDC simplifies SSO by enabling users to log in once and access multiple applications without reentering credentials.

To implement SSO, you can configure Okta as the IdP and Descope as the authentication service. Start by launching your Okta admin dashboard and navigating to Applications > Applications > Browse App Catalog:

On the Browse App Catalog page, search for descope, and select Descope from the search results:

Select + Add Integration from the Descope app details page:

On the General Settings tab, leave everything as is and click Next:

On the Sign-On options tab, select OpenID Connect as the sign-on method:

Scroll down to the Advanced Sign-on Settings section, and in the Callback URL field, provide the value https://api.descope.com/v1/oauth/callback. This defines the URL where the user will be redirected after getting successfully authenticated by Okta. Save the changes by clicking Done at the bottom of the page:

You also need to assign users to the Descope app you just configured. This will ensure that only authorized users can authenticate via the app. To do this, go to the app’s details page and the Assignments tab and select Assign > Assign to Groups:

On the Assign Descope to Groups page, select the Assign button beside the Everyone group to allow all users in your organization to authenticate via the app, and select Done to save the changes.

Select the Sign On tab and take note of your OIDC client ID and secret:

Go to the Descope console to create a tenant that you will use with the Descope app you just configured in Okta. On your Descope console, navigate to Tenants > + Tenant, provide the tenant details on the Create Tenant form, and select Create:

Open the details page of the Tenant you just created, add your email domain under the Tenant Settings > Details section in the Email domain field, and save the changes:

Select Authentication Methods > SSO from the tenant details page sidebar, and under Authentication Protocol, select OIDC:

Under Tenant Details > SSO Domains, provide your email domain. This will help to determine which SSO configuration to load once a user chooses to authenticate using SSO:

Scroll down to the SSO configuration > Account Settings section and provide the required values as follows:

Provider Name: Okta
Client ID: The Client ID you obtained from the Okta dashboard
Client Secret: The client secret you obtained from the Okta dashboard
Scope: openid profile email
Grant Type: Authorization code

To obtain the values needed for the SSO configuration > Connection Settings section, you’ll need the OAuth endpoints from the Okta “well-known” configuration. Navigate to https://<YOUR-OKTA-INSTANCE>.okta.com/.well-known/openid-configuration on your browser, and take note of the issuer and authorization, token, user info, and JWKs endpoints.

Make sure to replace <YOUR-OKTA-INSTANCE> with the correct value, which is your organization’s Okta instance ID.

Head back to the Descope console, provide these values in the respective inputs under SSO configuration > Connection Settings, and save the changes.

SSO with Okta as the IdP is now fully configured.

Demonstrating the application

To run the application and confirm that everything is working as expected, use the command fastapi dev app/main.py and navigate to http://localhost:8000 on your browser. You will be redirected to the login page:

Click the Login button, and you’ll be redirected to Descope’s sign-in page, which is powered by the flow you configured earlier. You can sign in using any of the available methods:

After successful authentication, you’ll be redirected to the user dashboard. This is because you don’t have the appropriate roles to access the admin dashboard:

If you manually tried to navigate to http://localhost:8000/gradio/admin, you will get an error informing you that you’re not authenticated:

To check if a user with the appropriate role can access the admin dashboard, open the users’ page on the Descope console, edit your user to assign them the Tenant Admin role, and save the changes:

Now, go back to the app, log out, and log in again. You should be redirected to the admin dashboard:

Conclusion

In this guide, you learned how to integrate Descope as an OAuth provider for your Gradio application using OIDC. You also explored how to implement SSO with Okta as the identity provider and Descope as the authentication service. Additionally, you implemented role-based access control to protect Gradio app routes.

Descope is a drag-and-drop customer authentication and identity management platform. Our no- or low-code CIAM solution helps hundreds of organizations easily create and customize their entire user journey using visual workflows—from authentication and authorization to MFA and federated SSO. Customers such as GoFundMe, Navan, You.com, and Branch use Descope to reduce user friction, prevent account takeover, and get a unified view of their customer journey.

To learn more, join our dev community, AuthTown, and explore the Descope documentation.