DEV Community: Mrunank Pawar

Adding Authentication Middleware With Descope

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

This blog was originally published on Descope.

Looking to implement authentication middleware in your app? Most modern frameworks support middleware functions that let you intercept user requests, verify tokens, and control access—all in a centralized way.

In this blog, we'll walk through how authentication middleware works and how to implement it effectively using code examples in Node.js and Python. Once you understand the basics, we'll show how Descope's tools can streamline the process with out-of-the-box support for token validation, role checks, and more.

What is authentication middleware in web apps

In the context of web development, authentication middleware is a function that intercepts incoming requests and runs logic before or after those requests reach your application's core handlers. Middleware gives you a centralized way to manage access control, freeing up developer time to focus on business logic instead of duplicating auth checks across routes.

Most modern frontend and backend frameworks support this concept. You typically register a function—similar to a callback—that's triggered with every request. This can happen before the request reaches a controller or after the response is generated.

Within this middleware function, you can inspect request headers (like Authorization) and validate session tokens or permissions before allowing access to protected routes.

Example: Authentication middleware in Node.js

Let's look at how to build simple authentication middleware using Express in a Node.js app. This middleware intercepts requests, checks for an authorization header, and validates the session token before passing the request to the next handler.

var express = require('express')
var app = express()

var validateJwt = function(token) {
  // validation logic
  return true;
}

var authMiddleware = function (req, res, next) {
  req.isValidSession = validateJwt(req.headers.authorization)
  next()
}

app.use(authMiddleware)

app.get('/', function (req, res) {
  var responseText = 'Hello World!<br>'
  responseText += '<small>Session Valid:' + req.isValidSession + '</small>'
  res.send(responseText)
})

app.listen(3000)

In this example, the authMiddleware function runs on every request. It extracts the token from the Authorization header, runs a validation check, and attaches the result (isValidSession) to the request object. This setup gives you a lightweight way to apply authentication logic across all routes in your Express app.

Adding Descope authentication to Node.js middleware

Now that we understand how middleware works, we can use it to implement robust authorization and authentication middleware by validating user sessions on every request.

Descope makes this easier by providing SDKs that handle session and token validation. Instead of repeating auth logic across your app, you can centralize it in a single middleware function. That way, each incoming request is automatically checked for a valid access token or refresh token before hitting protected routes.

Here's how to build authentication middleware using the Descope Node.js SDK:

authentication.js

import DescopeClient from '@descope/node-sdk';

export class DescopeMiddleware {
  constructor(projectId) {
    this.descopeClient = DescopeClient({ projectId: projectId});
  }

  validate(token) {
    try {
      const authInfo = await descopeSdk.validateSession(sessionToken);
      console.log("Successfully validated user session:");
      console.log(authInfo);
    } catch (error) {
      console.log("Could not validate user session " + error);
    }
  }
}

app.js

import express from 'express';
import DescopeMiddleware from './authentication.js';

const app = express();
const authMiddleware = new DescopeMiddleware('__PROJECT_ID__');

app.use(authMiddleware.validate());

app.get('/', (req, res) => {
  res.send('main');
});

app.listen(3000, () => {
  console.log("Express Running port 3000")
});

This pattern helps you manage authentication in one place. It also improves maintainability by offloading session validation to Descope's SDK, allowing you to focus on application logic.

Using Descope decorators in Python

Python decorators are a powerful way to wrap additional behavior around existing functions, making them especially useful for building authentication middleware in Python web frameworks.

A decorator takes a function as input, extends or modifies its behavior, and returns a new function. This allows you to centralize logic, such as logging, validation, or—in our case—authentication, without cluttering every route with repeated code.

Here's a basic example of how decorators work:

def my_decorator(func):
    def wrapper():
        print("Something is happening before the function is called.")
        func()
        print("Something is happening after the function is called.")
    return wrapper

@my_decorator
def say_hello():
    print("Hello!")

say_hello()

To use a decorator, you simply annotate a function with @decorator_name. When you call that function, Python actually runs the wrapper logic defined inside the decorator. In this case, calling say_hello() produces the following output:

> Something is happening before the function is called.
> Hello!
> Something is happening after the function is called.

This structure is ideal for building authentication middleware in frameworks like Flask, FastAPI, or Django, where decorators can be applied directly to route functions to enforce login or permission checks.

Example: Descope Python decorator

You could write your own authentication middleware using decorators in Flask, FastAPI, or Django. But to save time, Descope provides prebuilt decorators that handle session validation, role enforcement, and other identity checks out of the box.

Here's an example of using Descope's @descope_validate_auth decorator to protect a route that requires authentication:

# This needs authentication
@APP.route("/private")
@descope_validate_auth(
    descope_client
)  # Can add permissions=["Perm 1"], roles=["Role 1"], tenant="t1" conditions
def private():
    return Response("<h1>Restricted page, authentication needed.</h1>")

This decorator automatically checks the user's JWT. If the token doesn't meet the conditions—such as having the correct roles or permissions—Descope will return a 401 Unauthorized response without running the route handler.

Descope also provides other decorators that extend the behavior of your routes. For example, the @descope_full_login decorator can trigger a Descope Flow:

@APP.route("/login", methods=["GET"])
@descope_full_login(
    project_id=PROJECT_ID,
    flow_id="sign-up-or-in",
    success_redirect_url="http://dev.localhost:9010/private",
)
def login():
    # Nothing to do! this is the MAGIC!
    pass

Need to handle logout? The @descope_logout decorator clears the user's session:

@APP.route("/logout")
@descope_logout(descope_client)
def logout():
    return Response("<h1>Goodbye, logged out.</h1>")

With just a few lines of code, you can use decorators to handle user authentication and session flow without repeating logic across your app.

Authentication middleware made simpler with Descope

Authentication middleware lets you centralize and automate how your app handles access control. By intercepting requests and validating tokens before they hit protected routes, middleware simplifies security and improves the user experience.

Descope gives you tools to build and manage this layer more efficiently. Whether you prefer writing your own middleware or using prebuilt decorators, you can plug in Descope's SDKs and flows to streamline session validation, role enforcement, and login logic.

Want to add authentication to your app without reinventing the wheel? Sign up for a Free Forever Descope account to get started. If you have questions or want to learn more about authentication best practices, book time with our auth experts.

Add Authentication and SSO to Your Shiny App

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

This blog was originally published on Descope.

Shiny lets you easily build web apps for data science using R and Python without the need for any web development experience. You can deploy these applications on your own web server or use Posit Connect to deploy them directly from your IDE.

Although deploying the applications is straightforward, it's also vital to set up proper access control for these applications to ensure that only authenticated users can view and interact with the data. Integrating single sign-on (SSO) with Shiny apps can provide a seamless authentication experience for the users. As these apps are often used by different business or enterprise users who might need to log in with their own identity provider (IdP), SSO allows them to use their existing credentials to log in.

Descope offers a no-code Customer Identity Platform (CIAM) that lets you easily define a customized workflow for sign-up, login, multi-factor authentication (MFA), SSO, and Security Assertion Markup Language (SAML).

In this tutorial, you'll learn how to implement authentication and SSO in a Shiny app.

Prerequisites

Before starting, you need to do the following:

Install RStudio on your development machine.
Install Posit Connect locally and configure its license. This tutorial uses an on-prem installation of Posit Connect on AWS, but alternatively, you can sign up for Posit Connect Cloud and use it to follow along.
Sign up for a free Descope account.

Set up Descope

Before you can integrate Descope authentication into your Shiny application, you need to define an authentication flow using the Descope portal.

Sign up for a free Descope account if you don't already have one, and follow the Getting Started wizard to create a new flow. In the wizard, first, choose Consumers as the target audience for your app:

Next, choose the authentication methods you want to use. In this tutorial, you'll use Magic Link and SSO as the authentication method. You can change these settings in the future if you like:

Skip the next step that prompts you to choose an MFA method by clicking Go ahead without MFA. In the next step, review the selected settings and click Next to generate the authentication flow:

Create a Shiny app

In this tutorial, you'll create a personal finance application using Shiny and add Descope authentication. The Shiny app will let you upload a CSV file containing month-wise expense data, view a bar chart with monthly expense trends, and also analyze category-wise expenses.

Since the tutorial focuses on adding authentication, you can clone the starter code with the personal finance Shiny app. In the terminal, navigate to the project directory and check out the starter branch.

cd personal-finance-shiny
git checkout starter

Open the application using RStudio and attempt to run the starter app. When you run it for the first time, it will prompt you to install the required packages. After you install the packages and rerun the app, you'll notice that you're directly taken to the dashboard page without authentication:

Next, click on the Publish button in RStudio to deploy the app on Posit Connect.

Before you can publish the Shiny app, you need to connect your Posit Connect account by clicking Add new account and choosing Posit Connect. Enter the Posit Connect server URL and click Next to connect the account.

You'll be redirected to the web browser to confirm the linking between RStudio and Posit Connect. Click Connect to link the account.

After confirming the connection in the browser, navigate back to RStudio and click Connect Account to verify the account.

Finally, select the connected account, provide a title for the app, and click Publish to deploy the application.

The dashboard of the app has the following components:

The left section lets you upload a CSV file containing personal expense data. The GitHub repo contains a sample CSV that you could use for testing.
When you upload the CSV file, the right section lets you view and analyze the category-wise expenses based on the uploaded data.

Implement vanilla authentication with Descope

You've deployed the app to Posit Connect and can now add authentication methods to access it using Descope. In this section, you'll add auth using magic links and email OTP for simplicity. You can configure and use other authentication methods too but we will focus on magic links and OTP for this tutorial.

Descope offers a WebJS component to integrate its auth flows with HTML-based web apps. You can easily integrate the WebJS component with your Shiny app by adding a custom JavaScript widget.

In your R project, create a www/descope-auth.js file, add the following content to create a container for the Descope element, and set success and failure listeners:

// www/descope-auth.js
Shiny.addCustomMessageHandler('initDescopeAuth', function (config) {
  const wcElement = document.createElement('descope-wc');
  wcElement.setAttribute('project-id', config.projectId);
  wcElement.setAttribute('flow-id', config.flowId);
  wcElement.setAttribute('theme', config.theme);

  wcElement.addEventListener('success', function (e) {
    const user = e.detail.user;
    Shiny.setInputValue(config.successInput, user);
  });

  wcElement.addEventListener('error', function (err) {
    console.error('Authentication error:', err);
    Shiny.setInputValue(config.errorInput, err);
  });

  const container = document.getElementById(config.containerId);
  if (container) {
    container.innerHTML = ''; // Clear any previous instances
    container.appendChild(wcElement);
  }
});

Next, you need to update the UI definition to include the @descope/web-component and descope-auth.js JS scripts. Update the app.R file by replacing it with the following code snippet:

ui <- fluidPage(
  useShinyjs(), # For dynamic UI control
  tags$head(
    tags$script(src = "https://unpkg.com/@descope/web-component@3.32.0/dist/index.js"),
    tags$script(src = "descope-auth.js") # Include custom JavaScript
  ),
  titlePanel("Personal Finance Dashboard with Descope Auth"),

  # Descope Authentication UI
  div(id = "authContainer"),

  hidden(
    div(
      id = "appContent",
      sidebarLayout(
        sidebarPanel(
          fileInput("file", "Upload Expense Data (CSV)", accept = ".csv"),
          selectInput("category", "Select Category:", choices = NULL),
          actionButton("analyze", "Analyze")
        ),
        mainPanel(
          tabsetPanel(
            tabPanel("Overview", plotOutput("expenseTrend"), tableOutput("summaryTable")),
            tabPanel("Category Analysis", plotOutput("categoryTrend"), tableOutput("categoryTable"))
          )
        )
      )
    )
  )
)

Finally, you need to update the server definition to initialize the Descope web component and implement success and failure callbacks. Add the following code snippet at the start of the server section:

server <- function(input, output, session) {
  # Initialize Descope Auth
  session$sendCustomMessage("initDescopeAuth", list(
    projectId = "<YOUR_DESCOPE_PROJECT_ID>",
    flowId = "sign-up-or-in",
    theme = "light",
    containerId = "authContainer",
    successInput = "user_authenticated",
    errorInput = "auth_error"
  ))

  observeEvent(input$user_authenticated, {
    if (!is.null(input$user_authenticated)) {
      showNotification("Login successful!", type = "message")
      show("appContent")
    }
  })

  observeEvent(input$auth_error, {
    if (!is.null(input$auth_error)) {
      showNotification("Authentication failed. Please try again.", type = "error")
    }
  })
  ...
  # existing server definition
}

Replace YOUR_DESCOPE_PROJECT_ID with your Descope project ID, save the changes, and republish the app to Posit Connect using RStudio.

Test authentication using magic link

When a user clicks the magic link received in their email for authentication, Descope will validate the auth and redirect the user back to the Shiny application. For redirection to work, you need to configure the auth redirect URL in Descope. Head over to Magic link under Authentication Methods and set the Redirect URL to the published URL of your Shiny app.

To test the authentication, open the published content under the Content tab on Posit Connect.

When you run the app, you'll be redirected to the Descope auth screen. You can test the integration by entering your email ID on this screen and clicking the Continue button to log in with a magic link. You'll receive an email with a login link, and upon clicking it, you'll be redirected to the dashboard page of your Shiny app.

Create a new Descope tenant

After integrating vanilla authentication, the next step is to add SSO authentication using Descope. To do this, you first need to create a Tenant. Tenants represent organizations that use your application and make it easier to group and manage users, permissions, and authentication flows within the application. In this tutorial, you'll create a tenant for an example organization and use it to configure the SSO flow.

Navigate to Tenants and click the + Tenant button to create a new tenant.

Implement SSO with OIDC using Descope

OpenID Connect (OIDC) is an extension of the OAuth 2.0 authorization protocol that provides a standardized way for applications to request and receive identity information about users. Instead of managing user credentials for each application, OIDC SSO lets you delegate the authentication mechanism to a single trusted IdP, reducing the maintenance overhead. Once you log in, the IdP returns standardized JSON web tokens (JWTs) on login-containing information about the user's identity. In this section, you'll learn how to set up Descope as an OIDC IdP with Posit Connect.

Create a Descope OIDC application in a separate project

The Descope OIDC application acts as a federated IdP for the users. Based on your needs, Descope can act as a Service Provider (SP) or an IdP. An SP is an entity that initiates an authentication request to an IdP, which verifies the user's identity. After authentication, the SP processes the response from the IdP to determine whether the user should be granted access to the application. In the previous section, you configured the Descope project as an SP entity for auth and SSO.

You'll now create an OIDC application within Descope to turn it into an IdP, and subsequently, you'll also integrate it with your authentication flow. Since you're using Descope for both SP and IdP, to avoid cyclic dependency, both these entities should be configured in separate Descope projects.

First, use the Descope portal to create a new project to host the OIDC application. This tutorial sets the project name as descope-shiny-auth-sso.

You also need to create an OIDC application under the newly created project. Navigate to Applications and click the + Application button to register Generic OIDC Application.

Click Create to create the OIDC application and note the Descope OIDC endpoint configuration, as you'll need it while configuring the SSO tenant in the original project.

To configure OAuth with Posit Connect, you'll also need to create a new client secret. Navigate to the Access Keys page and click +Access key to create a new access key.

Configure Descope tenant to use OIDC SSO

To integrate the OIDC application with the authentication flow, you need to configure SSO under the example.com tenant you created under the original Descope SP project. A tenant lets you configure an authentication method using an OIDC or SAML application. This section discusses how to configure SSO using an OIDC application, and in a later section, you'll learn how to configure SSO using SAML.

Switch back to the Descope SP project and navigate to Tenants, and select the example.com tenant you created earlier. Choose Authentication Methods and select OIDC as the SSO authentication protocol. Make the following changes to configure SSO:

Under Tenant Details, add example.com to the SSO domains.
Update the SSO configuration by adding the following values:
- Provider name: Add a value for the provider. For example, the tutorial uses Descope as the provider name.
- Client ID: Use the Descope project ID for the descope-shiny-auth-sso project.
- Client Secret: Use the access key that you created above.
- Scopes: It sets the permissions for the access level that will be granted to the authenticated user. Add openid, profile, and email as the scopes.
- Issuer: Use the Issuer value from the OIDC application you created in the previous step.
- Authorization Endpoint: Use the Authorization URL value from the OIDC application.
- Token Endpoint: Use the Access Token URL value from the OIDC application.
- User Info Endpoint: Use the Access Token URL from the OIDC application by replacing /token with /userinfo.
Finally, Save the changes for them to take effect.

Configure SSO redirect URL

You also need to configure the Posit Connect application URL as an SSO redirect URL. Since the Shiny app is already configured to use Descope, it doesn't require any new changes. Grab the application URL, navigate to SSO under Authentication methods, and set it as the Redirect URL.

Note that the SSO redirect URL needs to be configured in the Descope SP project.

Test the OIDC SSO integration

Finally, to test the integration, open the application in the browser, enter your email ID, and click on Continue with SSO to initiate the SSO flow. Note that the email ID should use example.com for SSO to work since you didn't configure any other domains in Descope.

You'll be redirected to the IdP login screen, which, in this case, is hosted by the descope-shiny-auth-sso Descope project. You can verify this by comparing the project ID in the address bar with the Descope project ID.

For testing, complete the login using one of the social login options or the magic link, and upon authentication, you'll be redirected back to the Shiny dashboard.

Implement SAML SSO with Descope

SAML SSO is an XML-based open authentication standard that lets users log in to multiple web applications using a single set of credentials. SAML is a mature identity federation standard and is widely supported by legacy or internal enterprise applications. It serves a similar purpose to OIDC, but instead of JSON, it uses XML during authentication or authorization requests between the IdP and the SPs.

In this section, you'll learn how to configure SAML SSO with Descope using a mock SAML application and configuring the tenant to use SAML SSO.

Configure mock SAML tenant for testing

As you learned in the OIDC SSO section, Descope can act as both SP and IdP as needed, but this tutorial uses Descope as an SP and Mock SAML as an IdP. Mock SAML is a SAML 2.0 IdP that can test SAML SSO integrations quickly. If you don't have a SAML SP set up, you can use this tool to test your Descope SAML integration.

Navigate to Tenants and select the example.com tenant you created earlier. Choose Authentication Methods and change the SSO authentication protocol from OIDC to SAML. Make the following changes to configure SAML SSO:

Under Tenant Details, add example.com to the SSO domains.
Update the SSO configuration, select the Retrieve the connection details dynamically option, and set the Metadata URL for IdP to the following:

https://mocksaml.com/api/saml/metadata

Note: If you have a SAML SP setup, you can set the Descope Metadata (URL) of the SAML application instead of a Mock SAML URL.

Test the SAML SSO integration

To test the integration, open the application in the browser, enter your email ID, and click on Continue with SSO to initiate the SSO flow. Note that the email ID should use example.com for SSO to work since you didn't configure any other domains in Descope. If you used a mock URL, you'll be redirected to a MockSAML login page where you can confirm your email ID and click Sign in.

Note: If you configured a Descope SAML application with SP details, Descope will directly handle the authentication.

After logging in, you'll be redirected to the dashboard page.

Access users from Shiny

So you've now added authentication to the Shiny app using OIDC and SAML, but the Shiny application doesn't indicate that the user is logged in. This section discusses how to access the logged-in user metadata and display a welcome message in the UI.

You'll add a UI element to the sidebar and update the server definition to set the welcome message when the user is authenticated. First, add a welcomeText element to the sidebar by updating the sidebarPanel to the following:

sidebarPanel(
  # Add a welcome text element
  h3(textOutput("welcomeText")),
  br(),

  # Existing inputs
  fileInput("file", "Upload Expense Data (CSV)", accept = ".csv"),
  selectInput("category", "Select Category:", choices = NULL),
  actionButton("analyze", "Analyze"),
)

Update the user_authenticated observer under the server definition to set the welcome message:

observeEvent(input$user_authenticated, {
  req(input$user_authenticated)

  user_info <- input$user_authenticated

  # use "name", else fallback to "email", else "User"
  user_name <- user_info$name
  if (is.null(user_name)) user_name <- user_info$email
  if (is.null(user_name)) user_name <- "User"

  output$welcomeText <- renderText({
    paste("Welcome,", user_name)
  })

  showNotification("Login successful!", type = "message")
  show("appContent")
})

Notice that the above code snippet tries to retrieve the user's name from the user_info object and falls back to email if name is not present.

Save and republish the changes to test them. Once you log in to the dashboard, a welcome message will be displayed.

Log out a user

Your users also need logout functionality to enable them to end their sessions. To implement logout, first, add a logout button to the sidebar by updating the sidebarPanel as follows:

sidebarPanel(
  h3(textOutput("welcomeText")),
  br(),

  # Existing inputs
  fileInput("file", "Upload Expense Data (CSV)", accept = ".csv"),
  selectInput("category", "Select Category:", choices = NULL),
  actionButton("analyze", "Analyze"),

  # Logout button
  actionButton("logout", "Logout", icon = icon("sign-out-alt"))
)

Next, add a descopeLogout message handler in the descope-auth.js file that will be invoked when the logout button is clicked:

Shiny.addCustomMessageHandler('descopeLogout', function () {
  const wcElement = document.querySelector('descope-wc');
  if (wcElement) {
    wcElement.logout();
  }
});

Finally, add a logout observer under the server definition to invoke the descopeLogout and initDescopeAuth message handlers.

observeEvent(input$logout, {
  hide("appContent")  # Hide main content
  session$sendCustomMessage("descopeLogout", list())

  session$sendCustomMessage("initDescopeAuth", list(
    projectId = "P2pBl7sYVGg1RWtv4jC7zfO9TnUN",
    flowId = "sign-up-or-in",
    theme = "light",
    containerId = "authContainer",
    successInput = "user_authenticated",
    errorInput = "auth_error"
  ))
})

Save and republish the changes to test them. Once you log in to the dashboard, you'll notice a Logout button being displayed next to the Analyze button.

When you click the Logout button, you'll be logged out of the application and redirected to the Descope login page.

Make Shiny authentication simpler with Descope

Shiny makes it easier for data engineers and scientists to share their work with others as web applications without any HTML or JavaScript experience. Posit Connect is a publishing platform that lets you deploy Shiny apps directly from RStudio with a click of a button, eliminating the need to provision and maintain a web server.

In this article, you learned how to implement authentication and authorization in a Shiny app using Descope. You can find this tutorial's complete source code on GitHub.

Descope is a drag-and-drop customer authentication and identity management platform. Our low- or no-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 like Navan, GoFundMe, You.com, and Branch Insurance use Descope to reduce user friction, prevent account takeover, and get a unified view of their customer journey. To learn more, book a demo with our auth experts or join our dev community, AuthTown.

Add Authentication and SSO to Your Flet App

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

This blog was originally published on Descope.

Creating cross-platform applications has become much easier with frameworks like Flet. Flet allows developers to build modern web, desktop, and mobile apps using Python. Its simplicity and flexibility help developers focus on creating great user experiences without having to worry about platform-specific complexities.

However, as your application grows, so does the need to secure it. Adding secure authentication to your application helps to protect sensitive data by ensuring that only authorized users can access it. Descope is a modern authentication and user management platform that simplifies the integration of secure authentication features into your application. By providing out-of-the-box support for OAuth 2.0 and OpenID Connect (OIDC), Descope offers a reliable solution for implementing authentication in your Flet app.

In this guide, you will learn how to integrate Descope authentication and single sign-on (SSO) into a Flet application. You'll learn how to add basic authentication to your Flet app using Descope magic links and social login. You'll also configure Descope to use Okta as the identity provider (IdP), enabling SSO for your Flet app.

Why is adding SSO important for these types of apps?

SSO is essential for B2B applications that serve multiple companies. Each company may already use its own IdP—such as Okta, Google, or Azure—for authentication. By adding SSO, your application allows users to log in with existing credentials, which eliminates the need to create and manage separate accounts. This simplifies the onboarding process and enhances security by relying on trusted authentication providers.

SSO also improves the user experience by providing seamless access to different services within an organization. It allows employees to use their company credentials to log in, which reduces password fatigue and IT support overhead.

For businesses handling sensitive data, SSO ensures centralized access control, which makes it easier to enforce security policies while maintaining a smooth login process.

Prerequisites

To complete 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 Flet application

This tutorial uses a prebuilt starter template so you can focus on implementing authentication. To clone the starter template to your local machine, execute the following command:

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

cd into the project folder, set up a virtual environment, activate it, and install the project dependencies:

cd descope-flet-auth-sso

python3 -m venv venv

source venv/bin/activate

pip install -r requirements.txt

Here's an overview of the most important files in this project:

main.py: Sets up a simple Flet app with two views: a main view and a profile view. The MyApp class initializes the app, sets the page theme to light, and handles route changes and view pops. When the route changes (for example, when navigating to /profile), it updates the view accordingly, either showing the profile or the main view. It uses the AuthManager class to handle user authentication (login/logout). The route_handler method switches views based on the current route, and view_pop allows navigating backward through views. Finally, the run method starts the app with the main view.
auth/auth_helpers.py: Defines an AuthManager class that manages the auth-related functions. The handle_login method navigates the user to the /profile route while the handle_logout method navigates the user to the / route.
views/main_view.py: Displays a message with a login button that calls the handle_login method when clicked.
views/profile_view.py: Displays a message with a logout button that calls the handle_logout method when clicked.

You can run the application using the following command:

flet run -w --port 8550

This command opens the web version of the app. To view it, navigate to http://localhost:8550 on your browser, and you should see the demo application homepage with a Login button:

Click the Login button and you should be navigated to the profile page:

Right now, the profile page is accessible to anyone, which is not ideal. In the next section, you'll implement authentication to restrict access to authorized users.

Setting up Descope

To implement authentication in your Flet app, you first need to create a project and design a flow on your Descope console. To get started, launch your Descope console, click the project dropdown, and select + Project to create a new project:

On the Create project page, provide "descope-flet-auth-sso" as the project name and click Create to create the project:

The next step is to design a Descope flow. Flows define the authentication process. You're going to add support for three authentication methods: magic links, social login, and SSO. You need to design a flow that will support all the authentication methods.

Typically, you would need to design this flow from scratch, but to make it easy for you to follow along, this tutorial uses a pre-prepared flow, which is included in the starter template. You can find it in the project root folder in a file named sign-up-or-in.json. You just need to import this flow into the Descope console. To do this, navigate open the default sign-up-or-in flow in the flow editor by navigating to Flows > sign-up-or-in:

In the editor, select Import flow / Export flow > Import flow and upload the flow from your local machine:

The flow you imported presents three login methods on the welcome screen: magic link, SSO, and social login. If the user selects the magic link, an email is sent to the provided address. When the user clicks the link in the email, they are asked for additional details if they're a new user. If they're not new, the flow returns a JSON Web Token (JWT) and ends. For social login or SSO, the user is redirected to the appropriate provider. After successful authentication, they receive a JWT, and the flow ends.

Authentication with Descope

Now that you have implemented the authentication flow in the Descope console, you can go ahead and configure your Flet app to use Descope as an OAuth provider. Flet allows you to implement authentication with any identity provider that supports the OAuth 2.0 Authorization code flow. By default, Flet ships with a few built-in OAuth providers, such as Azure and Google, but it also allows you to configure a custom OAuth provider, like Descope.

To configure a custom OAuth provider, you need to configure the following in your Flet app:

Client ID: A public identifier for the application
Client secret: A secret that is only known to the application and the authorization server
Authorization endpoint: The endpoint that initializes the authorization flow
Token endpoint: The endpoint that exchanges an authorization code for access tokens
User endpoint: The endpoint that retrieves the authenticated user's information
Redirect URL: The URL where the user is redirected to after authentication
User ID function: A function that extracts the user ID from the returned user dictionary

To integrate Descope as the authentication provider for your Flet app, you first need to configure an OIDC app in the Descope dashboard to obtain the necessary endpoints required for the authorization code flow. To do this, navigate to Applications > OIDC default application on the Descope console:

Scroll down to the SP Configuration section and take note of the Client ID, Authorization URL, and Access Token URL. You will use these values in your Flet app.

For the user endpoint, you'll use https://api.descope.com/oauth2/v1/userinfo, which is discussed along with the other endpoints in the Descope documentation.

You also need to generate a client secret. You can do this by navigating to M2M > + Access Key. On the Generate Access Key form, provide the key name, select Generate Key, and copy the value of your key.

Now that you have these values, you can go back to your Flet app and start implementing authentication. First, create a new file named .env in the project root folder and add the following code:

OAUTH_CLIENT_ID="<YOUR-DESCOPE-CLIENT-ID>"
OAUTH_CLIENT_SECRET="<YOUR-DESCOPE-CLIENT-SECRET>"
OAUTH_AUTHORIZATION_ENDPOINT="https://api.descope.com/oauth2/v1/authorize"
OAUTH_TOKEN_ENDPOINT="https://api.descope.com/oauth2/v1/token"
OAUTH_USER_ENDPOINT="https://api.descope.com/oauth2/v1/userinfo"
OAUTH_REDIRECT_URI="http://localhost:8550/oauth_callback"
OAUTH_USER_ID_FIELD="sub"
OAUTH_SCOPES="openid profile email"

Some of the values have been prefilled for you as they will be the same for everyone. However, the client ID and client secret will be unique to you. Make sure you replace the placeholder values with the values you obtained from the Descope console.

You also need a utility file to extract the environment variables and make them available for use in different parts of the application. Create a new file named config.py in the project root folder and add the following code:

from dotenv import load_dotenv
import os

load_dotenv()

class Config:
    @staticmethod
    def get_env_var(name, default=None, required=True):
        value = os.getenv(name, default)
        if required and value is None:
            raise ValueError(f"Environment variable '{name}' is required but not set.")
        return value

    OAUTH_CLIENT_ID = get_env_var('OAUTH_CLIENT_ID')
    OAUTH_CLIENT_SECRET = get_env_var('OAUTH_CLIENT_SECRET')
    OAUTH_AUTHORIZATION_ENDPOINT = get_env_var('OAUTH_AUTHORIZATION_ENDPOINT')
    OAUTH_TOKEN_ENDPOINT = get_env_var('OAUTH_TOKEN_ENDPOINT')
    OAUTH_USER_ENDPOINT = get_env_var('OAUTH_USER_ENDPOINT')
    OAUTH_REDIRECT_URI = get_env_var('OAUTH_REDIRECT_URI')
    OAUTH_USER_ID_FIELD = get_env_var('OAUTH_USER_ID_FIELD')
    OAUTH_SCOPES = get_env_var('OAUTH_SCOPES')

This code loads environment variables from a .env file and defines a Config class with a method to retrieve them, raising an error if a required variable is missing. It then uses this method to set various OAuth-related settings as class attributes.

To define a custom OAuth provider, create a new file named auth_provider.py in the auth folder and add the code below:

from flet.auth import OAuthProvider as BaseOAuthProvider
from config import Config

class OAuthProvider(BaseOAuthProvider):
    def __init__(self):
        super().__init__(
            client_id=Config.OAUTH_CLIENT_ID,
            client_secret=Config.OAUTH_CLIENT_SECRET,
            authorization_endpoint=Config.OAUTH_AUTHORIZATION_ENDPOINT,
            token_endpoint=Config.OAUTH_TOKEN_ENDPOINT,
            user_endpoint=Config.OAUTH_USER_ENDPOINT,
            redirect_url=Config.OAUTH_REDIRECT_URI,
            user_id_fn=lambda u: u[Config.OAUTH_USER_ID_FIELD],
        )

This code defines an OAuthProvider class that inherits from the Flet OAuthProvider class and initializes it with OAuth configuration settings from the Config class.

Open the auth/auth_helpers.py file. Here, you will modify the methods to log in and log out the user instead of just navigating them. First, replace the import statements with the following:

from flet import Page, LoginEvent
from config import Config

Then, replace the handle_login method with the following to trigger the login process using the OAuth provider configured for the page:

def handle_login(self, e):
    self.page.login(self.page.oauth_provider)

Replace the handle_logout method with the following to log the user out by calling the logout function on the page:

def handle_logout(self, e):
    self.page.logout()

In the same class, add the following methods to configure methods that will be called when the user is successfully logged in or out:

def on_login(self, e: LoginEvent):
    if e.error:
        raise Exception(e.error)

    self.page.go('/profile')

def on_logout(self, e):
    self.page.go('/')

These methods handle login and logout events: on_login checks for errors during login and navigates to the /profile route if successful, while on_logout redirects the user to the home route (/).

Open the views/profile_view.py file and replace the get_view method with the following:

def get_view(self):
    return ft.View(
        route='/profile',
        vertical_alignment=ft.MainAxisAlignment.CENTER,
        horizontal_alignment=ft.CrossAxisAlignment.CENTER,
        controls=[
            ft.Column(
                alignment=ft.MainAxisAlignment.CENTER,
                horizontal_alignment=ft.CrossAxisAlignment.CENTER,
                controls=[
                    ft.CircleAvatar(
                        foreground_image_src=self.page.auth.user.get("picture", ""),
                        bgcolor=ft.Colors.GREY_400,
                        radius=40
                    ),
                    ft.Text(value=self.page.auth.user.get("name", "N/A"), size=20, weight=ft.FontWeight.BOLD),
                    ft.Text(value=self.page.auth.user.get("email", "N/A"), size=18),
                    ft.ElevatedButton(text="Logout", on_click=self.handle_logout),
                ],
            )
        ]
    )

This method returns a view for the profile page that displays the authenticated user's profile picture, name, and email in the center of the page, along with a Logout button.

Open the main.py file and add the following import statement:

from auth.auth_provider import OAuthProvider

Add the following line of code to the __init__ method just before self.auth_manager = AuthManager(page=self.page) to create an instance of the OAuth provider and attach it to the current page:

self.page.oauth_provider = OAuthProvider()

Register the event handler you created earlier to the page by adding the following code at the end of the __init__ method:

self.page.on_login = self.auth_manager.on_login
self.page.on_logout = self.auth_manager.on_logout

Finally, you need to protect the /profile page to make sure it cannot be accessed by unauthenticated users. To do this, in the route_handler method, replace the first block of the if statement with the following:

if self.page.route == '/profile':
    if(self.page.auth is None):
        return self.page.go(route='/')
    view = ProfileView(self.page, self.auth_manager.handle_logout)
    self.page.views.append(view.get_view())

This code checks if the current route is /profile; if the user isn't authenticated, it redirects them to the home page. Otherwise, it loads the ProfileView and appends it to the page.

At this point, you should be able to log in to the application using either magic links or social login. In the next section, you will implement SSO.

Implement SSO with OIDC using Descope

OIDC is a simple identity layer built on top of OAuth 2.0. It helps enable SSO by allowing users to authenticate through trusted IdPs, such as Azure or Okta. With Descope, you can easily integrate OIDC SSO into your app, letting users log in securely with their existing credentials, which streamlines access without the need for new accounts.

In this section, you'll implement SSO by configuring Okta as the IdP and Descope as the authentication service. To do this, open your Okta admin dashboard and navigate to Applications > Applications > Browse App Catalog:

On the Browse App Integration Catalog page, search for "descope" and select the Descope app:

On the app details page, select Add Integration:

On the Add Descope page under General Settings, leave the default settings and click Next:

On the Sign-On Options page, select OpenID Connect as the sign-on method, and under Advanced Sign-on Settings, in the Callback URL field, provide the value https://api.descope.com/v1/oauth/callback. This is where the user will be redirected after successful authentication by Okta.

Scroll down to the bottom of the page and click Done.

On the app details page, select the Sign On tab and take note of the client ID and secret.

You'll also need a tenant to use SSO. Back on your Descope console, navigate to Tenants > + Tenant. On the Create Tenant form, provide the tenant name and click Create:

Open the details page of the tenant you just created and under Tenant Settings. Make sure you add your email domain to the list of allowed domains and click Save:

Next, still on the tenant details page, select Authentication Methods > SSO > OIDC. Under Tenant Details > SSO Domains, make sure to provide your email domain. This domain is used 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

You also need to provide the required values for the SSO configuration > Connection Settings section. For this, you need to obtain OAuth endpoints from the Okta "well-known" configuration, which provides standardized metadata for OAuth and OIDC integrations. To obtain this, 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.

Go back to the Descope console and provide the values you just obtained from the Okta well-known endpoint in the respective inputs under SSO configuration > Connection Settings and save the changes.

To ensure that only authorized users can authenticate via the app and access your Flet application, you assign users to the Descope app you installed in your Okta console. To do this, open the app details page in Okta and select Assignments > Assign > Assign to Groups:

On the Assign Descope Groups page, select the Assign button beside the Everyone group to allow all users in your organization to log in via SSO and click Done to save the changes.

SSO with Okta as the IdP is now fully configured.

Adding a persistent login feature

Currently, the app does not save the access token obtained from Descope. So if a user logs in, leaves the app, and then returns, they will need to log in again. To improve the user experience, you can add a function that saves the access token to client storage.

However, you cannot store the token in client storage as plain text as this would make it vulnerable to malicious actors who could access and manipulate it. Instead, you need to encrypt the token using a secret key and save the encrypted value securely.

Open the .env file in the project root folder and add the following:

OAUTH_TOKEN_SECRET="cv3Gc9RG-9o8icwTBUEDb0HJC7M5A0b2FxT3WpWvg1I="
OAUTH_TOKEN_KEY="auth_token"

Values for these variables have been provided, but you can change them to any string.

OAUTH_TOKEN_SECRET will be used to encrypt the access token before saving it to the client storage, while OAUTH_TOKEN_KEY is the key under which the encrypted token will be saved in the client storage.

To load the environment variables you just created into the Flet application, open the config.py file and add the following attributes to the Config class:

OAUTH_TOKEN_SECRET = get_env_var('OAUTH_TOKEN_SECRET')
OAUTH_TOKEN_KEY = get_env_var('OAUTH_TOKEN_KEY')

Open the auth/auth_helpers.py file and add the following import statements:

from flet.security import encrypt, decrypt

encrypt and decrypt are utility methods provided by Flet for encrypting text data using a symmetric algorithm. This means that the same key is used for encryption and decryption.

Replace the on_login method with the following to modify the on_login method to encrypt and save the token to client storage once a user is successfully authenticated:

def on_login(self, e: LoginEvent):
    if e.error:
        raise Exception(e.error)

    # Save token in client storage
    token = self.page.auth.token.to_json()
    encrypted_token = encrypt(token, Config.OAUTH_TOKEN_SECRET)
    self.page.client_storage.set(Config.OAUTH_TOKEN_KEY, encrypted_token)

    self.page.go('/profile')

This code retrieves the access token, encrypts it using the secret key you set earlier, and stores the encrypted token in client storage. It then redirects the user to the profile page.

Replace the handle_login method with the following to modify the handle_login method to check if a valid token is stored in the client storage before redirecting the user to the sign-in page:

def handle_login(self, e):
    saved_token = None

    # Retrieve token from client storage
    encrypted_token = self.page.client_storage.get(Config.OAUTH_TOKEN_KEY)

    # Decrypt retrieved token
    if encrypted_token:
        saved_token = decrypt(encrypted_data=encrypted_token, secret_key=Config.OAUTH_TOKEN_SECRET)

    # Log in the user
    if e is not None or saved_token is not None:
        self.page.login(provider=self.page.oauth_provider, saved_token=saved_token, scope=Config.OAUTH_SCOPES.split())

This code retrieves the saved encrypted token from the client storage, decrypts it, and passes it to the self.page.login method. This way, if the token is valid, the application will obtain the user's info without prompting the user to reauthenticate.

Lastly, replace the handle_logout method with the following to modify the handle_logout method to make sure that it removes the token from storage when a user logs out:

def handle_logout(self, e):
    self.page.client_storage.remove(Config.OAUTH_TOKEN_KEY)
    self.page.logout()

Persistent login should now be working as expected.

Demonstrating the application

You can run the application to confirm that everything is working as expected.

Run the application using the command flet run -w --port 8550, navigate to http://localhost:8550 on your browser, and click the Login button. You should be redirected to the sign-in page:

Here, you can choose to sign in with any method, and after successful authentication, you will be redirected to the profile page, where your details are displayed:

You can stop the application and run it again. Then, on the home route, click the Login button. You will be redirected to the profile page without being prompted to sign in again.

You can access the full code on GitHub.

Conclusion

Implementing authentication and SSO into your Flet app using Descope is a straightforward process that significantly enhances your application's security and user experience. By integrating features like magic link authentication, social logins, and SSO with OIDC, you can offer your users seamless and secure access, whether they are individuals or part of an organization using their existing credentials.

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.

Add Authentication and SSO to Your Panel App

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

This blog was originally published on Descope.

Panel is an open source Python library for creating interactive data visualization applications. As these applications grow, secure authentication becomes essential to protect the data, ensure compliance with security standards, and deliver a seamless user experience. Descope, a no-/low-code customer identity and access management (CIAM) platform, simplifies authentication by offering ready-to-use solutions for secure login, single sign-on (SSO), and user access control. Its support for OpenID Connect (OIDC), a widely adopted standard for secure and scalable user authentication, makes it an excellent choice for securing Panel apps, allowing developers to focus on building core features while relying on a trusted platform for authentication.

In this tutorial, you'll learn how to integrate Descope into your Panel application by implementing secure user authentication, configuring access control, and providing a seamless SSO experience for your users. You will start by adding vanilla authentication with Descope via magic links, add support for social login, and lastly, implement SSO with Okta as the identity provider (IdP).

Why is adding SSO important for these types of apps?

SSO is often added to data visualization tools because these tools are typically designed for B2B use. Here are some of the advantages of integrating SSO into a data visualization tool:

Simplifying access for end users: B2B applications frequently cater to multiple companies with their own employees and systems. Each of these companies will have an IdP—such as Okta, Azure AD, or Google Workspace—which they use for secure access to tools and resources. Integrating SSO into your application allows users to sign in with their existing corporate accounts, which eliminates the need for another set of credentials.

Strengthening security and compliance: SSO ensures that authentication is handled through the organization's IdP, which is often configured with advanced security features like MFA and conditional access policies. This reduces the risk of unauthorized access and strengthens compliance with industry standards such as GDPR and HIPAA, which are crucial for data-driven applications.

Simplified management for developers: From a developer's perspective, SSO integration reduces the complexity of user account management. With SSO, developers can offload the responsibility of managing user credentials and access roles to the IdP, which not only saves time but also reduces the risk of mishandling sensitive user information.

Adding SSO to your application improves the user experience and future-proofs it to meet the needs of enterprise customers while maintaining high security standards.

Prerequisites

To follow along with this guide, you need to have 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 Panel app

For simplicity, this tutorial uses a prebuilt application that you add authentication to. To clone the application to your local machine, launch your terminal and execute the following command:

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

Create and activate a virtual environment for your application to run in:

cd descope-panel-auth-sso

python -m venv venv

source venv/bin/activate

Next, install all the dependencies using the command below:

pip install -r requirements.txt

The application is now set up. The two most important files in the application are admin.py and user.py. admin.py is used to set up an admin dashboard for a Panel application and will only be accessed by users with the appropriate roles after you have implemented auth and role-based access control. user.py sets up a Panel app that allows users to interact with a data set and view rolling averages and outliers for different variables. You can learn more about this application in the Panel docs.

Run the application using the following command:

panel serve admin.py user.py --dev

Launch your browser and navigate to http://localhost:5006/. You'll see that you have two Panel apps running:

At the moment, you can open any application. However, later on, you will implement authorization to ensure that the "Admin" application can only be accessed by users with the appropriate roles.

Setting up Descope

Here, you will create a project on your Descope console and implement an authentication flow to set up your application's authentication process. This flow will enable your users to authenticate using any of the three methods we discussed: magic links, social logins, and SSO.

To get started, launch your Descope console and select + Project from the project dropdown to create a new project:

In the Create project modal, provide descope-panel-auth-sso as the project name and click Create to create the project:

To create an authentication flow, select Flows > sign-up-or-in on the Descope console to open the default sign-up-or-in flow in the flow editor:

As mentioned earlier, you're going to customize this flow to support three different authentication methods: magic links, social logins, and SSO login. This tutorial uses an already-prepared flow that you just need to import.

The project you set up earlier contains a file named sign-up-or-in.json, which is where you'll find the flow logic. You can import it into the flow editor by selecting Import flow / Export flow > Import flow inside the editor and uploading the flow from your local machine:

The flow you just imported should now have all the authentication methods that you need:

Magic links and social login authentication methods are now fully configured. You will configure SSO later.

Adding authentication with Descope

In this section, you'll configure Descope as a generic OAuth provider for your Panel application.

Panel performs authentication through OAuth 2.0, a widely used protocol that delegates authentication to third-party providers, such as Google and GitHub. By default, Panel ships with support for various OAuth providers, but it also allows you to configure authentication via any Generic OAuth provider that has configurable endpoints, such as Descope.

To set up authentication with Descope, you need to configure specific settings. These can be passed through environment variables or via CLI arguments when you're running the application. In this guide, we will use environment variables for simplicity.

Here are the required environment variables:

PANEL_OAUTH_KEY: A public identifier for the application
PANEL_OAUTH_SECRET: A secret that is only known to the application and the authorization server
PANEL_OAUTH_AUTHORIZE_URL: The endpoint that initializes the authorization flow
PANEL_OAUTH_TOKEN_URL: The endpoint that exchanges an authorization code for access tokens
PANEL_OAUTH_USER_URL: The endpoint that retrieves the authenticated user's information
PANEL_COOKIE_SECRET: A random, unguessable string for encrypting cookies
PANEL_OAUTH_REDIRECT_URI: The URL where the user is redirected to after authentication
PANEL_OAUTH_ENCRYPTION: For encrypting user information and access tokens
PANEL_OAUTH_SCOPE: Defines the scope of permissions requested from the authorization server

You will obtain some values for these environment variables from the Descope console and generate others on the terminal.

Create a new file named .env in the project root folder and add the content below. You will assign values for each environment variable as you proceed.

PANEL_COOKIE_SECRET=
PANEL_OAUTH_REDIRECT_URI="http://localhost:5006"
PANEL_OAUTH_ENCRYPTION=
PANEL_OAUTH_SCOPE=
PANEL_OAUTH_KEY=
PANEL_OAUTH_SECRET=
PANEL_OAUTH_AUTHORIZE_URL=
PANEL_OAUTH_TOKEN_URL=
PANEL_OAUTH_USER_URL=

To integrate Descope as your authentication provider, you first need to configure an OIDC app in the Descope dashboard. This configuration provides the necessary endpoints and credentials for your Panel application. You could choose to create a new OIDC application for this integration, but in this example, you can simply use the default OIDC application that ships with Descope. Access the application by navigating to Applications > OIDC default application on the Descope console:

In the OIDC app's details page, scroll down to the SP Configuration section, take note of the Client ID, Authorization URL, and Access Token URL, and assign them to the PANEL_OAUTH_KEY, PANEL_OAUTH_AUTHORIZE_URL, and PANEL_OAUTH_TOKEN_URL environment variables in the .env file, respectively.

For the PANEL_OAUTH_USER_URL environment variable, assign the value https://api.descope.com/oauth2/v1/userinfo.

For the PANEL_OAUTH_SCOPE environment variable, provide the value openid email profile descope.claims descope.custom_claims. The openid email profile scopes request basic user information, while the descope.claims descope.custom_claims scopes request the user roles, permissions, tenants, and custom claims from the IdP. However, for the descope.claims descope.custom_claims scopes to be provided, you need to go back to your OIDC application and add them to the Supported Claims list under IdP Configuration:

Remember to save the changes.

To obtain the value for the PANEL_OAUTH_SECRET environment variable, create an access key by navigating to M2M > + Access Key on the Descope console. Name the key whatever you like and click Generate Key:

Copy the value of the generated key, and assign it to the PANEL_OAUTH_SECRET environment variable in the .env file.

Make sure your virtual environment is activated, and then execute the following command in your terminal to generate a value for the PANEL_COOKIE_SECRET environment variable:

panel secret

Lastly, activate the Python shell by executing the command python in your terminal, and execute the following code to generate a value for the PANEL_OAUTH_ENCRYPTION environment variable:

from cryptography.fernet import Fernet

key = Fernet.generate_key()
print(key.decode())

Now Descope is fully configured as a generic OAuth provider for Descope. At this point, you can run the application using the command panel serve admin.py user.py --oauth-provider=generic --dev and test if authentication is working as expected.

Keep in mind that only magic links and social login authentication methods should be working at this point. You will work on SSO in the next section.

Implement SSO with OAuth using Descope

OAuth 2.0 is an industry-standard protocol for authorization that enables applications to securely access user resources without requiring them to share their credentials. OAuth acts as a "middleman" that allows users to grant limited access to their information stored on an IdP to the Service Provider (SP), such as your application. When combined with OIDC, which is built on top of OAuth, this protocol also enables SSO, which allows users to log in once with their existing credentials and gain access to multiple applications or systems without having to log in again.

In this section, you'll configure Okta as the IdP and Descope as the OAuth service to integrate authentication and SSO into your Panel application.

To get started, go to your Okta admin dashboard and navigate to Applications > Applications > Browse App Catalog:

On the Browse App Integration Catalog page, search for "Descope" and select the Descope application:

Next, on the application details page, select + Add Integration:

On the Add Descope page, under General Settings, provide Descope Panel Auth and SSO as the Application label and click Next:

On the Sign-On Options page, select OpenID Connect as the sign-on method, and under Advanced Sign-on Settings, in the Callback URL field, provide the value https://api.descope.com/v1/oauth/callback. This is the URL the user will be redirected to after successful authentication by the IdP.

Scroll down to the bottom of the page and select Done.

On the app details page, select the Sign On tab and take note of your client ID and client secret:

Head back to the Descope console and select Tenants > + Tenant to create a new tenant. On the Create Tenant modal, provide Descope Panel Auth and SSO as the tenant name and click Create:

Open the tenant details page, and under Tenant Settings, add your email domain to the list of allowed domains and save the changes:

Still on the tenant details page, navigate to Authentication Methods > SSO and select OIDC. Under Tenant Details, add your email domain, which will help to determine the SSO configuration to load when a user chooses to authenticate with 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

You also need to provide the values for the SSO configuration > Connection Settings section. For these, you'll need to obtain OAuth endpoints from the Okta "well-known" configuration. To obtain this, 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, input these values in their respective endpoints under SSO configuration > Connection Settings, and save the changes.

Under SSO Mapping > User Attribute Mapping, you can choose to configure how attributes from Okta will be mapped to Descope, but we will not be doing so in this guide. The default mapping is sufficient for this example. For more information on how to add custom claims to your Okta OIDC tokens, check out the official docs.

You also need to assign users to the Descope app in Okta to grant them access. This step ensures that only authorized users can authenticate via the app and access your Panel application. To do this, open the app details page in Okta and select the Assignments > Assign > Assign to Groups:

On the Assign Descope Panel Auth and SSO to Groups page, select the Assign button beside the Everyone group to allow all users in your organization to log in via SSO and click Done to save the changes.

Add authorization

Authorization allows your app to determine what actions an authenticated user can perform and the data they can access. For example, in your Panel application, administrators might have access to advanced analytics and management tools, while regular users can only view specific dashboards.

At the moment, any user can access any dashboard in your application. Let's limit what dashboard a user can access based on their roles.

To do this, create a new file named main.py in the root project folder and add the following code, which retrieves user roles and redirects them to the appropriate dashboard:

from dotenv import load_dotenv
import os
import panel as pn

# Load env variables
load_dotenv()

# Enable Panel extension
pn.extension(sizing_mode="stretch_width")

# Define the authorization callback
def authorize(user_info):
    """
    Authorization callback to redirect users based on roles.
    """
    # Extract user roles from the user_info dict
    roles = user_info.get('tenants', {}).get(os.getenv('DESCOPE_TENANT_ID'), {}).get('roles', [])

    if "Tenant Admin" in roles:
        return "/admin"
    else:
        return "/user"

# Assign the authorization callback
pn.config.authorize_callback = authorize

The authorize function checks the user's roles from the user_info dictionary, which includes details about their roles in a specified tenant (retrieved from an environment variable). Depending on whether the user has the Tenant Admin role, they are redirected to either the admin dashboard (/admin) or the user dashboard (/user).

You'll also need to protect the admin dashboard so that users don't try to manually navigate to the /admin endpoint on their browser. To do this, Open the admin.py file and replace the existing code with the following:

from dotenv import load_dotenv
import os
import panel as pn

load_dotenv()

# Enable Panel extension
pn.extension(sizing_mode="stretch_width")

# Extract roles and permissions
tenant_data = pn.state.user_info.get('tenants', {}).get(os.getenv('DESCOPE_TENANT_ID'), {})
roles = tenant_data.get('roles', [])
permissions = tenant_data.get('permissions', [])

# Admin dashboard content
admin_content = f"""
# You're an admin. You have access to more data and functionality.

#### Your Roles:
<ul>
    {"".join(f"<li>{role}</li>" for role in roles) if roles else "<li>No roles assigned</li>"}
</ul>

#### Your Permissions:
<ul>
    {"".join(f"<li>{permission}</li>" for permission in permissions) if permissions else "<li>No permissions assigned</li>"}
</ul>
"""

# Authorization callback for the admin dashboard
def authorize_admin(user_info):

    if "Tenant Admin" in roles:
        return True
    return "/user"

# Assign the authorization callback
pn.config.authorize_callback = authorize_admin

# Create and configure the Material template
template = pn.template.MaterialTemplate(
    site="Panel",
    title="Admin Dashboard",
    main=[admin_content]
)

# Serve the admin dashboard
template.servable()

This code sets up the admin dashboard where the user roles and permissions are displayed and also checks if the user has the Tenant Admin role. If not, they are redirected to the user dashboard.

Open the .env file in the project root folder and add the following content, replacing the placeholder value with the ID of the tenant you created earlier on the Descope console:

DESCOPE_TENANT_ID="<YOUR-DESCOPE-TENANT-ID>"

At this point, if you run the application using the command panel serve admin.py user.py --oauth-provider=generic --dev and authenticate successfully, you'll be redirected to the default Panel landing page, which lists all the running applications. You need to add a function that automatically redirects the user to the appropriate app. To do this, create a new file named index.html in the project root folder and add the following code:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta http-equiv="Refresh" content="0; url='/main" />
    </head>
    <body>
        <p>Redirecting...</p>
    </body>
</html>

This HTML file acts as a redirect page for your Panel application. After successful authentication, users are redirected to http://localhost:5006, where this file automatically navigates them to the /main route. The /main route loads the main.py file, which determines whether users should be redirected to the admin or user dashboard based on their roles.

Refreshing the access tokens

In Panel, access tokens are cached as cookies. Depending on the OAuth provider you're using, these tokens may eventually expire. For example, Okta access tokens expire after thirty days. This means a user might remain logged into your application even though their access token has expired since it is cached.

To ensure you always have access to a valid access token, open the .env file in the project root folder and add the following line:

PANEL_OAUTH_REFRESH_TOKENS=1

This ensures that if a user tries to access your application with an expired token, the application will automatically fetch a new access token using the saved refresh token. If no refresh token is available, the user will be prompted to reauthenticate. As long as the user's session is active, the application will also schedule token refreshes ten seconds before the access token expires.

Adding a logout feature

Allowing users to log in to your Panel application is as simple as adding a widget and configuring the widget to redirect the user to the /logout endpoint.

First, open the admin.py and add the following code below the admin_content variable:

# Logout button
logout_widget = pn.widgets.Button(name="Logout", button_type="danger", width=100, align="end")

# Configure logout functionality
logout_widget.js_on_click(code="""window.location.href = '/logout'""")

This code creates a Logout button that redirects the user to the /logout URL when clicked.

Add this button to the dashboard's header by replacing the code that creates the Material template with the following:

template = pn.template.MaterialTemplate(
    site="Panel",
    title="Admin Dashboard",
    header=[pn.Row(pn.layout.Spacer(), logout_widget)],
    main=[admin_content]
)

You also need to do the same to the user.py file. Open the file and add the following code below signma_widget = pn.widgets.Button(...):

# Logout button
logout_widget = pn.widgets.Button(name="Logout", button_type="danger", width=100, align="end")

# Configure logout functionality
logout_widget.js_on_click(code="""window.location.href = '/logout'""")

Lastly, modify the code that creates the Material template, like this:

# Configure the template with the logout button in the header
template = pn.template.MaterialTemplate(
    site="Panel",
    title="User Dashboard",
    header=[pn.Row(pn.layout.Spacer(), logout_widget)],
    sidebar=[variable_widget, window_widget, sigma_widget],
    main=[bound_plot]
)

Testing the application

Now that everything is fully configured, you can test the application. To do this, make sure your virtual environment is still active and execute the following command in the terminal:

panel serve main.py admin.py user.py --oauth-provider=generic --index index.html --dev

Navigate to http://localhost:5006 on your browser, and you should be navigated to a sign-in page that is powered by the Descope flow you configured earlier:

On this page, you can choose to authenticate using any method. After successful authentication, you will be redirected to the user dashboard:

This shows that the authorization callback is working as expected as the user was not redirected to the admin dashboard.

Sign out of the app by clicking the Logout button. Go to the Descope console and navigate to the Users page. Here, identify the user you just signed in with, assign them the Tenant Admin role, and save the changes:

Go back to http://localhost:5006 on your browser and sign in again with the same credentials, and you'll now have access to the admin dashboard:

Conclusion

In this guide, you learned how to integrate secure authentication and SSO into a Panel application using Descope. From implementing secure authentication flows on the Descope console to integrating Okta as an IdP and implementing role-based access control, you now have the essential skills to enhance both security and user experience in your Panel apps. As a next step, you can explore additional features like multifactor authentication (MFA) and support for multiple SSO providers.

Descope is a drag-and-drop customer authentication and identity management platform. Our no-/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 like 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.

Next.js 15 vs. Next.js 16: What's the Difference?

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

This blog was originally published on Descope.

Next.js 16 marks a significant shift for the framework. What started as a simple SSR helper is now a comprehensive full-stack React engine.

This release brings major changes: Turbopack replaces Webpack as the default bundler, Cache Components introduces Partial Pre-Rendering (PPR), and middleware.ts becomes proxy.ts. The performance improvements are substantial, but you still may not be ready to switch over. You might be concerned about bugs, don't have time for migration work, or simply aren't ready to abandon Webpack yet.

This article breaks down what's actually different between Next.js 15 and 16, so you can decide whether to upgrade now or wait until v15's LTS support expires. If you do decide to switch over, we've included a short migration guide at the end to help ease your transition.

Next.js 15 vs. 16 at a glance

Feature	Next.js 15	Next.js 16
Bundler	Webpack as the default bundler, with Turbopack as an optional/experimental alternative.	Turbopack replaces Webpack, offering up to 10× faster Fast Refresh and 5× faster builds.
Caching Model	Fetch requests are cached by default with limited Partial Pre‑Rendering (PPR).	Cache Components with Partial Pre‑Rendering (PPR) for instant navigation and predictable caching defaults.
Middleware Architecture	Middleware API for routing and edge logic.	Middleware replaced by proxy.ts for clearer network boundaries.
React Version & Compiler	Introduced React 19 support along with the Speedy Web Compiler (SWC) for transpilation.	Offers full React 19.2 support and uses SWC with Turbopack integration for faster builds.
Image Optimization	Next.js Image component with built‑in optimization (WebP, AVIF).	Continued Image optimization and tighter integration with Turbopack for faster builds.
AMP Support Status	AMP is deprecated, but legacy support is still available.	AMP is fully deprecated and no longer supported in v16.

Performance and bundling

When deciding whether you should move from Next.js 15 to 16, performance is often the most important consideration.

The bundler plays a big role in the framework's performance. Next.js has used Webpack as the default bundler since the first version of the framework was released in 2016. Vercel's full move to Turbopack is one of the reasons Next.js 16 was such a pivotal release.

Next.js 15: Webpack default, Turbopack opt-in

As with the three previous iterations (v14, v13, and v12), Next.js 15 uses version 5 of Webpack. It offered improved disk caching, optimized Fast Refresh, more stable long-term caching of assets, and enhanced tree shaking over its predecessors.

In addition to the default implementation of WebPack, Next.js 15 also allowed developers to opt into an alpha version of Turbopack (using the --turbopack flag), a feature that had been present since Next.js 13. This inclusion allowed developers to experiment with and acclimate themselves to the bundler. It also allowed them to influence development by testing, reporting bugs, and sharing their ideas on how it could be improved.

Despite being in alpha, Turbopack was already showcasing boosts in build speed and hot reload times compared to Webpack; improvements that stemmed from its rewrite in Rust.

Next.js 16: Turbopack as default bundler

Next.js 16 fully replaced Webpack with Turbopack, much to the chagrin of developers who had an affinity for Webpack and disliked the fact that everything was being rewritten in Rust. However, Turbopack's use of Rust is precisely why it can outperform its JavaScript-based predecessor so easily.

Turbopack uses Rust's low-level control, fearless concurrency, and persistent caching to deliver incremental bundling where only changed files are rebuilt as opposed to the entire dependency graph. This also makes Hot Module Replacement (HMR) more efficient, since faster builds allow HMR to inject updated modules into the browser runtime more quickly.

Since Rust avoids unpredictable pauses (like garbage collection in JavaScript), it allows for incremental updates to be applied consistently and quickly, which also makes cold builds faster.

Let's use MySocials to showcase this. The Next.js 15 dev server took 35.6 seconds to initiate and run:

After upgrading the project to Next.js 16, the dev server launch time was cut down to 6 seconds:

A warm build was even quicker at 3.8 seconds:

We also found that compilation in development mode took Next.js 15.1 seconds to complete, while its v16 counterpart was done in 21 seconds. After editing the footer and reloading, v15 recompilation in Dev mode took 10.6 seconds, compared to 4.6 seconds in Next.js 16. In both instances, the changes were made available to the browser almost immediately thanks to HMR. Following additional rounds of testing and benchmarking, we found that a full Next.js 15 build took 251.67 seconds, whereas the v16 build took 36.25 seconds.

Here's a side-by-side breakdown:

Aspect	Next.js 15 (WebPack)	Next.js 16 (Turbopack)
Cold Startup Time	35.6s	6s (Nearly 6x faster)
Warm Startup Time	8.6s	3.8s (2.2x faster)
Dev Compilation Speed	121.7s	21.5s (5~x faster)
HMR / Fast Refresh Latency	10.6s	4.6s (2~x faster)
Full production build	251.67s	36.25s (7~x faster)

Why this matters

Next.js 16's new optimizations and features let you rapidly apply and test hot fixes. These are meaningful performance boosts that have short and long-term implications on the productivity of your team. Turbopack's incremental compilation is particularly favorable in monorepos and large apps with hundreds of packages. Next.js 16 only recompiles files that have new changes (along with their direct dependencies), saving you time and improving your project's ability to scale.

With that being said, it's important to note that Turbopack is still maturing, and several bugs have been reported and still persist. Contrastingly, Webpack is stable, reliable, and extremely well-supported with a thriving ecosystem of plugins and loaders. You could also always use Turbopack as an alternative bundler in Next.js 15.

However, Next.js 15 uses an alpha version of Turbopack. This means it's less stable and can only be run in dev mode. Features like Cache Components and React 19.2 support are also missing. Upgrading to Next.js 16 would allow you to take full advantage of Turbopack's capabilities. Although Turbopack is the default bundler, Next.js 16 still has full Webpack support. This means you can revert to it at any time after upgrading.

Cache components and use cache

v16 changes how caching is handled in Next.js. Where its predecessor used implicit caching as a default, Next.js 16 introduces a new explicit caching model.

The problem with implicit caching in Next.js 15

Next.js automatically decides what to cache and for how long, based on the APIs you use and where you use them. For example, data returned from fetch requests is uncached unless you explicitly opt in, but rendering work and certain data requests are cached per request lifecycle to improve performance.

Because earlier versions of Next.js leaned heavily on implicit caching, many developers assumed that repeated calls to the same endpoint would be cached automatically. However, if you didn't explicitly set options like force-cache or next:{ revalidate: 60 }, every request would hit the API fresh. This led to unexpected performance issues, especially when developers thought they were benefiting from caching but weren't.

Route segment caching was as confusing (if not more) because of how extensively caching behavior relied on the data-fetching API used in the segment. This meant that each route segment, whether a page, layout, or nested child, would be cached non-uniformly. For example, a segment using getStaticProps would be cached at build time, while one using getServerSideProps would fetch fresh data on every request. This implicit link between API choice and caching made it difficult to reason about how segments behaved without carefully tracking which API was in play.

It could also lead to accidental over-caching. If developers used getStaticProps without a revalidate interval, pages would remain cached indefinitely, even if the underlying data changed. This led to stale content being served to users until a new build was triggered.

How Next.js 16 improves caching

Next.js 16 makes caching explicit, granular, and predictable through Cache Components. This feature addresses the pitfalls of fetch caching by letting you wrap expensive components and functions in a cache boundary that you specify through the "use cache" directive. It essentially allows you to control how these elements should be cached and revalidated.

This goes for route segment caching, too. Cache Components provide each segment or component with its own cache boundary. Because caching is opt-in and configurable, the risk of over-caching reduces.

Code example: before vs. after

Here's an example showing implicit caching in v15:

// pages/products.js (Next.js 15)
export async function getStaticProps() {
  const res = await fetch("https://api.example.com/products");
  const products = await res.json();
  return {
    props: { products },
    revalidate: 60, // refresh every 60 seconds
  };
}

export default function ProductsPage({ products }) {
  return (
    <ul>
      {products.map(p => <li key={p.id}>{p.name}</li>)}
    </ul>
  );
}

The getStaticProps function automatically caches the page at build time as static HTML until the next build is initiated. You'll notice the inclusion of revalidate in the return. Without it, you risk accidental overcaching (stale data until a rebuild).

v16 uses explicit caching:

// app/products/page.js (Next.js 16)
export async function getProducts() {
  "use cache"; // Explicit directive: cache this function's result
  const res = await fetch("https://api.example.com/products");
  return res.json();
}

export default async function ProductsPage() {
  const products = await getProducts();
  "use cache"
  return (
    <ul>
      {products.map(p => <li key={p.id}>{p.name}</li>)}
    </ul>
  );
}

In this example, the "use cache" directive is called on both the function (getProducts) and the component level (<ul>). The getProducts function result is cached, while the rendered UI fragments are refreshed (revalidated) based on the default profile revalidation rules. You can also place the "use case" on the file-level (instead of on each function/component), essentially caching the entire page.

While the v16 example uses time-based intervals in its current form, you can explicitly set it to use tag-based invalidation or manual refresh. This lets you set clear revalidation rules, making updates predictable and easier to manage, instead of relying on implicit Incremental Static Regeneration (ISR) rules. By moving from implicit, API‑driven caching in v15 to explicit cache boundaries in v16, developers gain a simpler, more consistent mental model. You no longer have to guess how caching interacts with route segments or fetch calls; it's declared in code and easy to reason about.

Routing and edge changes

Next.js 16 replaces middleware.ts with proxy.ts. This change was mainly to clarify the layer's role. Many developers found the name misleading or confusing (and for good reason). It was never a catch-all "middleware" layer, but instead a proxy that intercepts and forwards requests at the network boundary.

The Problem with Next.js 15's middleware.ts

Before the change, many teams used the middleware (now proxy) layer for complex logic (authentication, database queries, heavy transformations), which was not its intended purpose. Developers would confuse it with Express.js middleware, which encouraged developers to treat it as a general logic layer rather than a lightweight routing tool.

Next.js 16's introduction of proxy.ts

With proxy.ts, routing rules are explicit and separated from caching. Proxy runs at the edge by default, which aligns with Vercel's push toward edge‑first architecture for Next.js 16 and future iterations of the framework. This ensures rewrites and redirects happen close to the user (edge side), improving latency.

Developers should think of the proxy as a network gatekeeper, not a hidden logic layer. This reduces confusion around where to put caching, revalidation, or authentication logic.

Migration considerations

When migrating from middleware.ts/middleware.js in Next.js 15 to proxy.ts/proxy.js in Next.js 16, you need to consider how your existing middleware logic maps to proxy rules. Simple routing logic from middleware maps cleanly to proxy rules, but heavier business logic should be moved into route handlers or server actions. In practice, if your middleware only rewrote /old-route to /new-route or redirected unauthenticated users to /login, those rules migrate directly into proxy.ts without much change.

The second consideration is identifying what breaks and what doesn't. What breaks are cases where the original middleware layer was overloaded with responsibilities it wasn't designed for, like database queries, complex authentication flows, or caching logic. You'll need to refactor those into server components, API routes, or dedicated backend services. The core routing behaviors, like rewrites, redirects, and header manipulation, are safe.

Let's say your middleware.js file looks like this:

// middleware.js (Next.js 15)
import { NextResponse } from "next/server";

export function middleware(req) {
  const url = req.nextUrl;

  // Redirect unauthenticated users
  if (!req.cookies.get("auth")) {
    return NextResponse.redirect(new URL("/login", req.url));
  }

  // Rewrite /old-route to /new-route
  if (url.pathname === "/old-route") {
    return NextResponse.rewrite(new URL("/new-route", req.url));
  }

  return NextResponse.next();
}

Your migrated proxy.js will look like this:

// proxy.js (Next.js 16)
import { proxy } from "next/server";

export default proxy((req) => {
  const url = req.nextUrl;

  // Redirect unauthenticated users
  if (!req.cookies.get("auth")) {
    return Response.redirect(new URL("/login", req.url));
  }

  // Rewrite /old-route to /new-route
  if (url.pathname === "/old-route") {
    return Response.rewrite(new URL("/new-route", req.url));
  }

  // Forward all other requests
  return Response.next();
});

You'll notice that redirects and rewrites migrate directly. The logic is almost identical. Any mention of "middleware" is replaced with "proxy".

React 19.2 integration

Next.js 16 integrates React 19.2 (where Next.js 15 was built on React 18) as its default React runtime, bringing stable support for Server Components, Actions, and the React Compiler. This tight integration makes caching, async server APIs, and edge execution more predictable and efficient.

React 19.2 View Transitions

View Transitions uses the browser's native View Transitions API to create smooth, animated changes between pages or UI states. It eliminates the need for complex animation libraries as the browser handles transitions. View Transitions also allows for seamless page‑to‑page animations, reducing the "hard cut" feel of traditional navigation.

useEffectEvent

Another notable feature introduced in React 19.2 is useEffectEvent. It lets you extract non‑reactive logic from your effects into a reusable function called an Effect Event, ultimately solving the stale closure problem. useEffectEvent ensures your effects always have access to the latest props and state without unnecessary re‑renders.

Imagine you're building a chat app. When a user connects to a chat room, you want to show a notification styled with the current theme (light or dark). Your code in Next.js 15 (without useEffectEvent) would look like this:

import { useEffect } from "react";

function ChatRoom({ roomId, theme }) {
  useEffect(() => {
    const connection = createConnection("https://example.com", roomId);
    connection.on("connected", () => {
      showNotification("Connected!", theme); // captures theme
    });
    connection.connect();
    return () => connection.disconnect();
  }, [roomId, theme]); // re-runs whenever theme changes
}

The notification logic is placed directly inside useEffect. If the theme changes, the effect re‑runs unnecessarily, tearing down and reconnecting the chat. The Next.js 16 rewrite would look something like this:

import { useEffect, useEffectEvent } from "react";

function ChatRoom({ roomId, theme }) {
  const onConnected = useEffectEvent(() => {
    showNotification("Connected!", theme); // always uses latest theme
  });

  useEffect(() => {
    const connection = createConnection("https://example.com", roomId);
    connection.on("connected", () => {
      onConnected(); // stable, no stale closure
    });
    connection.connect();
    return () => connection.disconnect();
  }, [roomId]); // only re-runs when roomId changes
}

The use of useEffectEvent keeps the connection stable while still using the latest theme for notifications. Dependencies are simpler, the chat connection isn't torn down unnecessarily, and notifications reflect the current theme.

The implications for Next.js apps

View Transitions and useEffectEvent both reduce the reliance on custom. In React 18 and earlier, developers often wrote hooks to manage stale closures in effects or to synchronize state with subscriptions. useEffectEvent provides a stable callback that always sees the latest props and state. Similarly, View Transitions removes the need for custom hooks or context providers to manage navigation animations. Together, these features cut down on boilerplate and make Next.js apps leaner and easier to maintain.

These features also contribute to more predictable rendering behavior. useEffectEvent ensures effects don't re‑run unnecessarily, keeping connections or listeners stable while still reflecting fresh state. View Transitions integrates directly with the App Router, so transitions happen consistently across route changes without unexpected flickers or mismatched states. For developers, this means fewer surprises in how React and Next.js handle updates, and for users, it means smoother, more reliable interactions.

Stable support for the React Compiler

Next.js 16 ships with React 19.2, and that includes the React Compiler as a first‑class integration. In practice, this means Next.js developers no longer need to scatter useMemo, useCallback, or React.memo throughout their codebase to prevent unnecessary re‑renders.

The compiler analyzes your components at build time and automatically applies memoization optimizations. For Next.js apps, this is especially impactful because of the App Router and Server Components model. Server Components already reduce client‑side JavaScript, and the compiler ensures that the remaining client components render efficiently without developer micromanagement. Combined with Next.js 16's explicit caching, you get predictable performance both on the server and client.

Developers can now write straightforward React code in Next.js without wrapping everything in memoization hooks. The compiler handles performance tuning automatically, so users experience smoother interactions.

Breaking changes and deprecations

The move from middleware to proxy wasn't the only potential project-breaking change that was introduced with Next.js 16. The next/image component shifted toward native browser features and simpler defaults.

Lazy‑loading is now applied automatically, responsive sizing no longer requires the layout prop, and styling props like objectFit and objectPosition have been deprecated in favor of plain CSS. These changes reduce abstractions but require migration if you relied on older defaults.

Audit and migration considerations

You'll need to remove deprecated props like layout, objectFit, and objectPosition, then add loading=eager or priority to prevent lazy-loading delays. Use fill for full‑width images or explicit dimensions for fixed sizing. This provides more responsive control.

For styling, move image fit/position logic into CSS classes for consistency. This helps manage the Cumulative Layout Shift (CLS). Tools like Lighthouse or WebPageTest can help you verify if images are causing layout shifts. To optimize the delivery of your images, use modern formats like WebP and AVIF. Next.js 16 automatically serves optimized versions, but it's always a good idea to confirm that your source assets are high-quality.

Remember to check file sizes. Large hero images should be compressed without visible quality loss. In addition to this, ensure images are cached at the edge for fast delivery.

AMP support Is deprecated

In Next.js 16, AMP support is fully deprecated and removed. You can no longer configure pages with amp: true or amp: 'hybrid', and the AMP optimizer is gone. Teams and organizations that had invested in building AMP‑specific pages for mobile performance or SEO will be the most impacted by this change.

AMP support deprecation also affects developers who built workflows around AMP's restrictions, such as limiting JavaScript usage, relying on AMP‑specific components, or configuring hybrid AMP pages. Those patterns are no longer supported, so developers need to migrate to Next.js's unified rendering model.

Instead of AMP's strict markup, they'll lean on Server Components, Actions, Turbopack, and explicit caching to achieve performance goals. This requires some refactoring, but ultimately simplifies codebases by removing the need for parallel AMP templates.

Migrating from AMP

SEO has shifted over the last few years. Google no longer gives AMP pages preferential treatment. Instead, Core Web Vitals (CLS, LCP, INP) are the ranking signals. A well‑optimized Next.js page can perform just as well as AMP. AMP required separate templates and restrictions. Next.js 16 lets you build a single React app with consistent tooling, reducing complexity.

When migrating from AMP, you first need to audit your project's AMP pages. This means identifying any pages using amp: true or amp: 'hybrid'. Next, remove all AMP configs and consolidate into standard Next.js routes.

Implement Server Component to minimize client JS, then move styling into CSS instead of AMP-specific markup. Replace AMP-restricted forms with Actions for mutations.

Migration strategy: how to upgrade safely

First, consider whether you should upgrade. For greenfield projects, upgrading to Next.js 16 makes sense. Starting fresh means you can adopt the new primitives we've discussed without worrying about legacy code. You'll be building on the latest architecture from day one, which reduces technical debt and ensures your app is aligned with the direction Next.js is heading.

For mature production apps, the decision requires more caution. Migrating from Next.js 15 involves rethinking middleware, auditing caching behavior, and replacing unstable APIs with their stable equivalents. If your app is business‑critical, you'll want to plan a phased migration, starting with staging environments and regression testing before rolling out to production. The payoff is significant. You'll get better performance and more predictable caching. However, the risk of breaking existing flows means you should approach the upgrade deliberately rather than rushing.

Team size and risk tolerance also play a big role. Smaller teams with limited resources may prefer to wait until the ecosystem stabilizes further, since they may not have the bandwidth to troubleshoot regressions. Larger teams, or those with higher risk tolerance, can benefit from adopting Next.js 16 earlier, especially if they have the capacity to run performance regression tests, audit caching, and adjust CI/CD pipelines.

The right timing depends on your context, but once you've weighed those factors, the next step is to define a clear upgrade path.

Recommended upgrade path

The quickest way to upgrade your Next.js project from version 15 to 16 is by using the upgrade codemod. Open a terminal, navigate to your project's root folder, and run the following command:

npx @next/codemod@canary upgrade latest

Note: Ensure that Node.js is installed before running the above command.

The upgrade codemod is interactive. So once it's done downloading the necessary packages, it will present you with a set of upgrade options that are relevant to your project. These include:

Adding the new Turbopack configuration to your next config file.
Migrating from next lint to the ESLint CLI.
Switching over to proxy from the middleware convention.
Remove experimental_ppr Route Segment config from App Router pages and layouts.
Drop all unstable_ prefixes from stabilized APIs.

You may not see some of these options if they're already up-to-date in your project. For instance, if your project is already using the latest ESLint CLI, it won't appear in the list:

By default, all update options are toggled on. Once you're ready, you can hit the Enter key to perform the updates.

Alternatively, you can upgrade your project manually, especially if the upgrade codemod fails.

Manually upgrading Next.js 15 to 16

Run the following command to upgrade Next.js to the latest version:

npm install next@latest

You can then upgrade React using the following command:

npm install react@latest react-dom@latest

Note: If you're using TypeScript, you'll need to update @types/react and @types/react-dom.

Some libraries may not yet support React 19. Fortunately, Next.js 16 supports React 18.2.0+. That means, if you find version mismatches or peer dependency conflicts, the best way to get around this is by upgrading or downgrading to React 18 (which Next.js 16 still supports), like this:

npm install react@18 react-dom@18

Next, you'll need to migrate from the middleware to proxy. First, find the middleware file in your root folder (middleware.js or middleware.ts) and rename it to proxy (proxy.js if you're using JavaScript, or proxy.ts if you're using TypeScript).

Next, open your freshly renamed proxy file and replace the middleware export function to proxy (if available):

export function proxy(request: Request) {}

You'll also need to replace any configuration flags that contain middleware as part of their name. For example, you'll need to change skipMiddlewareUrlNormalize to skipProxyUrlNormalize.

Alternatively, you can run the migration codemod from your terminal, which will perform all the migration steps for you:

npx @next/codemod@canary middleware-to-proxy .

If your Next.js 15 project uses experimental Partial Pre-Rendering (PPR), you'll need to remove every instance of it (flags, configuration options, and route-level segments). Vercel provides another helpful codemod to perform this action. Run the following command from your terminal:

npx @next/codemod@latest remove-experimental-ppr .

You can then opt into PPR by adding the cacheComponents option to your next.config.js file:

/** @type {import('next').NextConfig} */
const nextConfig = {
  cacheComponents: true,
}
module.exports = nextConfig

Next.js 16 stabilized a large number of plugins that were marked unstable in version 15. To ensure that your Next.js 16 project isn't calling deprecated APIs, you'll need to remove every mention of the unstable_ prefix from all stabilized APIs. You can do this manually or use the codemod:

npx @next/codemod@latest remove-unstable-prefix .

Enabling Webpack as a fallback

If your project relies on WebPack loaders, plugins, or has a custom configuration, you can opt out of Turbopack. You can run Dev with the Webpack flag:

npx next dev --webpack

Alternatively, you can edit the script section of your package:

"scripts": {
  "dev": "next dev --webpack",
  "build": "next build --webpack",
  "start": "next start",
  "lint": "next lint"
},

This will force your project to use WebPack in both the production and development builds. If you need to use Turbopack for one of these builds (for instance, dev), you can simply remove the --webpack flag.

Post-upgrade tooling and testing tips

Developers looking for the latest bug fixes and feature updates may be tempted to opt into canary releases. Canary releases aren't guaranteed to be stable, as they may contain unfinished APIs, regressions, or performance issues.

How to approach canary releases

For most teams, the safer approach is to test canary builds in local development or staging environments, where you can evaluate new features without exposing end users to potential instability. You can run the following command to pin your project to the latest Next.js canary build:

npm install next@canary

Opting into canary releases is most beneficial for developers who maintain libraries, frameworks, or large applications that need to anticipate changes. Canary builds are best for local development, staging, or feature branches. Avoid deploying them to production unless you're comfortable with instability.

Whether you're running the Canary or official stable release, you'll want to combine Next.js 16's tooling upgrades with a set of targeted testing practices. The first tool you should acquaint yourself with is the Next.js DevTools MCP Server.

Using the Next.js DevTools MCP server

The Next.js DevTools MCP Server is designed to give developers deep visibility into how their application is behaving at runtime, especially around caching and rendering. Prior to its introduction, developers often had to rely on logs, headers, or trial‑and‑error to understand what was cached, when it would revalidate, and why certain components were re‑rendering.

Use it to inspect cache boundaries, to see exactly where cache() is being applied to your code. This is crucial because caching in Next.js 16 is explicit.

For revalidation timings, DevTools provide a clear view of how long cached data is valid and when it will be refreshed. Instead of guessing whether a component will revalidate after 30 seconds or only on demand, you can see the exact timing in the DevTools panel. This helps you audit your ISR or Cache Component settings and ensures that your content stays fresh without overloading your backend.

DevTools can also show you whether a component was served from cache, revalidated, or freshly rendered. This is especially important in Next.js 16 because PPR means parts of a page may be cached while others are dynamic.

In addition to the above, you'll also need to audit the Turbopack's cache behavior.

Auditing Turbopack's cache behavior

Turbopack now writes build artifacts into a persistent cache directory .next/cache. It's important to inspect the size and contents of this folder from time-to-time, especially if you're experiencing performance dips or build issues. Delete the contents of this folder to force Turbopack to rebuild everything from scratch. You can then measure how fast your rebuilds are against previous builds.

To measure how long builds take on Linux/macOS machines, you can use:

time npm run build

Or the following for Windows machines:

Measure-Command { npm run build }

Conclusion

Next.js 16 introduces proxy.js, Cache Components, and Turbopack's file cache to give developers clearer boundaries and faster builds.

Migrating from 15 to 16 requires teams to adapt to a new philosophy. Routing logic is now separated cleanly from authentication, caching is transparent and auditable through DevTools MCP, and build performance benefits from persistent caching. These changes reduce guesswork, improve scalability, and align Next.js more closely with modern React practices.

Ultimately, Next.js 16 is less of an incremental update and more of a re‑architecture. It challenges developers to rethink how they structure applications, but rewards that effort with faster builds, clearer caching strategies, and a more stable foundation for future growth.

Authentication, access control, and user management are critical components of any Next.js app. Use Descope's no / low code workflows to easily add natively embedded auth to your Next.js app without worrying about custom code or keeping up with breaking changes. You can also use Descope integrations on the Vercel Marketplace to add auth for your users and MCP servers in a few clicks. Sign up for a free Descope account to get started.

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.