jess-author

Jessica Temporal is a Senior Developer Advocate at Auth0 and co-founder of the first Brazilian data science podcast called <a target='_blank' href='https://pizzadedados.com'><strong>Pizza de Dados</strong></a>. She’s the author of <a target='_blank' href='https://www.amazon.com/dp/B0CDNX6NS7/ref=sr_1_1?&_encoding=UTF8&tag=jesstempora0e-20&linkCode=ur2&linkId=efc4229f6b816609dfce4f185781d99a&camp=1789&creative=9325' ><strong>The Big Git Microbook</strong></a>, creator of <a target='_blank' href='https://gitfichas.com/en'><strong>GitFichas.com</strong></a>, and a part of <a target='_blank' href='https://www.linkedin.com/learning/instructors/jessica-temporal'><strong>LinkedIn Learning</strong></a> instructors team. Jessica helped develop the AI that identifies possible unlawful expenses from Brazilian politicians. She is part of the PyLadies initiative that works to improve diversity and inclusion in technology. In her free time, she likes to knit, play video games, use her 3D printer, and is learning to create 3D models.

Sr. Developer Advocate

Jessica Temporal

The official Auth0 MCP Server is now available. MCP Hosts can securely manage Auth0 tenant resources using natural language.

**TL;DR:** The official Auth0 MCP Server is available now. We’ll go over how you can use Claude Desktop, Cursor, Windsurf and other MCP Clients to securely manage your Auth0 tenant using natural language. Learn more with [our Get Started guide](https://auth0.com/docs/get-started/mcp/getting-started-with-model-context-protocol-mcp).

<AmpContent>
<amp-youtube
    data-videoid="-Oq022WDIuY"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>
<NonAmpContent>
<div class='embed-container' style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;"><iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" src='https://www.youtube.com/embed/-Oq022WDIuY' frameborder='0' allowfullscreen></iframe></div>
</NonAmpContent>


We want to make it easier for you to secure your apps with Auth0. Maybe you use an AI tool to help test your code, write documentation, or just “vibe code” your way through a new proof-of-concept app. Imagine saying to your favorite AI tool:

> “I want to create a mobile app with passkey and Google Sign-In, and access to an API with these scopes…”

and having Auth0 set up everything for you automatically.

Well, now you can.

We’re excited to introduce the **Auth0 MCP Server**, which enables AI tools like Claude Desktop, Cursor, Windsurf and other [MCP Clients](https://modelcontextprotocol.io/clients) to securely configure your Auth0 tenant using natural language through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction).

With the Auth0 MCP Server, you can delegate tasks like creating applications, configuring APIs, or deploying Auth0 Actions without exposing credentials and without interrupting your flow to interact with the Auth0 Dashboard.

MCP is just the bridge, what really matters is how effortlessly you can now configure Auth0.

If you want to understand more about MCP in general and how auth plays a role in the world of MCP read the following guide:

<include src="LinkCard" 
    link="https://auth0.com/blog/an-introduction-to-mcp-and-authorization/"
    title="An Introduction to MCP and Authorization"
    description="Discover the Model Context Protocol (MCP) and its authorization mechanisms. Learn how to use API keys, OAuth 2.1 implementation, and best practices for secure LLM API connections." 
    img="https://images.ctfassets.net/23aumh6u8s0i/ImPbKVGMqKM4FMs9Flncw/f715edcaec63105c95189125436cc3a1/MCP_and_Authorization.jpg" />

## What Is the Auth0 MCP Server?

**MCP** is an open protocol that standardizes how AI applications talk and pass context along to an LLM. With the Auth0 MCP Server, you can use commands like the one below in the supported AI client of your preference:

> “Create a new Auth0 application named staging-app with a callback URL of https://staging.example.com/callback.”

The Auth0 MCP Server will receive the request in the MCP format and turn them into actual Auth0 Management API calls while enforcing secure authentication, scoping, and permissions through OAuth 2.0.

![High level diagram showing how the Auth0 MCP Server](https://images.ctfassets.net/23aumh6u8s0i/5pwkaCQFO7xNuQUnKQNdue/6418d6e3446c0d779ce9304ccb3b0f6a/Uploaded_from_Auth0_MCP_Server_Announcement)

This means you can delegate identity management operations to your favourite supported AI tool without handing over raw API tokens or direct access to the Auth0 Management API.

## What You Can Do with Auth0 MCP Server

With the Auth0 MCP Server, your AI tool can:

*   **List and manage Auth0 applications** – List, create, update or Applications (Web Apps, Native, and SPAs)
*   **Access and configure APIs (Resource Servers)** – Create, update or APIs
*   **Inspect tenant-level Auth0 Actions** – List, update, or deploy Auth0 Actions in a tenant
*   **Interact with Tenant Logs** – Get and search logs
*   **Manage Forms** – List, create, update, or Auth0 Forms

These capabilities mean that Claude Desktop, Cursor, and others can become your personal Auth0-assistant, setting up configurations so that you can secure applications with Auth0 even faster. Imagine building your application in Cursor while telling Cursor to create the corresponding Auth0 Application with the necessary Callback URL and Logout URLs configuration in a single message.

### Auth0 MCP Server Key Features

##### Secure Authentication

Uses Device Authorization Flow to give all supported AI tools scoped-access to your Auth0 account. This allows you to manage applications, APIs, Auth0 Actions, and more by prompting your AI tool to do so.

##### Protected Credentials

Stores credentials securely in the system keychain, preventing unauthorized access. Only the Auth0 MCP Server has access to the Auth0 access token and refresh token stored.

##### Comprehensive Tools

Supports a collection of operations for your Auth0 tenant management. CRUD operations for your APIs and applications protected with Auth0 through the Management API, deployment of tenant-level Auth0 Actions, and more. See the [complete list of operations available here](https://auth0.com/docs/get-started/mcp/model-context-protocol-mcp-tools-reference).

##### Seamless Integration

Follows the standard Model Context Protocol and allows you to work directly with [any supported MCP Client](https://modelcontextprotocol.io/clients). The Auth0 MCP Server setup will take care of making all the configuration for you so you can start prompting right away in Claude Desktop, Cursor, and Windsurf.

## How The Auth0 MCP Server Works

Under the hood, the Auth0 MCP Server serves as a bridge between the MCP JSON schema and the **Auth0 Management API**.

![Device Authorization Flow in the Auth0 MCP Server context](https://images.ctfassets.net/23aumh6u8s0i/5YRh5xZe6m6M4qnrsUjJUY/e56bbab80cb012b3b12b3ec465e6e7b9/Uploaded_from_Auth0_MCP_Server_Announcement)

When you initialize the Auth0 MCP Server you’ll go through the [device authorization flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow): a browser window will open up for you to authenticate to Auth0 and choose your tenant. After authenticating, your credentials will be safely stored in your system’s keychain or equivalent app depending on your operating system. Once configuration is done, you’ll be able to interact with Auth0 through any supported AI tool and all of that without having to copy your API key.

![Auth0 consent screen](https://images.ctfassets.net/23aumh6u8s0i/MA5ybpuZEcPiM3qUprt9i/7ea2cf5bf2902da7a47413cd561c6406/Uploaded_from_Auth0_MCP_Server_Announcement)

No matter which tool you are using, all of them will follow a similar collection of steps as outlined above.

## Getting Started with the Auth0 MCP Server

To get started with the Auth0 MCP Server, follow the steps below.

### Prerequisites

*   [Node.js v18](http://node.js)+
*   [Claude Desktop](https://claude.ai/download), [Cursor](https://www.cursor.com/downloads), or [Windsurf](https://www.windsurf.com/editor/download), or your favorite MCP host.
*   Auth0 account

### Install and Configure

Install and initialize the Auth0 MCP Server with a single command:

```sh
npx @auth0/auth0-mcp-server init
```

Then, you need to restart your tool for the updates to take effect. That’s it.

![Terminal showing the result of running ‘npx @auth0/auth0-mcp-server init’](https://images.ctfassets.net/23aumh6u8s0i/6v898a9HHNxLJw0XN5dVGy/1b6db2a87c7690e169c0b3ebfb8290ee/Uploaded_from_Auth0_MCP_Server_Announcement)

The initialization will:

1.  Start the [device authorization flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow);
2.  Open your browser for you to authenticate with Auth0, select your preferred Auth0 tenant, and confirm permissions on the consent screen;
3.  Store your credentials (Auth0 access token and refresh token) securely in your system's keychain;
4.  Create configurations for Claude Desktop to use the Auth0 MCP Server.

Since the stored credentials are an Auth0 access token and a refresh token, you don’t have to authenticate every time you want to use the MCP Server. The server will take care of getting new access tokens when they expire. Additionally, if you want to change the tenant you are currently using, run the `init` command again, this will allow you to select a different tenant.

The MCP Host you are using e.g.: Claude Desktop, identifies which MCP Server you want to use based on your prompt. The MCP Host will then use the configuration files to interact with that MCP Server. This is what a configuration file for Claude Desktop looks like:

```json
{
  "mcpServers": {
    "auth0": {
      "command": "npx",
      "args": [
        "-y",
        "@auth0/auth0-mcp-server",
        "run"
      ],
      "capabilities": [
        "tools"
      ],
      "env": {
        "DEBUG": "auth0-mcp",
        "PATH": "..."
      }
    }
  }
}
```

For instructions on [how to set up other clients read this documentation](https://auth0.com/docs/get-started/mcp/getting-started-with-model-context-protocol-mcp#other-mcp-clients).

Let’s take a look at what happens when you want to use Cursor with the Auth0 MCP Server to secure a FastAPI web app:

1.  You initialize the Auth0 MCP Server passing Cursor as the client like so:

```sh
npx @auth0/auth0-mcp-server init --client cursor
```

And go through the authentication and selection of your tenant

1.  Then you open Cursor and implement your web app in FastAPI like you normally would and protect it using Auth0
2.  Once implemented, you prompt Cursor to create a new Auth0 application with a prompt similar to this:

    “Create a new Auth0 web app application named ‘My FastAPI App’, with a Callback URL [http://localhost:4040/callback](http://localhost:4040/callback) and an Allowed Logout URL [http://localhost:4040](http://localhost:4040) and make sure it is OIDC compliant and set the JWT to use `alg` RS256”

1.  In the background Cursor identifies the MCP Server you are trying to use then asks you to allow it to run the tool. Cursor shows you the parameters it is going to use, something like this:

```json
{
  "name": "My FastAPI App",
  "app_type": "regular_web",
  "callbacks": [
    "http://localhost:4040/callback"
  ],
  "allowed_logout_urls": [
    "http://localhost:4040"
  ],
  "oidc_conformant": true,
  "jwt_configuration": {
    "alg": "RS256"
  }
}
```

You should double check the parameters, and then you can give your consent for Cursor to run the MCP tool call. It then passes the request in the MCP transport format to the Auth0 MCP Server

1.  The Auth0 MCP Server then maps the request from Cursor to the action in the Auth0 Management API and makes the request using the access tokens stored in the system’s keychain;
2.  Auth0 then checks the credentials and sends back the information to the Auth0 MCP Server which in turn passes the information in the MCP transport to Cursor;
3.  Cursor then takes the received information and transforms it in a natural language answer using the LLM to show the information of your recently created, it even asks if it should add that to your application environment.

You can see all of this happening in the video below:

<include src="Vidyard" id="PJn2DTV7gjXmmf4rcGeGbg" />

This way Cursor never has access to the access tokens and the Auth0 MCP Server is the only one responsible for interacting with the Auth0 Management API.

Now that you’ve seen how it works you can tell that the possibilities are endless: Can you imagine telling your favorite AI IDE to build a mobile application with Auth0 and the application being built for you without you having to do any setup? We plan to cover this and how to leverage the Auth0 MCP Server with AI tools in future blog posts.

## Recap

Most developers today are leveraging AI tools to write and test code even faster.

With the **Auth0 MCP Server** your MCP Hosts can safely, reliably, and intelligently manage your Auth0 configurations using natural language.

Identity management should be integrated in these tools so developers won’t compromise on security and still keep their productivity levels high.

Share feedback, ideas, and use cases below. We are looking forward to seeing what you’ll build and how you’ll use the Auth0 MCP Server.

### Try It Now 👉 [Check out the source code on GitHub](https://github.com/auth0/auth0-mcp-server) and [our Get Started guide](https://auth0.com/docs/get-started/mcp/getting-started-with-model-context-protocol-mcp)

The Auth0 MCP Server is here!

Aliyah Winfrey

I'm Aliyah Winfrey, a staff design researcher who’s passionate about creating clarity and alignment in complex research spaces. I thrive on asking the right questions and uncovering insights that drive meaningful design. Outside work, I tend to my garden, experiment with new baking recipes, or get lost in a classic PS2 game.

Staff Design Researcher

Exploring the evolving tech/identifier trends, needs, and behaviors of a global audience

As an advocate for developers and a company that trusts the developer community, we are open-sourcing this survey data to foster dialogue, innovation, and shared learning. By making these insights publicly available, we invite researchers, developers, and CIAM leaders to analyze and build upon our findings. Understanding global digital identity trends requires diverse perspectives, and an open-source approach allows for an informed and equitable discussion. 

Digital technologies continue to change human interactions, shaping global attitudes toward identity, security, and new technological innovations in similar and different ways. Our latest End-User Device & Login Sentiment survey highlights key trends in digital identity preferences, authentication methods, and security concerns. This survey and high-level takeaways contribute to the broader discourse of technology, CIAM, and an evolving general population market. Please find details on the purpose, audience, and collection below:

## Purpose

Understand the general population of global users' evolving technology needs and behaviors to identify key trends and shifts. The following Key topics were covered: 

**Device/OS usage**

* Personal vs. Work device usage 
* Device registration preference
* Work application usage

**Attitude towards technology**

* Overall tech familiarity 
* Hardware update motives
* Frequency of technology updates

**Identifier preference**

* Identifier familiarity 
* Identifier registration preference
* Perceived vulnerability and convenience 

**Password management**

* Reuse & Change Password
* Compromised PII
* Fraud Check

![Key Topics](https://images.ctfassets.net/23aumh6u8s0i/34N68QuL8Q9JZBT8ql8wXB/218ff72b8716be2887562adb892c3e28/key_topics.png)

### Research Questions

1. Understand current technology devices and usage patterns 
2. Identifying emerging trends in end-user preference 
3. Discover unmet needs and pain points to capitalize on new opportunities, driving innovation and strategic growth

### Target Audience

Partnered with Qualtrics for a 33-question survey in the following regions/countries: EMEA (France & United Kingdom), NAMR (United States & Canada), LATAM (Mexico & Brazil), and India. 

### Sample

**N=1049**

* Age
    * Age 18-23: 19%
    * Age 24-30 19%
    * Age 35-54: 32%
    * Age 55+: 30%
* Region
    * NAMR 25%
    * EMEA 25%
    * LATAM 25%
    * APAC 25%
* Gender
    * Male:48%
    * Female: 52%
* Community Type
    * 1/3 Rural
    * 1/3 Suburban
    * 1/3 Urban
* Household Income
    * Less than $25,000- 5%
    * $25,001 - $50,000- 10%
    * $50,001 - $75,000- 20%
    * $75,001 - $100,000- 30%
    * $100,001 - $150,000- 20%
    * $150,001 - $200,000- 10%
    * More than $200,000- 5%

### Data Integrity 

No personally identifying information (PII) was collected. All responses shorter than 3 minutes (180 seconds) were removed. The median completion time was 6.08 minutes. Participants were compensated for completing the survey. 

Samplings across regions are representative of age and gender distributions. For example, given the larger youth population, more youth aged 18 to 30 were sampled in India. Given the country's demographics, ages ranging from 45 to 59+ were skewed towards EMEA and NAMR. 

Additionally, LATAM skewed predominantly toward the urban community type, EMEA represented much of the rural community type, and NAMR led heavily toward the Suburban community type.

### Regression analysis

![Regression analysis](https://images.ctfassets.net/23aumh6u8s0i/2cF18Iz0eEWlprYHPlHlFR/f21d36a8cb21cabedd6100f1037f7aba/Regression_analysis.png)
_Logistic Regression on survey data was completed to gauge if any response options forecast an individual's Willingness to Try New Identifiers. No substantial evidence indicates these factors are significant predictors._

<br>
Six low-level predictors for Willingness to Try New Identifiers were identified. These include the following:

1. Attitude towards New Tech
2. Familiarity with Identifiers other than Email and Username
3. How often do individuals update their devices
4. Age
5. Apple-Only OS Owners
6. APAC/India region 

Data was collected in October of 2024. Data is accessible via a[ CSV. file](https://cdn.auth0.com/blog/blog/End-User-Sentiments-Survey.csv).

#### Citation

1 End-User Device and Login Sentiment, Auth0, 2024. [Link](https://auth0.com/blog/digital-identity-what-users-think-about-devices-and-logins/)

## Insights

### Top 10 Learnings 

1. Android Phone and Windows OS more widely adopted across diverse groups: <br>
 - Adoption more prevalent in LATAM and APAC
 - Android users tend to be lower to middle-household income 
![Android, Windows OS lead in adoption](https://images.ctfassets.net/23aumh6u8s0i/1cz14tdcdDmqEZI5ZBgD9M/15021e7a00fe7d4967d9255f16f99b7d/Screenshot_2025-03-21_at_12.39.11_PM.png)
2. Younger demographics and higher income are more likely to use Apple OS <br>
 - Apple OS more pronounced in EMEA and NAMR
3. Younger demographics and higher income are more likely to use Apple OS <br>
 - Positive attitude toward new technology, higher frequency of device updates, and more open to adopting new identifiers
4. EMEA and NAMR are more cautious about approaching new technologies <br>
 - Preference could be influenced by cultural differences and regulations
![General comfortability with adopting tech once mainstream](https://images.ctfassets.net/23aumh6u8s0i/6LXzCLV1QzEPUbZk2rh5c9/33bea12287c85db2359d9e8990a5bda4/Screenshot_2025-03-21_at_12.29.28_PM.png)
5. Top upgrade motivators are new features, device damage, battery issues, and limited memory. <br>
 - India/APAC unique concern for social brand preference and security concerns
![New features and de ice damage lead us upgrade motivators](https://images.ctfassets.net/23aumh6u8s0i/7CbnGFomOPj6PfmU4IfzeD/e92edbcce72f7994c1ca55ac4575dfa8/Screenshot_2025-03-21_at_12.30.33_PM.png)
6. Respondents who are more familiar with alternative identifiers (email and username) show higher readiness to adopt new ones. <br>
 - Apple OS users less likely to try new identifiers 
7. The most familiar and used identifiers include Email, username, phone/SMS, and biometrics. In contrast, the least used and familiar include Blockchain and hardware security keys. <br>
 - Social login is slightly more prevalent in LATAM and APAC
![APAC lead in familiarity and use for most methods](https://images.ctfassets.net/23aumh6u8s0i/71S0j1xEeG6isV67O1SwkP/4a7cdda42233bd8cc16c2a6a2f5829cf/Screenshot_2025-03-21_at_12.35.26_PM.png)
8. Username, email, and fingerprint are rated as the most convenient across all regions. <br>
 - EMEA and NAMR seem to be more sensitive to non-conventional identifiers such as government ID, security key, and voice ID, while even social login is ranked neutral. 
![Username, email, and fingerprint rated as most convenient](https://images.ctfassets.net/23aumh6u8s0i/7JSF843aMWSNsNSTxBBF0d/c1e9723a8b0efd52cc02748b81256bf6/Screenshot_2025-03-21_at_12.36.02_PM.png)
9. In contrast, Social Login is perceived as the most vulnerable to hackers and cyber-attacks. <br>
 - Our recent article, Demystifying Social Login, dives deeper into the security of leveraging Auth0 social connections for end-users. 
![Social Login seen as most vulnerable to cyberattacks](https://images.ctfassets.net/23aumh6u8s0i/7zuPvErvRjmZo3uflHsRdG/49f35a40cc73261e8d7ad06cffba6f8b/Screenshot_2024-12-17_at_10.27.55_AM.png)
10. Security and Privacy priority for motivations to try new identifiers <br>
 - NAMR and EMEA rank innovation as one of the lowest drivers
![Security and Privacy priority for motivations to try new identifiers](https://images.ctfassets.net/23aumh6u8s0i/3LpGrqWztktMy8Nw1H2lYJ/550ad822c4f8684ef18c2cea1f751d56/Screenshot_2025-03-21_at_12.34.25_PM.png)

> Download the [.CSV data here](https://cdn.auth0.com/blog/blog/End-User-Sentiments-Survey.csv).

Join the conversation! Share your thoughts, repost, and tag us to discuss the future of digital identity.

Digital Identity: What Users Think About Devices and Logins

william_johnson

  Will Johnson is a Developer Advocate at Auth0. He loves teaching topics in a digestible way to empower more developers. He writes blog posts, records screencasts, and writes eBooks to help developers. He's also an instructor on <a target='_blank' rel='noopener noreferrer' href='https://egghead.io'><strong><b>egghead.io</b></strong></a>.


Developer Advocate

Will Johnson

Learn how to use Auth0 to secure a remote MCP server built with Cloudflare Workers to access a protected API.

**TL;DR** - Auth0 is collaborating with Cloudflare to make it easier for developers building remote MCP servers to configure authentication and authorization. Remote MCP servers will allow AI applications to access external services securely. This post details how to use Auth0 to secure a remote MCP server built with Cloudflare Workers to access an external service. It uses a sample Todo API as that external service.

## What are MCP Servers?

Developers are using large language models (LLMs) and AI applications to help build and deploy their code. Those applications are great when using data LLMs have already been trained on, but what if they could connect to external services to get even more information? That’s where the [Model Context Protocol (MCP)](https://auth0.com/blog/an-introduction-to-mcp-and-authorization/) comes in. MCP is a protocol that allows LLMs to connect with external tools and APIs in a standardized way. Using MCP, AI applications can connect with external services without knowing how each API works. MCP achieves this by using a client-server model.

* **MCP Client** &mdash; A client maintains the connection to MCP servers from inside of an LLM-based application.
* **MCP Server** &mdash; A server is always running and listening to be called by an MCP Client. 

Remote MCP servers are accessible on the Internet. Users sign in, and grant permissions to MCP clients using authorization flows with which they are already familiar. This opens up new use cases for users who may not want to run a MCP server locally on their machine, but are comfortable interacting with APIs and granting access online.

## Securing a Remote MCP Server with Auth0 and Cloudflare

Auth0 has collaborated with Cloudflare to help developers secure remote MCP servers powered by [Cloudflare Workers](https://developers.cloudflare.com/workers/). With the pace of MCP adoption rapidly increasing, Cloudflare has continued to keep up with innovation - [adding features to its platform](https://blog.cloudflare.com/remote-model-context-protocol-servers-mcp/) that handle the hard parts of building remote MCP servers, like `workers-oauth-provider`, an OAuth Provider that makes authorization easy. By [securing your MCP server with Auth0](https://auth0.com/blog/an-introduction-to-mcp-and-authorization/), AI applications can now interact with an external API by connecting through the remote MCP server and make API calls on behalf of an authenticated user.

In the rest of this blog post, we will walkthrough a practical example of this. We will set up and use an AI application to connect with a sample Todos API using an MCP server secured by Auth0. The server and API are Cloudflare Workers projects and will use Auth0 to request and receive access and refresh tokens.

![Diagram of request from MCP Client to a Todo API using Auth0 and Cloudflare](https://images.ctfassets.net/23aumh6u8s0i/1ycXxkqfevcl9XgqrtAL7E/b69b63cd6936a09343f7664229e07919/mcp-8.png)

We will first create the necessary accounts and set up the Todos API, then deploy and configure an MCP server that will connect to Auth0, and finally, the MCP Client can request information from the Todos API.

## Get Started

To follow along, you will want to set up your local developer environment. To get started:

* Create an [Auth0 Account](https://auth0.com/signup?place=header&type=button&text=sign%20up).
* Create a [Cloudflare Account](https://www.cloudflare.com/).
* Install Visual Studio Code (or your favorite code editor).

Once you create those accounts, you will want to 

* Install [Node.js](https://nodejs.org/en/download) (v18+).
* Install [Git](https://git-scm.com/downloads).
* Install the Cloudflare Wrangler CLI. [Read the documentation on installing Wrangler here](https://developers.cloudflare.com/workers/wrangler/install-and-update/).

### Get the Todo API and Remote Auth0 MCP server sample applications

The sample Todos API and remote MCP server are within the [Cloudflare AI monorepo](https://github.com/cloudflare/ai). Clone the repo, navigate to each application, and install the dependencies using the following commands in the terminal.

For the **Todos API**:

```
git clone https://github.com/cloudflare/ai.git
cd ai/demos/remote-mcp-auth0/todos-api
npm install
```

The TodosAPI is built with the [Hono web framework](https://hono.dev/),

For the **remote MCP** Server:

```
cd ../mcp-auth0-oidc
npm install
```

With both of the projects available locally and dependencies installed, proceed to the next step to secure the Todos API with Auth0.

### Configure the Todos API with Auth0

Let’s configure the Todos API to be secured by Auth0. Doing this will allow the remote MCP server to receive both access and refresh tokens and perform actions on behalf of the end user. To get started, [login to your Auth0 account](https://auth0.com/api/auth/login?redirectTo=dashboard) to visit the Auth0 Dashboard.

Create an API on the Auth0 Dashboard by going to [Applications > APIs](https://manage.auth0.com/#/apis/). Then click **Create API**.

![Create API modal in Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/klUW8q2EKjmE0CnTpaTU6/bb20af2cc6123644879ec38f09c51c73/Screenshot_2025-04-10_at_3.27.31_PM.png)

Next, enter the following values in the following fields:

* In the **Name** field, enter “Todos API”.
* In the** Identifier** field, enter `urn:todos-api`. This value will be used as the audience parameter when the MCP server makes an authorization call to the Todos API.
* Press the **Create** button

The next step is to allow a refresh token to be retrieved when requested by the remote MCP server. Go to [Applications > APIs](https://manage.auth0.com/#/apis/) and click on the entry for the Todos API. Visit **Settings**, scroll down to **Access Settings**, and toggle the **Allow Offline Access** button to enable it. Then click **Save**.

![Screenshot of API Access Settings in Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/6qoFrMXPUzyt5Z6SWK9o9w/517bf73eac7a9f701c984d18aec18fdf/Screenshot_2025-04-10_at_3.33.40_PM.png)

Toggling on the Allow Offline Access, allows a [refresh token](https://auth0.com/docs/secure/tokens/refresh-tokens) to be retrieved by the MCP server, so the user doesn’t have to keep re-authenticating when an access token expires.

As a final step - the permissions (scopes) need to be configured in the Auth0 Dashboard. These will be granted when a user authorizes an application to gain access to an API. In the API settings for the Todos API, go to the **Permissions** tab and add `read:todos` and `read:billing` as permissions, add a description, and press the **+ Add** button to effectively create the permissions.

![Screenshot of API Permissions tab on Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/4KSfabe2W5eQh5TuOF2cts/3ddf1ea4fd1eceadbff80d31ad5eed6c/Screenshot_2025-04-10_at_3.37.04_PM.png)

With the permissions in place, the Todos API is created and configured within Auth0. You need to give the Todos API the information from Auth0.

Open the Todos API project in your preferred code editor, set configuration values to connect it to the API you just created in the Auth0 Dashboard, and then deploy it via the Wrangler CLI.

In the root of the Todos API project, create a `.dev.vars` file. With the following format:

```
AUTH0_DOMAIN=
AUTH0_AUDIENCE=urn:todos-api
```

Note that you already have the `AUTH0_AUDIENCE` from when you created your API. Now, you’ll need to fill in the Auth0 Domain.

Whenever a new API is created in the Auth0 Dashboard, you also get a test application that allows you to get access tokens and make requests to your protected API. You can see the test application under [Applications>Applications](https://manage.auth0.com/#/applications).

Now that you are in the Applications section of the Dashboard click on the “*Todos API (Test Application)*”, which will load the settings and copy the **Domain** value. The domain will be used in the next step when we update the Todos API project. 

![Screenshot of Todo API application settings in the Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/1tYPzi9JnFGx0UfzIIU2p9/ea37c64f67666bc254ea05e6aef3d352/Screenshot_2025-04-07_at_1.03.54_PM.png)

Update your `.dev.vars` file to contain the Domain like so:

```
AUTH0_DOMAIN=Your Auth0 domain (e.g., acme.auth0.com)
AUTH0_AUDIENCE=urn:todos-api
```

### Testing the Todos API

With the Todos API configured both in Auth0 and locally, you can make requests to it.

Run the Todos API with the following command:

```
npm run dev
```

This will start the worker and allow you to make requests to the Todos API. 

To get the `access_token` to call the API, on the Auth0 Dashboard go to **Applications > APIs, **click on the** Todos API **then select the **Test** tab. This will give you the cURL command to request the access token.

![Screenshot of Todos API Test Tab](https://images.ctfassets.net/23aumh6u8s0i/3aXJxxBRZP75mib0aGAJyS/22204edc710ede9ae7c7b4a706dbe2d8/Screenshot_2025-04-09_at_1.52.22_PM.png)

In your terminal, run the command from the **Test** tab, and be sure to use the `client_id` and `client_secret` values from Auth0.

```
curl --request POST \
  --url https://dev-aggvwbxi.us.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":".....","client_secret":".....","audience":"urn:todos-api","grant_type":"client_credentials"}'
```

The cURL command will show the response with the access token like below:

```
{
  "access_token": ".......",
  "token_type": "Bearer"
}
```

Next, make a request to the API passing the access token in the Authorization header.

```
curl --request GET \
  --url http://localhost:8788/api/me \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6Im...'
```

On a successful call, you will see the claims of the JWT token in the response.

## Deploy the Todos API to Cloudflare

The Todos API is a Cloudflare Workers project, which means it can process Wrangler commands. With everything you have in place so far, you can use Wrangler to set secrets locally and deploy the API to Cloudflare. Using the terminal, navigate to your project folder and run the following commands:

```
wrangler secret put AUTH0_DOMAIN
wrangler secret put AUTH0_AUDIENCE
```

Now that the secrets are set, you can deploy the Todos API to Cloudflare with the following command:

```
wrangler deploy
```

Now that the Todos API is deployed to Cloudflare and secured by Auth0. Keep the project open as we’ll use the terminal in the next step to configure and deploy the remote MCP server.

## Configure and Deploy the Remote MCP Server

In this step, we will configure the remote MCP server secured with Auth0 and make requests to the Todos API. This includes creating an application for it in the Auth0 Dashboard and deploying it to Cloudflare.

Head back to the Auth0 Dashboard and create a web application by going to [Applications → Applications](https://manage.auth0.com/#/applications). Click **Create Application** and enter the following values:

* For the **Name** field, enter “Remote MCP Server”
* Choose **Regular Web Applications** as the Application Type
* Click the **Create** button

![Create Application Modal in Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/3HJs03fVbMD1dRZzGpcLGh/efa94e5434af3d0bc12dfd7565eae4fd/Screenshot_2025-04-07_at_1.53.58_PM.png)

Next, we will configure the callback URL, which is the URL to which the application will be redirected back to the caller after the user authenticates. To set this, head to the MCP Server application Settings, scroll to **Allowed Callback URLs** in the **Application URIs** section and add the following URL.

```
http://localhost:8788/callback
```

> *Note:* This URL will change when you deploy it to production. 

![Application URIs in application settings on Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/3VygdrL3LQBItkNhTVy7v7/fc558fd1a2492454302948c7c3d584e0/Screenshot_2025-04-10_at_4.10.52_PM.png)

Next up is creating a [Cloudflare Workers KV](https://developers.cloudflare.com/kv/) namespace. This namespace is used by the remote MCP server and `workers-oauth-provider` to handle authorization requests.

To create a **KV namespace** with Wrangler, in the terminal, run the following command:

```
wrangler kv namespace create "OAUTH_KV"
```

Open the Remote MCP Server project in your code editor and paste the resulting values in the existing `wrangler.jsonc` file using the format below:

```js
//wrangler.jsonc

{
  "kv_namespaces": [
    {
      "binding": "OAUTH_KV",
      "id": "<BINDING_ID>"
    }
  ]
}
```

Now that the KV namespace has been created, the next step is to update configuration values for Wrangler to deploy the remote MCP server to Cloudflare. To configure the application you’ll need a few values from your application settings in the Auth0 Dashboard. 

Go to [Applications → Applications](https://manage.auth0.com/#/applications), then click on the Remote MCP Server application. There, you can take note of your Auth0 Domain, Client ID, and Client Secret. 

![Auth0 application settings](https://images.ctfassets.net/23aumh6u8s0i/3HJs03fVbMD1dRZzGpcLGh/efa94e5434af3d0bc12dfd7565eae4fd/Screenshot_2025-04-07_at_1.53.58_PM.png)

With the project open in your preferred code editor, create a .dev.vars in the root of the project and add the following values:


```
AUTH0_DOMAIN=Your Auth0 domain (e.g., acme.auth0.com)
AUTH0_CLIENT_ID=The Client ID of the application created in Auth0
AUTH0_CLIENT_SECRET=The Client Secret of the application created in Auth0
AUTH0_AUDIENCE=urn:todos-api
AUTH0_SCOPE=openid email profile offline_access read:todos
NODE_ENV=development
API_BASE_URL=http://localhost:8789
```

### Deploy the MCP Server to Cloudflare

To deploy the remote MCP server to Cloudflare, you first need to set the secrets in Wrangler. To do this, run the following commands:

```
wrangler secret put AUTH0_DOMAIN
wrangler secret put AUTH0_CLIENT_ID
wrangler secret put AUTH0_CLIENT_SECRET
wrangler secret put AUTH0_AUDIENCE
wrangler secret put AUTH0_SCOPE
wrangler secret put API_BASE_URL
```

Once the secrets are set, run the following commands to deploy the MCP Server to Cloudflare.

```
wrangler deploy
```

With the MCP server deployed, we can update the **Allowed Callback URLs** in the Application settings within the Auth0 Dashboard using the deployed MCP server URL using this URL pattern.

To change the Allowed Callback URLs, on the Auth0 Dashboard go to **Applications > Applications**, click on **Settings**, scroll down to **Application URIs** and then add the following URL.

```
https://mcp-auth0-oidc.<your-subdomain>.workers.dev/callback
```

![Auth0 Application URI settings](https://images.ctfassets.net/23aumh6u8s0i/69X5vC9Cna1nKKvicpWTp6/79de976d5939062bc416d46037c550f6/app-urls-callback.png)

This will make sure that after the user authenticates, they will redirect back to the remote MCP server to make calls to the Todos API. With these steps in place, it’s now time to see the remote MCP server in action.

### Test the Remote MCP Server Call

To test making calls to the Todos API, use the Workers AI LLM Playground. Navigate to [Cloudflare’s AI Playground](https://playground.ai.cloudflare.com/) and connect to the Remote MCP Server URL:

```
https://mcp-auth0-oidc.<your-subdomain>.workers.dev/sse
```

Place the URL in the section labeled MCP Servers and click **Connect**.

![Cloudflare AI workers playground](https://images.ctfassets.net/23aumh6u8s0i/1Jwt30QY8vuTTO3ZMNTZXr/5757f0dc6a99600d8ab404eca3f97061/Screenshot_2025-04-10_at_12.33.42_PM.png)

Then you’ll go through the authorization flow; you need to allow access:

![MCP server access request](https://images.ctfassets.net/23aumh6u8s0i/57yVFkdC5sEhBIXEICo9jo/00327fda1167ae4b61f6d64582f78934/auth-request.png)

This will open the browser, have the user authenticate with Auth0, and allow the remote MCP server to access the resources of the Todos API. 

![Auth0 universal login](https://images.ctfassets.net/23aumh6u8s0i/MJX7hQveJh6BYaMKmIHDn/3ef06aa1a2a047c649278d9a0ee37de9/auth-ul.png)

Once permission is given, you can use the LLM to make requests to the MCP server to get information from the Todos API.

![cloudflare AI playground](https://images.ctfassets.net/23aumh6u8s0i/1sO7ZqO9aF7o0VzYEex9VZ/2aa6f63cf1bd01862dde09a0efdfe221/playground.png)

The Todos API allows requests for todos and billing information. Note that the billing information request will fail to show that the LLM can only make requests for information that it has permissions for.

## Configuring a Remote MCP Server in Claude

Now that you understand how to secure a remote MCP server with Auth0 and know how to deploy it to Cloudflare, it might be good to see how to set it up to your favourite MCP Host. Let’s set up your server in Claude Desktop.

Open Claude Desktop, navigate to the Settings then click on Developer and Edit Config. This will show you Claude’s folder on your computer and the file named `claude_desktop_config.json`.

![Claude Desktop Config JSON file](https://images.ctfassets.net/23aumh6u8s0i/4JAy6wjNRtCEVaLIUSJxDv/ebab95cd543009cac72cf1a22fb90e1e/claude-desktop-config-in-folder.png)

Open that file in your favorite editor, and add the following:

```json
{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-auth0-oidc.<your-subdomain>.workers.dev/sse"
      ]
    }
  }
}
```

Remember to update the URL to use your Remote MCP Server URL in the arguments list. This configuration names a “`math`” server that runs with `npx` as command and passes the package `mcp-remote` and the URL as parameters to `npx`.

[The `mcp-remote` package](https://www.npmjs.com/package/mcp-remote) is responsible for connecting an MCP Host with `stdio` like Claude Desktop and Cursor to securely access a Remote MCP Server like the one you just deployed.

Once you save the configuration and restart Claude, you’ll be able to prompt Claude about your list of todos:

![Claude using the Remote MCP Server to show the todos list](https://images.ctfassets.net/23aumh6u8s0i/7HE3fATATP2E1Mxr69V11J/84d1c2267567d095f4b9b5cf5a1bbadb/claude-todos-list-mcp-server-and-api.png)

## Conclusion

In this post we walked through the steps needed to secure a MCP Server with Auth0, and connect it to a third party API. You also learned how to deploy your MCP Server to Cloudflare. The MCP server uses Auth0 as a third party identity provider and allows AI tools to call the protected API on behalf of the user.

Remote MCP Servers offer tools that can make LLMs more convenient and give faster access to the information that matters to users. If you are building with GenAI you should check out our brand new product [Auth for GenAI](http://a0.to/ai-content), to enable AI agents to securely access tools, workflows, and data with fine-grained control and just a few lines of code.

You can take a look at the code that was used in these demos [on GitHub](https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-auth0) to try it out for yourself.


---

_This blog may contain hyperlinks to non-Okta websites that are created and maintained by third parties who are solely responsible for the content on such websites._


Secure and Deploy Remote MCP Servers with Auth0 and Cloudflare

deepu-sasidharan

Deepu is a polyglot developer, Java Champion, and OSS aficionado. He mainly works with Java, JS, Rust, and Golang. He co-leads JHipster and created the JDL Studio and KDash. He's a Staff Developer Advocate at Okta. He is also an international speaker and a published author.

Staff Developer Advocate

Deepu K Sasidharan

Learn how to build a tool-calling AI agent using LangGraph, Vercel AI SDK, and Next.js. Integrate different kinds of tools in them. Use Google services like Gmail, Calendar, and Drive as tools secured using Auth0 Token Vault.

**AI agents** and **Operators** are the next big things in software development. In a [previous post](https://auth0.com/blog/genai-tool-calling-intro/), we discussed how AI agents are taking center stage by seamlessly integrating with multiple digital tools to be more efficient. In this post, we will be building a personal assistant that can use different types of tools. Both simple unauthenticated tools and more complex authenticated tools like Gmail, Calendar, and Google Drive.

If you haven't read the previous post, I recommend you do so before continuing to better understand tool calling in AI agents and how security is currently handled.

<include
  src="LinkCard"
  title="Tool Calling in AI Agents: Empowering Intelligent Automation Securely"
  link="https://auth0.com/blog/genai-tool-calling-intro/"
  description="Discover how AI agents are taking center stage by seamlessly integrating with multiple digital tools to be more efficient. Learn why it is important to secure them."
  img="https://images.ctfassets.net/23aumh6u8s0i/4LrNhImjPcdPVpmCIrhlG9/4efed8dfb26630e6cf48b4a478a1f550/genai-tool-calling-intro.png"
/>

To keep this post focused on tool calling, we will only focus on the AI agent part and not the UI. Each step of the tutorial, including building the UI, can be found as a distinct commit in the [GitHub repository](https://github.com/auth0-samples/auth0-assistant0).

## Technology Stack

We will use a [Next.js](https://nextjs.org/) application called **Assistant 0** as the base, Assistant 0 is an AI personal assistant that consolidates your digital life by dynamically accessing multiple tools to help you stay organized and efficient.

Apart from Next.js, we mainly use the following technologies:

- [LangGraph.js](https://langchain-ai.github.io/langgraphjs/) and [LangChain's JavaScript framework](https://js.langchain.com/docs/introduction/) for building agentic workflows.
- [LangChain community tools](https://js.langchain.com/docs/integrations/tools/).
- Vercel's [AI SDK](https://github.com/vercel-labs/ai) to stream response tokens to the client and display the incoming messages.
- The [Auth0 AI SDK](https://github.com/auth0-lab/auth0-ai-js) and [Auth0 Next.js SDK](https://github.com/auth0/nextjs-auth0) to secure the application and call third-party APIs.

## Prerequisites

> **You will need the following tools and services to build this application**:
>
> - [Bun v1.2](https://bun.sh/) or [NodeJS v20](https://nodejs.org/en/download)
> - An Auth for GenAI account. [Create one](https://a0.to/ai-content).
> - An OpenAI account and API key. [Create one](https://platform.openai.com) or use any [other LLM provider supported by LangChain](https://js.langchain.com/docs/integrations/llms/).
> - A SerpAPI account and API key. [Create one](https://serpapi.com/).
> - A Google account for Gmail, Calendar, and Drive. Preferably a new one for testing.

## Getting Started

First clone [the repository](https://github.com/auth0-samples/auth0-assistant0) and install the dependencies:

```bash
git clone https://github.com/auth0-samples/auth0-assistant0.git
cd auth0-assistant0
git switch step-1 # so that we skip building the UI and get straight to the AI agent

bun install # or npm install
```

Next, you'll need to set up environment variables in your repo's `.env.local` file. Copy the `.env.example` file to `.env.local`. To start you'll just need to add your OpenAI API key.

Now, start the development server:

```bash
bun dev # or npm run dev
```

Open `http://localhost:3000` with your browser to see the result! Ask the agent something, and you'll see a streamed response.

![Assistant 0](https://images.ctfassets.net/23aumh6u8s0i/ePzgV9PLYqmwdsqdJC2VU/3507e783ee8199b6a5599742ef81fed7/assistant-0.png)

### A Peek into the Code

The application is structured as below:

- `src/app`: Contains the Next.js application routes, layout, and pages.
- `src/app/page.tsx`: Home page with chat interface.
- `src/api/chat/route.ts`: API route for handling chat requests. This is where the AI agent is defined.
- `src/components`: UI components used in the application.
- `src/lib`: Services and configurations. This is where custom tools will be defined.
- `src/utils`: Utility functions

Let's take a look at the `src/api/chat/route.ts` file where the AI agent is defined.

```js
// src/api/chat/route.ts
// ...
const AGENT_SYSTEM_TEMPLATE = `You are a personal assistant named Assistant0. 
You are a helpful assistant that can answer questions and help with tasks. 
You have access to a set of tools, use the tools as needed to answer the user's question.`;

export async function POST(req: NextRequest) {
  // ... Process the request and get messages
  // Create a new OpenAI chat model
  const llm = new ChatOpenAI({ model: 'gpt-4', temperature: 0 });
  const tools = [];
  // Use a prebuilt LangGraph agent.
  const agent = createReactAgent({
    llm,
    tools,
    messageModifier: new SystemMessage(AGENT_SYSTEM_TEMPLATE),
  });
  // Stream back all generated tokens and steps from their runs.
  const eventStream = agent.streamEvents({ messages }, { version: 'v2' });
  // Log tool calling data. Only in development mode
  const transformedStream = logToolCallsInDevelopment(eventStream);
  // Adapt the LangChain stream to Vercel AI SDK Stream
  return LangChainAdapter.toDataStreamResponse(transformedStream);
}
```

The route uses a prebuilt LangGraph agent and OpenAI chat model. No tools are defined yet; we will add them in the next section.

Here is a high-level architecture of the application with the tools we will be adding in this post.

![Assistant 0 architecture](https://images.ctfassets.net/23aumh6u8s0i/6ZTtsivmBOPUmKGWx479Xm/d8d90c3bf3f24f1c8ce99ff703a1ba7d/architecture.jpg)

Now that the base application is running, let's start building our personal assistant with tool-calling capabilities.

## Add Tools to the Assistant

If you recall the previous post, we discussed authenticated and unauthenticated tools. Let's start with an unauthenticated tool and then proceed to add more complex tools like Gmail, Calendar, and Google Drive.

### Add a Calculator Tool

We will start with a simple calculator tool from LangChain community tools to perform basic arithmetic operations.

Install the `@langchain/community` package.

```bash
bun add @langchain/community # or npm i @langchain/community
```

Update the `src/api/chat/route.ts` file with the following code.

```js
// src/api/chat/route.ts
import { Calculator } from '@langchain/community/tools/calculator';
// ...
export async function POST(req: NextRequest) {
  // ...
  const tools = [new Calculator()];
  // ...
}
```

It's that simple! Now try asking the assistant to perform some calculations. For example, `what is (2+56) x 200`. You should see the answer in the UI. If you check the console where Next.js dev server (`bun dev`) is running, you should see the tool calling data like below.

```bash
Tool calls state: {
  "call_E3Za9klJcJ5TADWiMj8XfjdB": {
    "name": "calculator",
    "args": "{\n  \"input\": \"(2+56) * 200\"\n}"
  }
}
 POST /api/chat 200 in 8382ms
```

### Add a Web Search Tool

Now let's add a web search tool to search the web for information. Let's use [SerpAPI](https://serpapi.com/) for this. It's an authenticated tool. But since this is going to be API usage and not a user impersonation, we can simply use an API key.

First, get an API key from SerpAPI and add that to your `.env.local` file.

```bash
SERPAPI_API_KEY=your-api-key
```

Now, update the `src/api/chat/route.ts` file with the following code.

```js
// src/api/chat/route.ts
import { SerpAPI } from '@langchain/community/tools/serpapi';
// ...
export async function POST(req: NextRequest) {
  // ...
  const tools = [new Calculator(), new SerpAPI()];
  // ...
}
```

Again, quite simple! Now try asking the assistant to search the web for information. For example, `What is the top 10 news today?`. You will see the response in the UI.

![Assistant 0 web search](https://images.ctfassets.net/23aumh6u8s0i/h4hWDQwBBTUiDh6gdaVET/137647c87dd51c6cc34ec0a44d6e453d/assistant-0-web-search.png)

If you check the console, you should see the tool calling data like the one below.

```bash
Tool calls state: {
  "call_e8vqAPW45vMsUbFiIF9SW5Yn": {
    "name": "search",
    "args": "{\n  \"input\": \"top 10 news today\"\n}"
  }
}
 POST /api/chat 200 in 15443ms
```

This corresponds to the `step-2` branch in case you want to double-check your code.

```bash
git switch step-2
```

### Add Gmail Tools

Now, let's get into business. I know you are here for this part, not to learn about adding calculators and web search tools. But before we can add a Gmail tool, we need to add Auth0 authentication to the application since we will be using Auth0's [Token Vault](https://auth0.com/docs/secure/tokens/token-vault) feature to get access tokens to call the Gmail API via a tool.

#### Add Auth0 Authentication

First, let's add Auth0 as the authentication provider to the application.

Follow the [Auth0 Next.js quickstart guide](https://auth0.com/ai/docs/user-authentication) to set up the application.

> If you want to create the Auth0 application manually, create a new application (Type: **Regular Web App**, Callback URL: `http://localhost:3000/auth/callback`) and get the **client ID** and **client secret**.

Update the `.env.local` file with credentials, and create the `src/lib/auth0.ts` and `src/middleware.ts` files.

If you want to skip to the next step, check out the `step-3` branch. The [full changelog for this step is on GitHub](https://github.com/auth0-samples/auth0-assistant0/commit/9a6db1ec49511afa7c361080c3f5a1854ee8efe5).

```bash
git switch step-3
```

#### Configure Auth0 for Gmail

To use Gmail API with Auth0 via a Google Social Connection, you need to do the following:

- Create Google OAuth 2.0 credentials
- Configure Gmail social connection in Auth0

You can follow the [Google Sign-in and Authorization](https://auth0.com/ai/docs/google-sign-in-and-auth) guide from Auth0 to configure this.

#### Add Gmail Search Tool

We can add Gmail tools now that we have Auth0 authentication in place. Let's start with a Gmail search tool. This tool will allow the assistant to search for emails in the user's Gmail account.

First, we need to get an access token for the Gmail API. We can get this using the [Auth0 Token Vault](https://auth0.com/docs/secure/tokens/token-vault) feature.

Update `src/lib/auth0.ts` with the following code.

```js
// src/lib/auth0.ts
// ...
export const auth0 = new Auth0Client({
  // this is required to get federated access tokens from services like Google
  authorizationParameters: {
    access_type: 'offline',
    prompt: 'consent',
  },
});

export const getGoogleAccessToken = async () => {
  const { token } = await auth0.getAccessTokenForConnection({
    connection: 'google-oauth2',
  });
  return token;
};
```

Install the `googleapis` package.

```bash
bun add googleapis # or npm i googleapis
```

Import the `GmailSearch` tool from LangChain community tools and update the `src/api/chat/route.ts` file with the following code.

```js
// src/api/chat/route.ts
import { GmailSearch } from '@langchain/community/tools/gmail';
import { getGoogleAccessToken } from '@/lib/auth0';
// ...
export async function POST(req: NextRequest) {
  // ...
  // Update the LLM model to gpt-4o-mini to support a larger context window
  const llm = new ChatOpenAI({
    model: 'gpt-4o-mini',
    temperature: 0,
  });
  // Get the access token via Auth0
  const accessToken = await getGoogleAccessToken();
  // Provide the access token to the Gmail tools
  const gmailParams = {
    credentials: { accessToken },
  };
  const tools = [new Calculator(), new SerpAPI(), new GmailSearch(gmailParams)];
  // ...
}
```

We are all set! Now try asking the assistant to search for emails. For example, `What is the latest unread email?`. You should see the response in the UI.

![Assistant 0](https://images.ctfassets.net/23aumh6u8s0i/14n2drq2woolLeJybBMWk6/3bbc575f92493dc2322f485a6b4f4ac9/assistant-0-gmail-search.png)

If you check the console, you should see the tool calling data like the one below.

```bash
Tool calls state: {
  "call_rCzcZRjueyD8p2kzTmeZMiSK": {
    "name": "search_gmail",
    "args": "{\"query\":\"is:unread\",\"maxResults\":1,\"resource\":\"messages\"}"
  }
}
 POST /api/chat 200 in 10892ms
```

#### Add Gmail Draft Tool

We will add a Gmail draft tool next. This tool will allow the assistant to draft emails on behalf of the user.

Update the `src/api/chat/route.ts` file with the following code.

```js
// src/api/chat/route.ts
import { GmailDraft } from '@langchain/community/tools/gmail';
// ...
export async function POST(req: NextRequest) {
  // ...
  const tools = [
    new Calculator(),
    new SerpAPI(),
    new GmailSearch(gmailParams),
    new GmailDraft(gmailParams),
  ];
  // ...
}
```

Now, ask the assistant to draft an email. For example, `Draft an email to John Doe about the meeting tomorrow.` You should see the response in the UI.

![Assistant 0](https://images.ctfassets.net/23aumh6u8s0i/hWz4f6iUXTacbCNoqxwLz/c16c70d786027012b4c4944639339999/assistant-0-gmail-draft.png)

If you check the console, you should see the tool calling data like the one below.

```bash
Tool calls state: {
 "call_pPAk6rFYJSSyAuYkNWFf5KYX": {
   "name": "create_gmail_draft",
   "args": "{\"message\":\"Hi John,\\n\\nI hope this message finds you well. I wanted to … [Your Name]\",\"to\":[\"john.doe@example.com\"],\"subject\":\"Meeting Reminder\",\"cc\":[],\"bcc\":[]}"
 }
}
 POST /api/chat 200 in 7594ms
```

You can find the [full changelog of these two steps on GitHub](https://github.com/auth0-samples/auth0-assistant0/commit/ae2dd28b2fd2248d1d9ca76bd77269ea75817379).

This corresponds to the `step-4` branch in case you want to double-check your code.

```bash
git switch step-4
```

## Learn more about AI Agents and Auth for GenAI

You have successfully built an AI personal assistant that can search the web, search your emails, and draft emails. In the next chapter, we will add more tools like User Info, Google Calendar, Google Drive, and Slack to the assistant.

This tutorial is part of a series of posts on tool-calling Agents with [Auth for GenAI](https://a0.to/ai-content), we learned how to add tools to an AI agent and how to secure them using Auth0.

Sign up for [Auth for GenAI in Developer Preview](https://a0.to/ai-content).

Before you go, we have some great news to share: we are working on more content and sample apps in collaboration with amazing GenAI frameworks like [LlamaIndex](https://www.llamaindex.ai/), [LangChain](https://www.langchain.com/), [CrewAI](https://www.crewai.com/), [Vercel AI](https://vercel.com/ai), and [GenKit](https://firebase.google.com/docs/genkit). [Auth for GenAI](https://auth0.com/blog/introducing-auth-for-genai-launching-identity-for-ai-agents/) is our new product to help you protect your user's information in GenAI-powered applications. Make sure to join the [Auth0 Lab Discord server](http://a0.to/auth0-lab-discord) to hear more and ask questions.


Build an AI Assistant with LangGraph, Vercel, and Next.js: Use Gmail as a Tool Securely

Generative AI is everywhere, and since not every user has access to all data, learn how to use retrieval-augmented generation with fine-grained authorization to ensure that private information stays private.

Build Trustworthy AI: Implementing Access Control for RAG Systems Using FGA

Michelle Agroskin

Michelle Agroskin is a Product Marketing Manager for Okta. She leads the Customer Identity AI, Authorization, and Consumer portfolios, driving go-to-market strategy, messaging, launches, and strategic growth initiatives.

She lives in NYC and in her free time, loves to travel the world and try new restaurants!

Product Marketing Manager, Customer Identity Cloud

Auth0’s latest features enhance user experience with secure, customizable logins, flexible authentication, and improved security—without compromising convenience.

Customer expectations are higher than ever. They want security, convenience, and personalization, all without friction. Businesses need to deliver seamless experiences while keeping user data safe. The challenge? Balancing security with ease of access.

At Auth0, we believe you shouldn’t have to choose between security and experience. That’s why we’re introducing innovations that strengthen security and improve user experience—before, at, and after login.

## Powerful New Features for Secure, Seamless Login

Today’s businesses need to build trust with their users. Customers *expect* engaging experiences, convenient journeys, and secure digital platforms. Before they give you their business, they need to know that you can cater to their unique needs, provide ease of use across multiple channels, and protect their data and sensitive information. When security and user experience are seamlessly integrated, customers engage more, businesses grow, and digital experiences become effortless. And that starts with getting identity right. 

> We’ve updated the authentication journey to help businesses deliver trusted, customized experiences while keeping users safe.

#### **Before login**: greater flexibility with Tenant Access Control

**Security starts before users even log in. **Tenant Access Contro**l (Generally Available, March 2025) helps protect applications and APIs from threats like denial-of-service attacks. Stopping lousy traffic before it reaches your applications prevents disruptions and keeps them running. This feature allows organizations to create granular policies to manage access and mitigate threats, giving them more control over protecting their applications and users.

#### **At login**: Advanced Customization for Universal Login

**The login box is often the first interaction users have with your brand and the one they repeatedly return to as they continue engaging with it. Now, with **Advanced Customization for Universal Login** (Early Access, February 2025), businesses can control every piece of their login experience while leveraging Auth0’s security and built-in authentication process. Create pixel-perfect experiences and tailor every detail to match your brand with the same built-in security Auth0 is known for. 

#### **After login**: strengthen security

**Security doesn’t stop after users are logged in. We’re introducing key enhancements to secure the entire customer journey:

 * **FAPI 2 Certification **(Achieved, March 2025) strengthens API security with financial-grade protections that prevent transaction tampering and data leaks within our Highly Regulated Identity product.
 * **Client-initiated backchannel Authentication** (Limited Early Access, Generally Available Q2 2025) enables a client application (e.g., call center system, POS terminal, autonomous AI agent) to initiate the authentication process on behalf of the customer, making authentication easier.
 * **Native to Web SSO** (Early Access, April 2025) keeps users signed in as they move between mobile and web apps, eliminating unnecessary logins (and frustrated customers!).

## Identity Is the Key to Better Experiences 

In the past, businesses struggled with trade-offs, prioritizing security at the expense of user experience or vice versa. Modern identity removes that compromise, ensuring that security enhances, rather than hinders, customer experience.

Businesses that get identity right can deliver effortless logins, personalized interactions, and enterprise-grade security without slowing growth. These latest innovations make it easier than ever to:

* Protect against fraud and unauthorized access
* Build seamless, branded login experiences
* Maintain compliance with industry standards
* Enable flexible, secure authentication
* Keep users signed in across platforms

## Get Started Today

Auth0 makes identity **simple**, **scalable**, and more **secure.** These latest innovations help businesses stay ahead by offering users the frictionless, secure experiences they expect.

> Stop building identity from scratch. Start building with Auth0.

Learn more about these updates in our [documentation](https://auth0.com/docs/get-started) or [contact our team](https://auth0.com/contact-us) today.

_Any products, features, functionalities, certifications, authorizations, or attestations referenced in this material that are not currently generally available or, have not yet been obtained, or are not currently maintained may not be delivered or obtained on time or at all. Product roadmaps do not represent a commitment, obligation, or promise to deliver any product, feature, functionality, certification, or attestation, and you should not rely on them to make your purchase decisions._

Better User Experiences, Stronger Security

I stream, blog, and make youtube videos about tech stuff. I love coding, I love AI, and I love building stuff!

Juan Cruz Martinez

Discover the Model Context Protocol (MCP) and its authorization mechanisms. Learn how to use API keys, OAuth 2.1 implementation, and best practices for secure LLM API connections.

An Introduction to MCP and Authorization

andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Learn how to enable self-subscription in your B2B SaaS application and automate the Organization creation process using the Auth0.NET SDK.

Enable Self-Subscribing Model in Your Blazor B2B SaaS Application

Sam4-square

I'm an Identity nerd with many years of experience as a developer and advocate. I love explaining complex topics clearly and understandably. You can find me on stage at developer events worldwide or simply having great conversations in the hallway. Google has recognized me as a Google Developer Expert (GDE) in the domains of Web Technologies, Security, Privacy, Payments, and Identity.

Sam Bellen

Supercharge your Auth0-issued access tokens with information, like organizations a user belongs to, from your Auth0 FGA decision engine.

Auth0 supports Roles and Permissions and allows you to add users' permissions to your access tokens with a convenient toggle in the dashboard. But what if you’re using a more fine-grained solution to make access control decisions, like [Auth0 FGA](https://a0.to/auth0-fga-content) or its open-source counterpart, [OpenFGA](https://a0.to/fga-content)?

Actions are our way of offering developers flexibility. There are many different use cases for Auth0 Actions, and enriching an access or ID token is one of them. In this blog post, we’ll explore how we can add some relevant user data from our Auth0 FGA decision engine to the access tokens issued by our Auth0 tenant so that we can use that data in our application logic.

## Prerequisites

For this blog post, we assume you are familiar with either Auth0 FGA or OpenFGA and have an instance up and running. If you’d like to follow along, you can use the following model and tuples to set up a test store, or you could adapt the code for our Auth0 action later to reflect your use case.

> If you are unfamiliar with Auth0 FGA, OpenFGA, or how to get started, read [this blog](https://auth0.com/blog/fine-grained-access-control-with-okta-fga-nextjs/) post to learn more.

## The OpenFGA Authorization Model

Our [model](https://openfga.dev/docs/getting-started/configure-model) will contain a “user,” an “organization,” and a “document” type. An organization can have admins who are defined users and members who are either directly defined users or any user who’s already an admin for the organization. One or more organizations can own documents, and access rights are determined by the “doc_creator” and “doc_admin” relations from these organizations.

```
model
schema 1.1

type user

type organization
relations
    define admin: [user]
    define member: [user] or admin
    define doc_creator: [user] or member
    define doc_admin: [user] or admin

type document
relations
    define owner: [organization]
    define can_create: doc_creator from owner
    define can_delete: doc_admin from owner
```

### OpenFGA Test Tuples

These are [the tuples](https://openfga.dev/docs/getting-started/update-tuples) I’ve added to our Auth0 FGA Store. The ``auth0|62...7f`` is a user identifier within Auth0 and will be part of the Access Token as the `sub` claim. We’ll use these user IDs in our action code to look up all organizations belonging to the current user.

```js
[
    {
      "object":"organization:devrel",
      "relation":"admin",
      "user":"user:auth0|62...7f"
    },
    {
      "object":"organization:openfga",
      "relation":"member",
      "user":"user:auth0|62...7f"
    }  
]
```

## Let’s Write Our Auth0 Action

We can create our [Action](https://auth0.com/features/actions) from the Library page under the Actions menu item. Once we’ve navigated to this page, click the “Create Action” button in the top-right corner. This will allow us to install an action from the marketplace, start from an existing template, or write one from scratch. We’ll choose “Choose a template”, as there’s a template available that can serve as a solid basis from which to start.

![Let’s Write Our Auth0 Action](https://images.ctfassets.net/23aumh6u8s0i/6MUa1wOTUXVfJjelvLvUNT/d006cd1500a5dd4531ba4b6f0e9190a5/enrich-auth0-access-tokens-with-auth0-fga-data_01.png)

On the next page, select the “Enrich profile” use case and click on the “Add Email to Access Token” template. This template will add an email address to your access tokens, but we’ll adapt it to add organizations from Auth0 FGA instead.

![Template for Actions](https://images.ctfassets.net/23aumh6u8s0i/4NDnN6YTO3fMSBNBGUfYXh/ff765bc5ef61b437d2b8862cda074bc3/enrich-auth0-access-tokens-with-auth0-fga-data_02.png)

You can now preview the code from the template and click on the “Use This Template” button to install it. The following popup will ask you to give a name to the new action. We will leave the “post-login” trigger and node runtime as is and click “Create”.

![Add Email to Access Token](https://images.ctfassets.net/23aumh6u8s0i/3UhXvF3kmvyW5JuqLILbHn/4f2c28ffb2af2d164ba3bdc5ed2bf9a9/enrich-auth0-access-tokens-with-auth0-fga-data_03.png)

![Create Action](https://images.ctfassets.net/23aumh6u8s0i/6JWXbwZJVcgnltt0oI7JXM/c1a7905d5d73d68f6964bc7798493d17/enrich-auth0-access-tokens-with-auth0-fga-data_04.png)

### Namespace our custom claim

The [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#AdditionalClaims) recommends adding a namespace to [custom claim](https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims#namespaced-guidelines) names. The first few lines of code in our `onExecutePostLogin` function do just that. They check for a secret called `namespace` and ensure that it ends with a trailing slash.

We can add the namespace to the secrets by clicking on the Key icon in the left-side menu of the Action editor and clicking on the “Add Secret” button. Namespaces are usually a URI, so we will add `https://example.com` as a `NAMESPACE` secret. Feel free to change this to a more appropriate namespace.

### Install and configure the OpenFGA SDK

The Actions editor also conveniently allows us to install packages from NPM. We can add the OpenFGA SDK by clicking on the box icon on the left side and clicking on the “Add dependency” button. The package name will be `@openfga/sdk`, and the version can remain “latest”. This will install the [`@openfga/sdk`](https://www.npmjs.com/package/@openfga/sdk) package so we can import and use it in the Action codebase.

Add the following line to the top of the Action’s codebase:

```js
const { OpenFgaClient, CredentialsMethod } = require('@openfga/sdk');
```

Now that we’ve imported the OpenFGA client, let’s create a new instance and configure the credentials. 

```js
const fgaClient = new OpenFgaClient({
    apiUrl: event.secrets.FGA_API_URL,
    storeId: event.secrets.FGA_STORE_ID,
    authorizationModelId: event.secrets.FGA_MODEL_ID,  // Optional, by default it will use the latest model
    credentials: {
        method: CredentialsMethod.ClientCredentials,
        config: {
            apiTokenIssuer: event.secrets.FGA_API_TOKEN_ISSUER,
            apiAudience: event.secrets.FGA_API_AUDIENCE,
            clientId: event.secrets.FGA_CLIENT_ID,
            clientSecret: event.secrets.FGA_CLIENT_SECRET,
        }
    }
});
```

It is a good idea to create a new authorized client through the [Auth0 FGA dashboard’s](https://dashboard.fga.dev/) settings page for us to use in the Actions editor. Once you’ve created this new client, you can add its Client ID and secret to the Actions editor’s secrets, together with all other necessary configuration parameters. 

Here’s a quick overview of what they should look like. Be sure to change the `eu1` region in the API URL and Audience to `us1` or `au1` depending on which jurisdiction you choose when creating your store.

```
FGA_API_URL=https://api.eu1.fga.dev
FGA_API_AUDIENCE=https://api.eu1.fga.dev/
FGA_API_TOKEN_ISSUER=auth.fga.dev
FGA_CLIENT_ID=0U...4q
FGA_CLIENT_SECRET=pB...kf
FGA_STORE_ID=01...1M
FGA_MODEL_ID=01...9C
```

### List all assigned organizations from Auth0 FGA

Auth0 FGA exposes a `list-objects` endpoint that can return a set of objects of a particular type assigned to a user, such as all organizations for which a user is a member. This will also consider all indirect relationships, such as when a user is a member because they are an admin for a specific organization.

To use this endpoint, the OpenFGA client we just created exposes a `listObjects` method where we can pass a user, relation, and object type. Notice that we pass along the `user_id` from `event.user`. This is the actual ID of the user who is currently trying to log in.

Add the following snippet below the OpenFGA client initialization code in our Action.

```js
const {objects} = await fgaClient.listObjects({
    user: `user:${event.user.user_id}`,
    relation: "member",
    type: "organization",
})
```

### Add the Assigned Organizations to the Access Token

The last thing left to do is to add the returned organization to our access token. We can re-purpose the last existing line from the template by adding the email to add our organizations instead. With some minimal changes, that code will look something like this.

```js
api.accessToken.setCustomClaim(
  namespace + 'organizations', 
  objects.map(organization => organization?.replace('organization:', ''))
);
```

The `list-objects` endpoint returns the object type together with the actual objects, so in our case, we can strip `organization:` from each returned organization. This will keep the organization names, which we can add to the custom claim.

### Putting it All Together

If we add some error handling, we’ll end up with an action that should look like this. 

```js
const { OpenFgaClient, CredentialsMethod } = require("@openfga/sdk");

exports.onExecutePostLogin = async (event, api) => {
  let namespace = event.secrets.NAMESPACE || "";
  if (namespace && !namespace.endsWith("/")) {
    namespace += "/";
  }

  try {
    const fgaClient = new OpenFgaClient({
      apiUrl: event.secrets.FGA_API_URL,
      storeId: event.secrets.FGA_STORE_ID,
      authorizationModelId: event.secrets.FGA_MODEL_ID,
      credentials: {
        method: CredentialsMethod.ClientCredentials,
        config: {
          apiTokenIssuer: event.secrets.FGA_API_TOKEN_ISSUER,
          apiAudience: event.secrets.FGA_API_AUDIENCE,
          clientId: event.secrets.FGA_CLIENT_ID,
          clientSecret: event.secrets.FGA_CLIENT_SECRET,
        },
      },
    });

    const { objects } = await fgaClient.listObjects({
      user: `user:${event.user.user_id}`,
      relation: "member",
      type: "organization",
    });

    api.accessToken.setCustomClaim(
      namespace + "organizations",
      objects.map((organization) => organization?.replace("organization:", ""))
    );
  } catch (error) {
    api.access.deny("Could not list organizations");
  }
};
```

The issued access token will now have a custom `https://example.com/organizations` claim, and when decoded, it can look something like the following:

```js
{
  "iss": "https://<your-tenant>.eu.auth0.com/",
  "sub": "auth0|62...7f",
  "aud": [
    "https://example.com",
    "https://<your-tenant>.auth0.com/userinfo"
  ],
  "iat": 1740579493,
  "exp": 1740665893,
  "scope": "openid profile email address phone",
  "jti": "rDk6D9GigyYTfi2WN492AB",
  "client_id": "T1...aW",
  "https://example.com/organizations": [
    "devrel",
    "openfga"
  ],
}
```

## Wrapping Up

In this article, we’ve gone through the steps to create a new Auth0 Action. This action will run every time a user logs into our application and adds all organizations that the user is a member of to the Access Token. We can use this information in our backend systems by decoding the Access Token, which will be a JSON Web Token, and looking for our custom claim `https://example.com/organizations`.

The action does the following steps to accomplish this:

* Import the [OpenFGA Node.js SDK](https://github.com/openfga/js-sdk).
* Make sure we have a namespace configured and that it ends with a slash.
* Create a new instance of the imported OpenFGA client.
* Use this client to list all organizations assigned to the user by using the exposed `listObjects()` method.
* Return the list of organizations as a custom claim prepended by our namespace in our Access Tokens.


Enrich Auth0 Access Tokens with Auth0 FGA Data

Learn how to use Auth0 FGA to secure your LlamaIndex RAG agent on Node.js.

Generative Artificial Intelligence (GenAI) has massively changed the software landscape and AI agents are all the rage now. AI agents can also be used for complex Retrieval-Augmented Generation (RAG) systems where additional context can be provided to the Large Language Model (LLM) by retrieving updated or domain-specific data from a database or a search engine. This technique can reduce hallucinations and improve accuracy of the LLM. AI agents can also use RAG as a tool to perform complex workflows.

[Sensitive Information Disclosure](https://genai.owasp.org/llmrisk/llm022025-sensitive-information-disclosure/) is a common issue that plagues RAG-based systems. We don't want the LLM to accidentally access or expose sensitive data from a database. Traditional Role-Based Access Control (RBAC) systems are not enough to secure RAG applications and agents. This is where [Fine-Grained Authorization (FGA)](https://fga.dev/) shines as a solution.

If you would like to learn the basics of using FGA for RAG, check out this blog post on [RAG and Access Control: Where Do You Start?](https://auth0.com/blog/rag-and-access-control-where-do-you-start/).

<include
  src="LinkCard"
  title="RAG and Access Control: Where Do You Start?"
  link="https://auth0.com/blog/rag-and-access-control-where-do-you-start/"
  description="Learn how to get started with Auth0 FGA for a RAG application."
  img="https://images.ctfassets.net/23aumh6u8s0i/79NCborGcFIrAMeaV7G8oi/f9c588c2d05f0828d447e72e1fe825cc/Latam01.jpg"
/>

In this tutorial, we will build a simple RAG agent using the [LlamaIndex.TS](https://ts.llamaindex.ai/), which is the JavaScript version of the popular [LlamaIndex](https://www.llamaindex.ai/) framework, and secure it using Auth0 FGA.

## Prerequisites

> **This tutorial was created with the following tools and services**:
>
> - [NodeJS v20](https://nodejs.org/en/download)
> - An Auth0 FGA account. [Create one](https://dashboard.fga.dev).
> - An OpenAI account and API key. [Create one](https://platform.openai.com).

## What Does LlamaIndex Do?

[LlamaIndex](https://www.llamaindex.ai/) is a flexible framework for building AI agents and RAG applications. It provides Python and JavaScript SDKs to interact with a variety of LLMs and databases. LlamaIndex can be used to build AI agents and workflows that can interact with the user, retrieve data from a database, and generate responses using an LLM. It also provides tools like [LlamaParse](https://www.llamaindex.ai/llamaparse) to transform unstructured data into LLM-optimized formats and LlamaCloud to store and retrieve LLM-ready data from the cloud.

## Set up a LlamaIndex RAG Application

To get started, clone the [**auth0-ai-samples**](https://a0.to/auth0-ai-samples) repository from GitHub:

```bash
git clone https://github.com/auth0-samples/auth0-ai-samples.git
cd auth0-ai-samples/authorization-for-rag/llamaindex-agentic-js
# install dependencies
npm install
```

The application is written in TypeScript for the Node.js platform and is structured as follows:

- `index.ts`: The main entry point of the application that defines the RAG pipeline.
- `assets/docs/*.md`: Sample markdown documents that will be used as context for the LLM. We have public and private documents for demonstration purposes.
- `scripts/fga-init.ts`: Utility to initialize the Auth0 FGA authorization model.

Let us look at the important bits and pieces before we run the application.

### RAG pipeline

The RAG pipeline is defined in `index.ts`. It uses LlamaIndex Agents to interact with the underlying LLM and retrieve data from the database. The pipeline is defined as follows:

```typescript
/** index.ts **/
const user = 'user1';
// 1. Read and load documents from the assets folder
const documents = await new SimpleDirectoryReader().loadData('./assets/docs');
// 2. Create an in-memory vector store from the documents using the default OpenAI embeddings
const vectorStoreIndex = await VectorStoreIndex.fromDocuments(documents);
// 3. Create a retriever that uses FGA to gate fetching documents on permissions.
const retriever = FGARetriever.create({
  // Set the similarityTopK to retrieve more documents as SimpleDirectoryReader creates chunks
  retriever: vectorStoreIndex.asRetriever({ similarityTopK: 30 }),
  // FGA tuple to query for the user's permissions
  buildQuery: (document) => ({
    user: `user:${user}`,
    object: `doc:${document.metadata.file_name.split('.')[0]}`,
    relation: 'viewer',
  }),
});
// 4. Create a query engine and convert it into a tool
const queryEngine = vectorStoreIndex.asQueryEngine({ retriever });
const tools = [
  new QueryEngineTool({
    queryEngine,
    metadata: {
      name: 'zeko-internal-tool',
      description: `This tool can answer detailed questions about ZEKO.`,
    },
  }),
];

// 5. Create an agent using the tools array and OpenAI GPT-4 LLM
const agent = new OpenAIAgent({ tools });

// 6. Query the agent
let response = await agent.chat({ message: 'Show me forecast for ZEKO?' });
```

Here is a visual representation of the RAG architecture

![LlamaIndex RAG architecture](https://images.ctfassets.net/23aumh6u8s0i/lGssMbzaSU4J0zXG4bFcC/21f2abbda55a13640350d637609469f7/llamaindex-rag.jpg)

### FGA retriever

The `FGARetriever` class filters documents based on the authorization model defined in Auth0 FGA and will be available as part of the [**auth0-ai-js**](https://github.com/auth0-lab/auth0-ai-js) SDK. This retriever is a post-search filter ideal for scenarios where you already have documents in a vector store and want to filter the vector store results based on the user's permissions. Assuming the vector store already narrows down the documents to a few, the FGA retriever will further narrow down the documents to only the ones to which the user has access.

The alpha version of the retriever can be installed using the following command:

```bash
npm install "https://github.com/auth0-lab/auth0-ai-js.git#alpha-2" --save
```

The build query function is used to construct the query to the FGA store. The query is constructed using the user, object, and relation. The user is the user ID, the object is the document ID or the document name, and the relation is the permission that the user must have on the document.

```typescript
buildQuery: (document) => ({
  user: `user:${user}`,
  object: `doc:${document.metadata.file_name.split(".")[0]}`,
  relation: "viewer",
}),
```

### Retrieval Agent

1. The `queryEngine` is created from the vector store index and configured to use our custom FGA retriever. The query engine handles searching through documents and retrieving relevant information based on user queries.

2. The `tools` array contains a `QueryEngineTool` that wraps our query engine. The tool provides a structured interface for the agent to access the query engine's capabilities.

3. The `agent` is created using OpenAI's GPT-4 model and the tools array. The agent acts as an intelligent interface between the user and the tools - it understands natural language queries, determines when to use the query engine tool, and formulates responses based on the retrieved information.

```typescript
/** index.ts **/
const queryEngine = vectorStoreIndex.asQueryEngine({ retriever });
const tools = [
  new QueryEngineTool({
    queryEngine,
    metadata: {
      name: 'zeko-internal-tool',
      description: `This tool can answer detailed questions about ZEKO.`,
    },
  }),
];

// 5. Create an agent using the tools array and OpenAI GPT-4 LLM
const agent = new OpenAIAgent({ tools });
```

## Set up an FGA Store

In the [Auth0 FGA dashboard](https://dashboard.fga.dev/), navigate to **Settings**, and in the **Authorized Clients** section, click **+ Create Client**. Give your client a name, mark all three client permissions, and then click **Create**.

![Create FGA client](https://images.ctfassets.net/23aumh6u8s0i/2KQc8ACR0MDTqftUgUSXpX/5b779bcece07a69ac775de0fc760c208/Uploaded_from_RAG_and_Access_Control__Where_Do_You_Start)

Once your client is created, you’ll see a modal containing Store ID, Client ID, and Client Secret.

Add `.env` file with the following content to the root of the project. Click **Continue** to see the `FGA_API_URL` and `FGA_API_AUDIENCE`.

```
# OpenAI
OPENAI_API_KEY=<your-openai-api-key>

# Auth0 FGA
FGA_STORE_ID=<your-fga-store-id>
FGA_CLIENT_ID=<your-fga-store-client-id>
FGA_CLIENT_SECRET=<your-fga-store-client-secret>
# Required only for non-US regions
FGA_API_URL=https://api.xxx.fga.dev
FGA_API_AUDIENCE=https://api.xxx.fga.dev/
```

[Check the instructions here to find your OpenAI API key](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key).

Next, navigate to **Model Explorer**. You’ll need to update the model information with this:

```text
model
  schema 1.1

type user

type doc
  relations
    define owner: [user]
    define viewer: [user, user:*]
```

Remember to click **Save**.

> Check out [this documentation to learn more about creating an authorization model in FGA](https://docs.fga.dev/modeling).

Now, to have access to the public information, you’ll need to add a tuple on FGA. Navigate to the **Tuple Management** section and click **+ Add Tuple**, fill in the following information:

- **User** : `user:*`
- **Object** : select doc and add `public-doc` in the ID field
- **Relation** : `viewer`

A tuple signifies a user’s relation to a given object. For example, the above tuple implies that all users can view the `public-doc` object.

> Alternatively, you can use the `scripts/fga-init.ts` script to initialize the FGA store with the model and tuple.
> Run the `npm run fga:init` command after setting up the `.env` file.

## Test the Application

Now that you have set up the application and the FGA store, you can run the application using the following command:

```bash
npm start
```

The application will start with the query, `Show me forecast for ZEKO?` Since this information is in a private document, and we haven't defined a tuple with access to this document, the application will not be able to retrieve it. The FGA retriever will filter out the private document from the vector store results and, hence, print a similar output.

```text
The provided context does not include specific forecasts or projections for Zeko Advanced Systems Inc. ...
```

If you change the query to something that is available in the public document, the application will be able to retrieve the information.

Now, to have access to the private information, you’ll need to update your tuple list. Go back to the Auth0 FGA dashboard in the **Tuple Management** section and click **+ Add Tuple**, fill in the following information:

- **User** : `user:user1`
- **Object** : select doc and add `private-doc` in the ID field
- **Relation** : `viewer`

Now click **Add Tuple** and then run the script again:

```bash
npm start
```

This time, you should see a response containing the forecast information since we added a tuple that defines the `viewer` relation for `user1` to the `private-doc` object.

Congratulations! You have run a simple RAG application using LlamaIndex and secured it using Auth0 FGA.

## Learn More about Auth for GenAI, Auth0 FGA and GenAI

In this post, you learned how to secure a LlamaIndex-based RAG application using Auth0's [Auth for GenAI](https://a0.to/ai-content) and [Auth0 FGA](https://fga.dev/). Auth0 FGA is built on top of OpenFGA, which is open-source. We invite you to check out the [OpenFGA code on GitHub](https://a0.to/fga_repo).

Before you go, we have some great news to share: we are working on more content and sample apps in collaboration with amazing GenAI frameworks like [LlamaIndex](https://www.llamaindex.ai/), [LangChain](https://www.langchain.com/), [CrewAI](https://www.crewai.com/), [Vercel AI SDK](https://sdk.vercel.ai/), and [GenKit](https://firebase.google.com/docs/genkit). [Auth for GenAI](https://auth0.com/blog/auth-for-genai/) is our upcoming product to help you protect your user's information in GenAI-powered applications. Make sure to join the [Auth0 Lab Discord server](http://a0.to/auth0-lab-discord) to hear more and ask questions.

Build a Secure RAG Agent Using LlamaIndex and Auth0 FGA on Node.js

Learn how to use Auth0 FGA to secure your LangChain RAG agent on Node.js

Like it or not, Generative Artificial Intelligence (GenAI) has massively changed the software landscape. Retrieval-Augmented Generation (RAG) is a cornerstone of GenAI-powered applications. It is an architecture that improves the accuracy of Large Language Models (LLMs) by providing more context to the model. This is done by retrieving updated or domain-specific data from a database or a search engine. This is a powerful technique that can be used to improve the accuracy of LLMs in a variety of applications.

Security is even more paramount when it comes to RAG-based systems, as we don't want the LLM to accidentally access or expose sensitive data. Traditional Role-Based Access Control (RBAC) systems are not enough to secure RAG applications. This is where [Fine-Grained Authorization (FGA)](https://fga.dev/) comes to the rescue.

If you would like to learn the basics of using FGA for RAG, check out this blog post on [RAG and Access Control: Where Do You Start?](https://auth0.com/blog/rag-and-access-control-where-do-you-start/)

<include
  src="LinkCard"
  title="RAG and Access Control: Where Do You Start?"
  link="https://auth0.com/blog/rag-and-access-control-where-do-you-start/"
  description="Learn how to get started with Auth0 FGA for a RAG application."
  img="https://images.ctfassets.net/23aumh6u8s0i/79NCborGcFIrAMeaV7G8oi/f9c588c2d05f0828d447e72e1fe825cc/Latam01.jpg"
/>

In this tutorial, we will build a simple RAG agent using the [LangChain](https://www.langchain.com/) framework and secure it using Auth0 FGA.

<AmpContent>
<amp-youtube
    data-videoid="u81b6nsDoPA"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>

<NonAmpContent>
<div
  className='embed-container'
  style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;">
    <iframe
      style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
      src='https://www.youtube.com/embed/u81b6nsDoPA'
      frameborder='0' allowfullscreen>
    </iframe>
</div>
</NonAmpContent>


## Prerequisites

> **This tutorial was created with the following tools and services**:
>
> - [NodeJS v20](https://nodejs.org/en/download)
> - An Auth0 FGA account. [Create one](https://dashboard.fga.dev).
> - An OpenAI account and API key. [Create one](https://platform.openai.com).

## Why LangChain?

[LangChain](https://www.langchain.com/) is one of the leading frameworks for building context-aware reasoning applications, including RAG applications. It is open-source and provides a simple API to interact with the underlying LLMs. It supports a variety of LLMs, including OpenAI's GPT models, Google VertexAI, Anthropic, and more. It also provides a simple way to retrieve data from a database or a search engine to provide more context to the LLM. For this tutorial, we will use [LangGraph](https://www.langchain.com/langgraph) from LangChain to build an agentic RAG application. LangGraph is a powerful tool that allows you to build agents that can handle complex tasks, including RAG applications. It provides advanced features like workflows, persisted context, and streaming support.

## Set up a LangGraph RAG application

To get started, clone the [**auth0-ai-samples**](https://a0.to/auth0-ai-samples) repository from GitHub:

```bash
git clone https://github.com/auth0-samples/auth0-ai-samples.git
cd auth0-ai-samples/authorization-for-rag/langgraph-agentic-js
# install dependencies
npm install
```

The application is written in TypeScript for the Node.js platform and is structured as follows:

- `index.ts`: The main entry point of the application that defines the RAG pipeline.
- `assets/docs/*.md`: Sample markdown documents that will be used as context for the LLM. We have public and private documents for demonstration purposes.
- `helpers/read-documents.ts`: Utility to load markdown files as documents.
- `helpers/langchain.ts`: Defines the LangGraph retrieval agent.
- `scripts/fga-init.ts`: Utility to initialize the Auth0 FGA authorization model.

Let us look at the important bits and pieces before we run the application.

### RAG pipeline

The RAG pipeline is defined in `index.ts`. It uses the LangGraph framework to interact with the underlying LLM and retrieve data from the database. The pipeline is defined as follows:

```js
/** index.ts **/
const user = 'user1';
// 1. Read and load documents from the assets folder
const documents = await readDocuments();
// 2. Create an in-memory vector store from the documents for OpenAI models.
const vectorStore = await MemoryVectorStore.fromDocuments(
  documents,
  new OpenAIEmbeddings({ model: 'text-embedding-3-small' }),
);
// 3. Create a retriever that uses FGA to gate fetching documents on permissions.
const retriever = FGARetriever.create({
  retriever: vectorStore.asRetriever(),
  // FGA tuple to query for the user's permissions
  buildQuery: (doc) => ({
    user: `user:${user}`,
    object: `doc:${doc.metadata.id}`,
    relation: 'viewer',
  }),
});
// 4. Convert the retriever into a tool for an agent.
const fgaTool = retriever.asJoinedStringTool();
// 5. The agent will call the tool, rephrasing the original question and
// populating the "query" argument, until it can answer the user's question.
const retrievalAgent = RetrievalAgent.create([fgaTool]);
// 6. Query the retrieval agent with a prompt
const answer = await retrievalAgent.query('Show me forecast for ZEKO?');
```

Here is a visual representation of the RAG architecture:

![LangChain RAG architecture](https://images.ctfassets.net/23aumh6u8s0i/707VuhSJ2FqDBTrQNP6rTl/0fcd90a881441369e1466b109c02686c/langgraph-rag.jpg)

### FGA retriever

The `FGARetriever` class filters documents based on the authorization model defined in Auth0 FGA and will be available as part of the [**auth0-ai-js**](https://github.com/auth0-lab/auth0-ai-js) SDK. This retriever is ideal for scenarios where you already have documents in a vector store and want to filter the vector store results based on the user's permissions. Assuming the vector store already narrows down the documents to a few, the FGA retriever will further narrow down the documents to only the ones that the user has access to. 

The alpha version of the retriever can be installed using the following command:

```bash
npm install "https://github.com/auth0-lab/auth0-ai-js.git#alpha-1" --save
```

The build query function is used to construct the query to the FGA store. The query is constructed using the user, object, and relation. The user is the user ID, the object is the document ID, and the relation is the permission that the user has on the document.

```typescript
buildQuery: (doc) => ({
  user: `user:${user}`,
  object: `doc:${doc.metadata.id}`,
  relation: 'viewer',
}),
```

### Retrieval Agent

The `RetrievalAgent` class configures a LangGraph retrieval agent that uses the FGA retriever tool and an OpenAI model to answer the user's question. The agent will call the tool to get context documents in this case.

```typescript
/** helpers/langchain.ts **/
static create(tools: StructuredToolInterface[]) {
  // Create a retrieval agent that has access to the retrieval tool.
  const retrievalAgent = createReactAgent({
    llm: new ChatOpenAI({ temperature: 0, model: 'gpt-4o-mini' }),
    tools,
    stateModifier: [
      "Answer the user's question only based on context retrieved from provided tools.",
      'Only use the information provided by the tools.',
      'If you need more information, ask for it.',
    ].join(' '),
  });
  return new RetrievalAgent(retrievalAgent);
}
```

## Set up an FGA store

In the [Auth0 FGA dashboard](https://dashboard.fga.dev/), navigate to **Settings**, and in the **Authorized Clients** section, click **+ Create Client**. Give your client a name, mark all three client permissions, and then click **Create**.


![Create FGA client](https://images.ctfassets.net/23aumh6u8s0i/2KQc8ACR0MDTqftUgUSXpX/5b779bcece07a69ac775de0fc760c208/Uploaded_from_RAG_and_Access_Control__Where_Do_You_Start)


Once your client is created, you’ll see a modal containing Store ID, Client ID, and Client Secret.

Add `.env` file with the following content to the root of the project. Click **Continue** to see the `FGA_API_URL` and `FGA_API_AUDIENCE`.

```
# OpenAI
OPENAI_API_KEY=<your-openai-api-key>

# Auth0 FGA
FGA_STORE_ID=<your-fga-store-id>
FGA_CLIENT_ID=<your-fga-store-client-id>
FGA_CLIENT_SECRET=<your-fga-store-client-secret>
# Required only for non-US regions
FGA_API_URL=https://api.xxx.fga.dev
FGA_API_AUDIENCE=https://api.xxx.fga.dev/
```

[Check the instructions here to find your OpenAI API key](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key).

Next, navigate to **Model Explorer**. You’ll need to update the model information with this:

```text
model
  schema 1.1

type user

type doc
  relations
    define owner: [user]
    define viewer: [user, user:*]
```

Remember to click **Save**.

> Check out [this documentation to learn more about creating an authorization model in FGA](https://docs.fga.dev/modeling).

Now, to have access to the public information, you’ll need to add a tuple on FGA. Navigate to the **Tuple Management** section and click **+ Add Tuple**, fill in the following information:

- **User**: `user:*`
- **Object**: select doc and add `public-doc` in the ID field
- **Relation**: `viewer`

A tuple signifies a user’s relation to a given object. For example, the above tuple implies that all users can view the `public-doc` object.

> Alternatively, you can use the `scripts/fga-init.ts` script to initialize the FGA store with the model and tuple.
> Run the `npm run fga:init` command after setting up the `.env` file.

## Test the application

Now that you have set up the application and the FGA store, you can run the application using the following command:

```bash
npm start
```

The application will start with the query, `Show me forecast for ZEKO?` Since this information is in a private document, and we haven't defined a tuple with access to this document, the application will not be able to retrieve it. The FGA retriever will filter out the private document from the vector store results and, hence, print a similar output.

```text
The provided context does not include specific forecasts or projections for Zeko Advanced Systems Inc. ...
```

If you change the query to something that is available in the public document, the application will be able to retrieve the information.

Now, to have access to the private information, you’ll need to update your tuple list. Go back to the Auth0 FGA dashboard in the **Tuple Management** section and click **+ Add Tuple**, fill in the following information:

- **User**: `user:user1`
- **Object**: select doc and add `private-doc` in the ID field
- **Relation**: `viewer`

Now click **Add Tuple** and then run the script again:

```bash
npm start
```

This time, you should see a response containing the forecast information since we added a tuple that defines the `viewer` relation for `user1` to the `private-doc` object.

Congratulations! You have run a simple RAG application using LangChain and secured it using Auth0 FGA.

## Learn more about Auth0 for GenAI, Auth0 FGA and GenAI

In this post, you learned how to secure a LangChain-based RAG application using Auth0's [Auth for GenAI](https://a0.to/ai-content) and [Auth0 FGA](https://fga.dev/). Auth0 FGA is built on top of OpenFGA, which is open-source. We invite you to check out the [OpenFGA code on GitHub](https://a0.to/fga_repo).

Before you go, we have some great news to share: we are working on more content and sample apps in collaboration with amazing GenAI frameworks like [LlamaIndex](https://www.llamaindex.ai/), [LangChain](https://www.langchain.com/), [CrewAI](https://www.crewai.com/), [Vercel AI SDK](https://sdk.vercel.ai/), and [GenKit](https://firebase.google.com/docs/genkit). [Auth for GenAI](https://auth0.com/blog/auth-for-genai/) is our upcoming product to help you protect your user's information in GenAI-powered applications. Make sure to join the [Auth0 Lab Discord server](http://a0.to/auth0-lab-discord) to hear more and ask questions.


Build a Secure LangChain RAG Agent Using Auth0 FGA and LangGraph on Node.js

Learn how to use Okta FGA to secure your LangChain RAG agent in Python.

Retrieval-Augmented Generation (RAG) is a great way to create AI-driven applications that deliver more accurate, context-rich answers. Instead of relying purely on pre-trained knowledge, a RAG system retrieves domain-specific data (like PDFs, knowledge bases, or markdown files) and passes it into a language model. This is *awesome* when your data is public or freely shareable. But what happens if some of that data is *restricted* or *confidential*? That’s where fine-grained authorization comes in!

In this post, we’ll walk through:

1. **Why** authorization is crucial in RAG
2. **What** OpenFGA is, and how it helps you enforce fine-grained permissions
3. **How** to build a secure pipeline that filters out unauthorized documents **before** they reach your language model

## The Challenge of Authorization in RAG Systems

RAG systems retrieve relevant information from large datasets and use that information to enhance the AI model responses. While this functionality is powerful, it raises a significant challenge: **ensuring that each user only accesses the information they are authorized to see**. Authorization must be:

* **Accurate**: Only correct data gets through.
* **Performant**: Works quickly, even with large datasets.
* **Adaptive**: Updates with dynamic organizational changes, role updates, or any changes in the relationship between the information and the users.

A secure RAG system needs to enforce fine-grained access control without sacrificing speed or scalability. Roles might change, projects can be reassigned, and permissions could evolve over time. Handling all this efficiently is key to building a truly secure and robust RAG application.

## Proposed Solution: Secure Retrieval with LangChain, OpenAI, and OpenFGA

The solution employs a workflow that integrates document retrieval, user-specific authorization filtering, and Large Language Model (LLM) response generation.

We’ll build a pipeline that uses:

* **LangChain**: A helpful toolkit for chaining the steps of a RAG pipeline (loading data, embeddings, retrieval, prompting).
* **LLMs** (OpenAI or any other): For both embeddings (similarity search) and text generation.
* **OpenFGA**: A fine-grained authorization service that checks, for each document, if a user has the “can_view” relationship.

### LangChain

LangChain is a library that streamlines building LLM applications by assembling different components—like loading documents, vector stores, and prompt templates. This structure makes it easier to read, maintain, and modify your RAG pipeline.

### LLMs

Although we’ll demonstrate OpenAI’s embeddings and Chat APIs, you can easily replace them with other providers (e.g., Anthropic, LLaMA, or Azure OpenAI). The main tasks here are:

1. **Embedding** documents so you can do similarity searches.
2. **Generating** text from the retrieved documents to answer the user’s query.

### FGA and Okta FGA

**FGA (Fine-Grained Authorization)** is about controlling _who can do what_ with _which resources_, down to an individual level. In a typical role-based system, you might say, “Admins can see everything, and Regular Users can see some subset.” But in a real-world app—especially one that deals with many documents—this might not be flexible enough.

**OpenFGA (and Okta FGA)** addresses this by letting you define authorization _relationships_. The relationships defined in the authorization model can be either direct or indirect. Simply put, direct relationships are directly assigned between a consumer and a resource (we call them user and object) and stored in the database. Indirect relationships are the relationships we can infer based on the data and the authorization model.

If you would like to learn the basics of using FGA for RAG, check out this blog post on [RAG and Access Control: Where Do You Start?](https://auth0.com/blog/rag-and-access-control-where-do-you-start/).

<include
 src="LinkCard"
 title="RAG and Access Control: Where Do You Start?"
 link="https://auth0.com/blog/rag-and-access-control-where-do-you-start/"
 description="Learn how to get started with Okta FGA for a RAG application."
 img="https://images.ctfassets.net/23aumh6u8s0i/79NCborGcFIrAMeaV7G8oi/f9c588c2d05f0828d447e72e1fe825cc/Latam01.jpg"
/>

## Implementation: Step-by-Step

Below is a sample setup in Python. We’ll keep it simple so you can see the big picture. Feel free to adapt for your chosen LLM or a more robust data store.

### Set Up Prerequisites

To follow this tutorial and secure your application, you’ll need the following:

* Python 3.8.1 or newer.
* An Okta FGA account. If you don’t have one, you can [create one for free](https://dashboard.fga.dev/).
* An [OpenAI account and API key](https://platform.openai.com/).

### Download and install the sample code

To get started, clone the[ auth0-ai-samples](https://a0.to/auth0-ai-samples) repository from GitHub:

```
git clone https://github.com/auth0-samples/auth0-ai-samples.git
cd auth0-ai-samples/authorization-for-rag/langchain-python
# Create a virtual env
python -m venv venv
# Activate the virtual env
source ./venv/bin/activate
# Install dependencies
pip install -r requirements.txt
```

The application is written in Python and is structured as follows:

* `main.py` &mdash; The main entry point of the application, and it is where we define the RAG pipeline
* `docs/*.md` &mdash; Sample markdown files to be used as context for the LLM. There are two types of docs, public and private. Private documents are only accessible to certain individuals.
* `helpers/memory_store.py` &mdash; Creates an in-memory vector store that acts as the base retriever in the chain.
* `helpers/read_documents.py` &mdash; Utility to read the markdown files from the `docs` folder.
* `scripts/fga_init.py` &mdash; Utility to initialize the OktaFGA authorization model and sample data.

### RAG Pipeline

The `main.py` file defines the RAG pipeline using `Langchain` to interact with the underlying LLM model and retrieve data from our context. In your project, your data may be sourced from different platforms and systems, make sure you check the proper documentation about [loaders in the Langchain ecosystem](https://python.langchain.com/v0.1/docs/modules/data_connection/).

The following diagram represents the RAG architecture we are defining:

![LangChain RAG architecture](https://images.ctfassets.net/23aumh6u8s0i/4ReiQ2qnjzYRR18KujkHwe/4c4738866ad275b26aed2d7b9c8d3661/langchain-rag.png)

Now let’s talk Python:

```python
class RAG:
    def __init__(self):
        documents = read_documents()
        self.vector_store = MemoryStore.from_documents(documents)
        self.prompt = ChatPromptTemplate.from_template(
            """You are an assistant for question-answering tasks. Use the following pieces of retrieved context to answer the question. If you don't know the answer, just say that you don't know. Use three sentences maximum and keep the answer concise.\\nQuestion: {question}\\nContext: {context}\\nAnswer:"""
        )

        self.llm = ChatOpenAI(model="gpt-4o-mini")

    def query(self, user_id: str, question: str):
        chain = (
            {
                "context": FGARetriever(
                    retriever=self.vector_store.as_retriever(),
                    build_query=lambda doc: ClientBatchCheckItem(
                        user=f"user:{user_id}",
                        object=f"doc:{doc.metadata.get('id')}",
                        relation="viewer",
                    ),
                ),
                "question": RunnablePassthrough(),
            }
            | self.prompt
            | self.llm
            | StrOutputParser()
        )

        return chain.invoke(question)
```

Let’s break that down.

The `RAG` class first initializes a vector store and reads the documents using the helper functions. It also defines a system prompt for our use case and the LLM model in use, in our case, `gpt-40-mini`.

The class also defines a method query that builds the chain by piping the `FGARetriever` instance with the prompt and the LLM model. `FGARetriever` is provided by the [Auth0 AI SDK for Python](https://github.com/auth0-lab/auth0-ai-python).

The `FGARetriever` is designed to abstract the base retriever from the FGA query logic. The `build_query` argument lets us specify how to query our FGA model, in this case, by asking if the user is a viewer of the document.

```python
build_query=lambda doc: ClientBatchCheckItem(
    user=f"user:{user_id}",
    object=f"doc:{doc.metadata.get('id')}",
    relation="viewer",
),
```

With this design, you can plug any Langchain retriever, combined with checks for any FGA model query.

### Create an OktaFGA Account

If you already have an [Auth0 account](https://auth0.com/), you can use the same credentials to log in to the Okta FGA dashboard at [https://dashboard.fga.dev](https://dashboard.fga.dev/). If you don't have an Auth0 account, hop over to [https://dashboard.fga.dev](https://dashboard.fga.dev/) and create a free account.

Once you are logged in, you should see a dashboard similar to the one below.

![The Okta FGA Dashboard getting started page](https://images.ctfassets.net/23aumh6u8s0i/38P8Vu4qsBvCGrZ4ePew3C/090d068c68b785311a00aa788b92579b/fga-get-started.png)

> When you log into the Okta FGA dashboard for the first time, you may be asked to create a new store. This store will serve as the home for your authorization model and all the data the engine requires to make authorization decisions. Simply pick a name and create your store to get started.

### Create an OktaFGA Client

Once you are in the dashboard, you’ll need a client to make API calls to OktaFGA. To create a client, navigate to **Settings**, and in the **Authorized Clients** section, click **Create Client**. Give your client a name, mark all three client permissions, and then click **Create**.

![Create FGA client](https://images.ctfassets.net/23aumh6u8s0i/2KQc8ACR0MDTqftUgUSXpX/5b779bcece07a69ac775de0fc760c208/Uploaded_from_RAG_and_Access_Control__Where_Do_You_Start)

When you create the client, OktaFGA will provide you with some data like a Store ID, a Client ID and a Client Secret. Don’t close that yet, you’ll need those values next.

At the root of the project, there’s a `.env.example` file. Copy the file and paste it as `.env`. Then, open the file and edit the three FGA-related variables with the values provided by OktaFGA. When you are ready, click continue, and the modal will display the values for the missing variables (`FGA_API_URL` and `FGA_API_AUDIENCE`).

At this step, you can also add your [OpenAI API Key](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key), which you’ll need to run the demo.

### Configure the OktaFGA model

Now that the application is set up, you can run the provided script to initialize the model and some sample data. To set things up, run:

```
python ./scripts/fga_init.py
```

You can verify that the script worked by navigating to the model explorer page in OktaFGA. The following model should now have been created:

```
model
 schema 1.1

type user

type doc
 relations
   define owner: [user]
   define viewer: [user, user:*]
```

> You can visit the OktaFGA documentation to learn more about [modeling OktaFGA and creating an authorization model](https://docs.fga.dev/modeling).

On top of the model, the script also created two tuples. Tuples in OktaFGA define the relationships between the types.

First, it defined a tuple to give all users access to the public doc:

- **User** :` user:*`
- **Object** : `public-doc`
- **Relation** : `viewer`

Then, it created a second tuple to give the admin user access to the private doc:

- **User** :` user:admin`
- **Object** : `private-doc`
- **Relation** : `viewer`

> You can visit the OktaFGA documentation to learn more about [tuples and how to create them](https://docs.fga.dev/content/getting-started/new-getting-started#add-tuples).

### Query the Chain

Invoke the chain to process a query and generate a response.

```python
rag = RAG()

question = "What is the forecast for ZEKO?"

# Juan only has access to public docs
response = rag.query("juan", question)
print("Response to Juan:", response)

# Admin has access to all docs
response = rag.query("admin", question)
print("Response to Admin:", response)
```

Fantastic! You now know how to build and scale a secure RAG with Python and LangChain. It’s time to test things out.

To run the chain, simply call the `main.py` file:

```
python main.py
```

If you follow the steps, you’ll see a response like the following:

```
Response to Juan: The retrieved context does not provide any specific forecast or predictions for ZEKO (Zeko Advanced Systems Inc.). It mainly outlines the company's mission, technologies, and products without detailing any financial or market forecasts. Therefore, I don't know the forecast for ZEKO.

Response to Admin: The forecast for Zeko Advanced Systems Inc. (ZEKO) for fiscal year 2025 is generally bearish. Projected revenue growth is expected to remain subdued at 2-3%, with net income growth projected at 1-2%, primarily due to margin pressures and competitive challenges. Investors should be cautious, given the potential headwinds the company faces.
```

As you can see, `Juan` couldn’t retrieve any “protected” data, while the user `admin` got an accurate response to the prompt.

## Conclusion

You’ve seen how to build a **secure** RAG system that respects user permissions at the **document level** using **OpenFGA**. This approach prevents data leaks, meets security and compliance requirements, and stays flexible—perfect for businesses dealing with a large pool of sensitive information.

Feel free to adapt this flow for other vector stores, different LLM providers, or your own organizational rules. By coupling RAG’s retrieval power with fine-grained authorization, you’ll build AI-driven apps that are both insightful and safe.

Before you go, we have some great news to share: we are working on more content and sample apps in collaboration with amazing GenAI frameworks like [LlamaIndex](https://www.llamaindex.ai/), [LangChain](https://www.langchain.com/),[ CrewAI](https://www.crewai.com/), [Vercel AI](https://sdk.vercel.ai/), and others. 

[Auth for GenAI](https://a0.to/ai-content) is our upcoming product to help you protect your user's information in GenAI-powered applications.

Make sure to join the [Auth0 Lab Discord server](http://a0.to/auth0-lab-discord) to hear more and ask questions.

Happy coding!

Building a Secure RAG with Python, LangChain, and OpenFGA

Learn how to use Auth0 FGA to secure your LangGraph RAG agent in Python.

Building Retrieval-Augmented Generation (RAG) applications are all the rage, and for a good reason. They let you tap into vast knowledge bases to answer questions, generate content, and power all sorts of AI-driven experiences. But what happens when you need to control who can access what information? That's where things get interesting.

We're diving deep into building a secure RAG pipeline using LangGraph, Python, and Auth0 FGA. Forget simple vector lookups; we're talking about a graph-based approach that lets you orchestrate complex workflows, integrate tools, and enforce fine-grained access control.

## Proposed Solution: Secure Retrieval with LangGraph, OpenAI, and Auth0 FGA

The solution employs a workflow that integrates document retrieval, user-specific authorization filtering, and LLM response generation.

We’ll build a pipeline that uses:

* **LangChain & LangGraph**: A helpful toolkit for chaining the steps of an RAG pipeline (loading data, creating embeddings, retrieving, and prompting).
* **LLMs** (OpenAI or any other): For both embeddings (similarity search) and text generation.
* **Auth0 FGA**: A fine-grained authorization service that checks, for each document, if a user has the “viewer” relationship.

### LangChain & LangGraph

LangChain and LangGraph are two complementary tools that simplify the development of LLM applications, each bringing unique strengths to the table.

LangChain is a library that streamlines the assembly of components—such as document loaders, vector stores, and prompt templates—into a robust and cohesive framework. This makes it easier to build, maintain, and scale your RAG pipeline efficiently.

LangGraph takes a different approach by enabling you to visualize and construct your workflows as a graph. With its ability to handle **complex graphs, branching logic, and advanced flow structures**, LangGraph empowers developers to design sophisticated pipelines that go beyond linear processes. By mapping out the connections between components visually, it enhances modularity and simplifies debugging and optimization. Read more here to get started: [https://langchain-ai.github.io/langgraph/](https://langchain-ai.github.io/langgraph/).

### LLMs

Although we’ll demonstrate OpenAI’s embeddings and Chat APIs, you can easily replace them with other providers (e.g., Anthropic, LLaMA, or Azure OpenAI). The main tasks here are:

1. **Embedding** documents so you can do similarity searches.
2. **Generating** text from the retrieved documents to answer the user’s query.

### FGA, OpenFGA and Auth0 FGA

**FGA (Fine-Grained Authorization)** is about controlling *who can do what* with *which resources*, down to an individual level. In a typical role-based system, you might say, “Admins can see everything, and Regular Users can see some subset.” But in a real-world app—especially one that deals with many documents—this might not be flexible enough.

**OpenFGA (and Auth0 FGA)** addresses this by letting you define authorization *relationships.* The relationships defined in the authorization model can be either direct or indirect. Simply put, direct relationships are directly assigned between a consumer and a resource (we call them user and object) and stored in the database. Indirect relationships are the relationships we can infer based on the data and the authorization model.

If you would like to learn the basics of using FGA for RAG, check out this blog post on [RAG and Access Control: Where Do You Start?](https://auth0.com/blog/rag-and-access-control-where-do-you-start/).

<include
   src="LinkCard"
   title="RAG and Access Control: Where Do You Start?"
   link="https://auth0.com/blog/rag-and-access-control-where-do-you-start/"
   description="Learn how to get started with Auth0 FGA for a RAG application."  img="https://images.ctfassets.net/23aumh6u8s0i/79NCborGcFIrAMeaV7G8oi/f9c588c2d05f0828d447e72e1fe825cc/Latam01.jpg"
/>

## Implementation: Step-by-Step

Below is a sample setup in Python. We’ll keep it simple so you can see the big picture. Feel free to adapt for your chosen LLM or a more robust data store.

### Set Up Prerequisites

To follow this tutorial and secure your application, you’ll need the following:

* Python 3.9 or newer.
* An Auth0 FGA account. If you don’t have one, you can [create one for free](https://dashboard.fga.dev/).
* An [OpenAI account and API key](https://platform.openai.com/).

### Download and install the sample code

To get started, clone the[ auth0-ai-samples](https://a0.to/auth0-ai-samples) repository from GitHub:

```
git clone https://github.com/auth0-samples/auth0-ai-samples.git
cd auth0-ai-samples/authorization-for-rag/langgraph-agentic-python
# Create a virtual env
python -m venv venv
# Activate the virtual env
source ./venv/bin/activate
# Install dependencies
pip install -r requirements.txt
```

The application is written in Python and is structured as follows:

* `main.py` &mdash; The main entry point of the application, and it is where we define the RAG pipeline
* `docs/*.md` &mdash; Sample markdown files are to be used as context for the LLM. There are two types of docs, public and private. Private documents are only accessible to certain individuals.
* `helpers/memory_store.py` &mdash; Creates an in-memory vector store that acts as the base retriever in the chain.
* `helpers/read_documents.py` &mdash; Utility to read the markdown files from the `docs` folder.
* `scripts/fga_init.py` &mdash; Utility to initialize the Auth0 FGA authorization model and sample data.

### RAG Pipeline

The `main.py` file defines the RAG graph using `LangGraph` to interact with the underlying LLM model and retrieve data from our context. In your project, your data may be sourced from different platforms and systems, make sure you check the proper documentation about [loaders in the Langchain ecosystem](https://python.langchain.com/v0.1/docs/modules/data_connection/).

The following diagram represents the RAG architecture we are defining:

![LangGraph RAG architecture](https://images.ctfassets.net/23aumh6u8s0i/NwbnsTvKszhWZIng1VjwH/b8b5d467787cbdbb0ac6a850738f4922/langgraph-python-example.png)

## Python Implementation

Let’s now explore the code at `main.py`, which is where all the magic happens. We’ll start splitting the code into relevant chunks, so it will be easier to follow and understand.

Let’s start by defining a LangChain tool that is responsible for querying the RAG for context by querying the vector database and filtering the relevant documents based on the user access:

```python
@tool
def agent_retrieve_context_tool(query: str):
    """Call to get information about a company, e.g., What is the financial outlook for ZEKO?"""
    documents = read_documents()
    vector_store = MemoryStore.from_documents(documents)

    user_id = "admin"

    retriever = FGARetriever(
        retriever=vector_store.as_retriever(),
        build_query=lambda doc: ClientBatchCheckItem(
            user=f"user:{user_id}",
            object=f"doc:{doc.metadata.get('id')}",
            relation="viewer",
        ),
    )

    relevant_docs = retriever.invoke(query)

    if len(relevant_docs) > 0:
        return "\n\n".join([doc.page_content for doc in relevant_docs])

    return "I don't have any information on that."

tools = [agent_retrieve_context_tool]
```

The `FGARetriever` defined in the `retrieve` node is designed to abstract the base retriever from the FGA query logic. The `build_query` argument lets us specify how to query our FGA model, in this case, by asking if the user is a viewer of the document.

```python
build_query=lambda doc: ClientBatchCheckItem(
    user=f"user:{user_id}",
    object=f"doc:{doc.metadata.get('id')}",
    relation="viewer",
),
```

Then we need to define the nodes in the Graph, each node will process unique functions, so we will explore them separately, starting with the `agent_node`, which is responsible for querying the LLM model based on the user’s input.

Each node in LangGraph receives state as an object and can return state updates, for example:

```python
def agent_node(state: State):
    """
    Generate the response from the agent.
    """
    llm_response = llm.invoke(state["messages"])
    return {"messages": [llm_response]}
```

After the `agent_node` runs, we are using a conditional edge to determine the next step. In our particular case, the node` agent_should_continue` will finalize the execution of the graph if the LLM response didn’t trigger a tool call. But if we detect a tool call, then we continue the graph execution with the `tools` node.

```python
def agent_should_continue(state: State):
    """
    Determines whether the conversation should continue based on the user input.
    """
    last_message = state["messages"][-1]
    if last_message.tool_calls:
        return "tools"

    return END
```

The `tools` node is a bit different from the others, as it builds on top of the Tool we declared at the start and uses the `ToolNode` method to simplify the logic. This method will wrap our tool into a node that adds a response from the tool into the chat messages state.

But that’s not all, as after we process the tool call, and we retrieve the proper context to answer the user’s input, we need to call, once again, the LLM model to generate an answer.

```python
def generate_response_node(state: State):
    """
    Generate the response from the agent based on the result of the RAG tool.
    """
    prompt = PromptTemplate(
        template="""You are an assistant for question-answering tasks. Use the following pieces of retrieved-context to answer the question. If you don't know the answer, just say that you don't know. Use three sentences maximum and keep the answer concise. Question: {question}. Context: {context}. Answer:""",
        input_variables=["question", "context"],
    )

    question = state["messages"][0].content
    context = state["messages"][-1].content

    chain = prompt | llm

    llm_response = chain.invoke(
        {"question": question, "context": context}, prompt=prompt
    )

    return {"messages": [llm_response]}
```

If you read the previous article, this may be familiar, but this is a simple chain that uses a prompt with a question and context to provide a good and relevant answer to the user.

Now, with all the parts in place, we can build the graph:

```python
# Create the OpenAI chat tool
llm = ChatOpenAI(model="gpt-4o-mini").bind_tools(tools)

# Build the graph
graph_builder = StateGraph(State)
tool_node = ToolNode(tools)

# Define the nodes
graph_builder.add_node("agent", agent_node)
graph_builder.add_node("tools", tool_node)
graph_builder.add_node("generate_response", generate_response_node)

# Define the edges
graph_builder.add_edge(START, "agent")
graph_builder.add_conditional_edges(
    "agent",
    agent_should_continue,
    ["tools", END],
)
graph_builder.add_edge("tools", "generate_response")

# Compile the graph
graph = graph_builder.compile()
```

That’s awesome! Now, if you set up all the environment variables, you could run the code. If you are not sure how to set them up, don’t worry; we will do that next.

### Create an Auth0 FGA Account

If you already have an [Auth0 account](https://auth0.com/), you can use the same credentials to log in to the Auth0 FGA dashboard at [https://dashboard.fga.dev](https://dashboard.fga.dev/). If you don't have an Auth0 account, hop over to [https://dashboard.fga.dev](https://dashboard.fga.dev/) and create a free account.

Once you are logged in, you should see a dashboard similar to the one below.

![The Auth0 FGA Dashboard getting started page](https://images.ctfassets.net/23aumh6u8s0i/38P8Vu4qsBvCGrZ4ePew3C/090d068c68b785311a00aa788b92579b/fga-get-started.png)

> When you log into the Auth0 FGA dashboard for the first time, you may be asked to create a new store. This store will serve as the home for your authorization model and all the data the engine requires to make authorization decisions. Simply pick a name and create your store to get started.

### Create an Auth0 FGA Client

Once you are in the dashboard, you’ll need a client to make API calls to Auth0 FGA. To create a client, navigate to **Settings**, and in the **Authorized Clients** section, click **Create Client**. Give your client a name, mark all three client permissions, and then click **Create**.

![Create FGA client](https://images.ctfassets.net/23aumh6u8s0i/2KQc8ACR0MDTqftUgUSXpX/5b779bcece07a69ac775de0fc760c208/Uploaded_from_RAG_and_Access_Control__Where_Do_You_Start)

When you create the client, Auth0 FGA will provide you with some data like a Store ID, a Client ID and a Client Secret. Don’t close that yet, you’ll need those values next.

At the root of the project, there’s a `.env.example` file. Copy the file and paste it as `.env`. Then, open the file and edit the three FGA-related variables using the values provided by Auth0 FGA. When you are ready, click continue, and the modal will display the values for the missing variables (`FGA_API_URL` and `FGA_API_AUDIENCE`).

At this step, you can also add your [OpenAI API Key](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key), which you’ll need to run the demo.

### Configure the Auth0 FGA model

Now that the application is set up, you can run the provided script to initialize the model and some sample data. To set things up, run:

```
python ./scripts/fga_init.py
```

You can verify that the script worked by navigating to the model's page in Auth0 FGA. The following model should now have been created:

```
model
 schema 1.1

type user

type doc
 relations
   define owner: [user]
   define viewer: [user, user:*]
```

> You can visit the Auth0 FGA documentation to learn more about[ modeling Auth0 FGA and creating an authorization model](https://docs.fga.dev/modeling).

On top of the model, the script also created two tuples. Tuples in Auth0 FGA define the relationships between the types.

First, it defined a tuple to give all users access to the public doc:

- **User** &mdash; `user:*`
- **Object** &mdash; `public-doc`
- **Relation** &mdash; `viewer`

Then, it created a second tuple to give the admin user access to the private doc:

- **User** &mdash; `user:admin`
- **Object** &mdash; `private-doc`
- **Relation** &mdash; `viewer`

> You can visit the Auth0 FGA documentation to learn more about [tuples and how to create them](https://docs.fga.dev/content/getting-started/new-getting-started#add-tuples).

### Query the Graph

Invoke the graph to process a query and generate a response.

```python
# Run the graph
result = graph.invoke(
    {"messages": [("human", "What is the financial outlook for ZEKO?")]}
)
print(result["messages"][-1].content)
```

Fantastic! You now know how to build and scale a secure RAG with Python and LangGraph. It’s time to test things out.

To run the graph, simply call the `main.py` file:

```
python main.py
```

If you follow the steps, you’ll see responses like the following:

```
Example with no access:
The retrieved context does not provide any specific forecast or predictions for ZEKO (Zeko Advanced Systems Inc.). It mainly outlines the company's mission, technologies, and products without detailing any financial or market forecasts. Therefore, I don't know the forecast for ZEKO.

Example with access:
The forecast for Zeko Advanced Systems Inc. (ZEKO) for fiscal year 2025 is generally bearish. Projected revenue growth is expected to remain subdued at 2-3%, with net income growth projected at 1-2%, primarily due to margin pressures and competitive challenges. Investors should be cautious, given the potential headwinds the company faces.
```

Depending on the user you use in the `agent_retrieve_context_tool`, you’ll see different results, experiment also by adding and removing privileges from the Auth0 FGA dashboard.

## Learn More about Auth for GenAI, Auth0 FGA, and GenAI

Before you go, we have some great news to share: we are working on more content and sample apps in collaboration with amazing GenAI frameworks like [LlamaIndex](https://www.llamaindex.ai/), [LangGraph](https://www.langchain.com/), [CrewAI](https://www.crewai.com/), [Vercel AI](https://sdk.vercel.ai/), and others. 

[Auth for GenAI](https://a0.to/ai-content) is our upcoming product to help you protect your user's information in GenAI-powered applications.

Make sure to join the [Auth0 Lab Discord server](http://a0.to/auth0-lab-discord) to hear more and ask questions.

Happy coding!

Building a Secure Python RAG Agent Using Auth0 FGA and LangGraph

37590801?s=460&v=4

Howdy! 🤠 I do technology research at Auth0 with a focus on security and identity and develop apps to showcase the advantages or pitfalls of such technology. I also contribute to the development of our SDKs, documentation, and design systems, such as <a target='_blank' rel='noopener noreferrer' href='https://github.com/auth0/cosmos'><strong>Cosmos</strong></a>.<br /><br />The majority of my engineering work revolves around AWS, React, and Node, but my research and content development involves a wide range of topics such as Golang, performance, and cryptography. Additionally, I am one of the core maintainers of this blog. Running a blog at scale with <strong>over 600,000 unique visitors per month</strong> is quite challenging!<br /><br />I was an Auth0 customer before I became an employee, and I've always loved how much easier it is to implement authentication with Auth0. Curious to try it out? <a href='https://auth0.com/signup' data-amp-replace='CLIENT_ID' data-amp-addparams='anonId=CLIENT_ID(cid-scope-cookie-fallback-name)'><strong>Sign up for a free account</strong></a> ⚡️.

Dan Arias

AAA (Authentication, Authorization, Accounting) helps developers secure web apps by verifying users, controlling access, and tracking actions.

Historically, the AAA framework (Authentication, authorization, and accounting) has been deeply tied to network security, particularly in the context of remote access, VPNs, and network devices. However, AAA is a conceptual framework and not a protocol itself, allowing us to apply it anywhere identity and access matter. Instead of a VPN gateway, you’re securing a web application. Instead of a network admin, it’s a customer buying shoes online. The scale gets bigger, the users are external, and the focus shifts toward balancing security and usability, but the AAA principles still fit to help us build robust, secure, and maintainable user-facing applications.

For developers, considering AAA in your design decisions means not only verifying who your users are (Authentication) but also controlling what they can do (Authorization) and tracking their actions for auditing and analytics (Accounting). This holistic approach minimizes security risks, enhances user experience, and simplifies compliance.

## A Framework to Measure Identity Platforms

A good identity platform gives you features out of the box that tackle each component of the AAA triad, transforming a simple login system into a comprehensive identity management system that meets your security and compliance requirements. User data is one of the most precious and valuable assets we handle as developers. As such, when we make the decision to delegate creating and handling the identity of our users to a third-party vendor, we need to ensure that we are getting better security, scalability, and user-centric experience than what we could build ourselves. The AAA framework is a helpful tool to assess whether an Identity-as-a-Service (IDaaS) vendor can help you build application systems that are resilient against threats, aligned with business requirements, and equipped for future growth.

In today’s competitive digital landscape, including identity and security as part of your MVP or existing product is a competitive advantage. A holistic approach to security is not just an option—it’s a necessity. However, not every player in the field can deliver the security the current security and threat landscape requires. Let’s dive into why Auth0 is a robust identity platform that meets the requirements of the AAA framework and why you should consider it as your identity solution of choice.

## Authentication

Authentication is the process of verifying a user's identity before granting access to your application. It answers the question: **"Who are you?"**

* [Seamless User Sign-Up and Login](https://auth0.com/docs/authenticate/login)
    * Auth0 offers multiple authentication methods, such as social logins, passwordless options, and multi-factor authentication (MFA). These features enable quick and secure identity verification.
* [Personable User Experience](https://auth0.com/docs/customize)
    * With customizable interfaces, Auth0 reduces barriers during sign-up and login, ensuring that the verification process is both secure and user-friendly.
* [Relevant User Journeys](https://auth0.com/docs/customize/forms)
    * Auth0 offers customization of the metadata you collect from users or creates a unique authentication journey that serves your business needs while still being secure.
* [Uncompromised Internationalization and Localization](https://auth0.com/docs/customize/internationalization-and-localization)
    * Auth0 can handle different languages across the authentication experience, allowing you to connect authentically and accurately with millions of potential customers across the globe. Auth0 adapts to your users instead of forcing users to adapt to inflexible platforms.

## Authorization

Authorization defines what actions or resources a user is allowed to access once they are authenticated. It answers the question: **"What can you do?"**

Auth0 allows developers to implement flexible yet comprehensive authorization models that fit different threat models.

* [Role-Based Access Control (RBAC)](https://auth0.com/blog/an-overview-of-commonly-used-access-control-paradigms/#Role-Based-Access-Control--RBAC-):
    * Auth0 allows you to set granular permissions by assigning roles to users. This ensures that users only access the features and data relevant to their privileges.
* [Auth0 Actions](https://auth0.com/docs/manage-users/access-control/sample-use-cases-actions-with-authorization)
    * Actions are secure  Node.js functions that allow you to modify or complement the outcome of the decision made by pre-configured authorization policies. Developers can use Auth0 Actions to[ handle more complicated cases](https://auth0.com/docs/manage-users/access-control/sample-use-cases-actions-with-authorization) than is possible with role-based access control (RBAC).
* [Fine Grained Authorization](https://auth0.com/fine-grained-authorization)
    * Auth0 FGA delivers relationship-based access control ([ReBAC](https://auth0.com/blog/an-overview-of-commonly-used-access-control-paradigms/#Relationship-Based-Access-Control--ReBAC-)) designed for complex authorization needs, such as restricting resource edits to team leads. As a managed service, it scales to handle millions of permission checks per second with minimal latency, eliminating the need to build and maintain custom solutions.

## Accounting

Accounting, also known as auditing, involves tracking and logging user activities within your application. It answers the question: **"What did you do?"**

* [Detailed Logging](https://auth0.com/docs/deploy-monitor/logs)
    * Auth0 maintains a comprehensive audit trail of authentication and authorization events. This detailed logging is essential for monitoring user behavior and identifying potential security incidents.
* [Usage Analytics](https://auth0.com/docs/get-started/auth0-overview/dashboard/activity)
    * The collected data helps analyze user interactions, optimize authentication flows, and ensure compliance with industry regulations. Accounting provides valuable insights into how your application is used.
* [Log Streaming](https://auth0.com/docs/customize/log-streams)
    * Auth0's log streaming service allows you to export tenant log events to a log event analysis service URL, leveraging robust data services, such as DataDog, Splunk, and Amazon EventBridge, and allowing you to react to events like password changes or new registrations with your own business logic.

## Bringing It All Together

Overlaying the AAA framework on your Auth0-powered B2C or B2B solutions ensures:

* **Enhanced Security:**
    * A multi-layered approach that not only verifies identities (Authentication) but also enforces precise access controls (Authorization) and continuously monitors user activities (Accounting).
* **Improved User Experience:**
    * While users benefit from a smooth and secure sign-up process, the detailed authorization rules and accounting measures ensure that they access the right features with confidence.
* **Operational Excellence:**
    * With robust logging and analytics, you can swiftly detect anomalies, refine your application, and maintain compliance with regulatory standards.

If you haven’t tried it already, [get started with Auth0 today](https://a0.to/get-started)!


Authentication, Authorization, and Accounting For Developers

jimena-garbarino

Jimena is an experienced result and value-oriented programmer with a strong engineering background. She excels with Ruby on Rails, Java, and Scrum development. She has worked in web development for 10+ years in many industries and has a master's degree in software engineering from Universidad de Buenos Aires.

Spring Cloud Developer

Jimena Garbarino

How to add Fine-Grained Authorization (FGA) to an Express + Typescript API using the OpenFGA Javascript and Node.js SDK.

OpenFGA is an open-source Relationship-Based Access Control (ReBAC) system designed by Okta for developers, and adopted by the Cloud Native Computing Foundation (CNCF). It offers scalability and flexibility, and it also supports the implementation of RBAC and ABAC authorization models, moving authorization logic outside application code, making it simpler to evolve authorization policies as complexity grows. In this guide, you will learn how to secure a Node.js API with Auth0 and integrate Fine-Grained Authorization (FGA) into document operations with OpenFGA.

> **This tutorial was created with the following tools and services**:
> - [Node 20.10.0](https://jdk.java.net/java-se-ri/21)
> - [Auth0 account](https://auth0.com/signup)
> - [Auth0 CLI 1.4.0](https://github.com/auth0/auth0-cli#installation)
> - [Docker 24.0.7](https://docs.docker.com/desktop/)
> - [FGA CLI v0.2.7](https://openfga.dev/docs/getting-started/install-sdk)


## Add API Authorization

Auth0 is an easy to implement, adaptable authentication and authorization platform, and you can implement authentication for any application in just minutes. With Auth0 CLI you can create access tokens and use them for identifying the user when making requests to the document API. Sign up at [Auth0](https://auth0.com/signup) and install the [Auth0 CLI](https://github.com/auth0/auth0-cli). Then in the command line run:

```shell
auth0 login
```

The command output will display a device confirmation code and open a browser session to activate the device.

You don't need to create a client application at Auth0 for your API if not using opaque tokens. But you must register the API within your tenant, you can do it using Auth0 CLI:

```shell
auth0 apis create \
  --name "Document API" \
  --identifier https://document-api.okta.com \
  --offline-access=false
```

Leave scopes empty and default values when prompted.

Checkout the document API repository, which already implements basic request handling:

```shell
git clone https://github.com/indiepopart/express-typescript-fga.git
```

The repository contains two project folders, `start` and `final`. The bare bones document API is a Node.js project in the `start` folder, open it with your favorite IDE. Add the `express-oauth2-jwt-bearer` dependency:

```shell
cd express-typescript-fga/start
npm install express-oauth2-jwt-bearer
```

Create the middleware for token validation in the file `src/middleware/auth0.middleware.ts`, with the following content:

```typescript
// src/middleware/auth0.middleware.ts
import * as dotenv from "dotenv";
import { auth } from "express-oauth2-jwt-bearer";

dotenv.config();

export const validateAccessToken = auth({
  issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
  audience: process.env.AUTH0_AUDIENCE,
});
```

Call `validateAccessToken` from the router, for example:

```typescript
// src/documents/document.router.ts
...
documentRouter.get("/", validateAccessToken, async (req, res, next) => {
  try {
    const documents = await getAllDocuments();
    res.status(200).json(documents);
  } catch (error) {
    next(error);
  }
});
...
```

Add error handling to `error.middleware.ts`, the final code should look like this:

```typescript
import { Request, Response, NextFunction } from "express";
import {
  InvalidTokenError,
  UnauthorizedError,
} from "express-oauth2-jwt-bearer";

import mongoose from "mongoose";

export const errorHandler = (
  error: any,
  request: Request,
  response: Response,
  next: NextFunction
) => {
  console.log(error);

  if (error instanceof InvalidTokenError) {
    const message = "Bad credentials";

    response.status(error.status).json({ message });

    return;
  }

  if (error instanceof UnauthorizedError) {
    const message = "Requires authentication";

    response.status(error.status).json({ message });

    return;
  }

  if (error instanceof mongoose.Error.ValidationError) {
    const message = "Bad Request";

    response.status(400).json({ message });

    return;
  }

  if (error instanceof mongoose.Error.CastError) {
    console.log("handle ValidationError");
    const message = "Bad Request";

    response.status(400).json({ message });

    return;
  }

  const status = 500;
  const message = "Internal Server Error";

  response.status(status).json({ message });
};
```

Copy `.env.example` to `.env` and add the properties:

```shell
AUTH0_AUDIENCE=https://document-api.okta.com
AUTH0_DOMAIN=<your-auth0-domain>
```

Run the MongoDB database with:

```shell
docker compose up mongodb mongo-express
```

Run the API with:

```shell
npm install && npm run dev
```

Obtain a test access token with Auth0 CLI:

```shell
auth0 test token -a https://document-api.okta.com -s openid
```
Choose an available `[Generic]` client when prompted. Set the access token in an environment var:

```shell
ACCESS_TOKEN=<access-token>
```

Create a document with cURL:

```shell
curl -i -X POST \
  -H "Authorization:Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "planning.doc"}' \
  http://localhost:6060/api/documents
```

The output should look like:

```json
{
  "name": "planning.doc",
  "_id": "66feb9c1f106b84c28644d3e",
  "__v": 0
}
```

Retrieve all documents:

```shell
curl -i -H "Authorization: Bearer $ACCESS_TOKEN" localhost:6060/api/documents
```

The output should look like:

```json
[
  {
    "_id": "66feb9c1f106b84c28644d3e",
    "name": "planning.doc",
    "__v": 0
  }
]
```

Verify access is denied if the access token is not present:

```shell
curl -i localhost:6060/api/documents
```

The response code should be `401 Unauthorized`.

## Initialize an Authorization Model in OpenFGA

At a high level, an authorization model is defined by indicating user types, object types, and relationships between them. As we are not going to deep-dive on [ReBAC](https://openfga.dev/docs/authorization-concepts#what-is-relationship-based-access-control) in this guide, you can refer to OpenFGA documentation for learning about modeling concepts. Under the [Advanced use-cases](https://openfga.dev/docs/modeling/advanced) section in the doc, there is a simplified authorization model for a [Google Drive](https://openfga.dev/docs/modeling/advanced/gdrive) application ready to test. Prepare the model for import to the OpenFGA service, creating the file `auth-model.fga` in the directory `start/openfga`:

```fga
model
  schema 1.1

type user

type document
  relations
    define owner: [user, domain#member] or owner from parent
    define writer: [user, domain#member] or owner or writer from parent
    define commenter: [user, domain#member] or writer or commenter from parent
    define viewer: [user, user:*, domain#member] or commenter or viewer from parent
    define parent: [document]

type domain
  relations
    define member: [user]
```

For saving the authorization model in an OpenFGA store, it must be transformed to JSON format with FGA CLI:

```shell
fga model transform --file=auth-model.fga > auth-model.json
```

Run the OpenFGA service with:

```shell
docker compose up openfga
```

Create a store:

 ```shell
 export FGA_API_URL=http://localhost:8090
 fga store create --name "documents-fga"
 ```

 Set the store id in the output as an env var, and write the model:

 ```shell
 export FGA_STORE_ID=<store-id>
 fga model write --store-id=${FGA_STORE_ID} --file auth-model.json
 ```

 Set the model ID in the output as an env var:

 ```shell
 export FGA_MODEL_ID=<model-id>
 ```

## Add Fine-Grained Authorization (FGA) with OpenFGA

First, add the following vars to the `.env` file:

```shell
FGA_API_URL=http://localhost:8090
FGA_STORE_ID=<store-id>
FGA_MODEL_ID=<model-id>
```

Create a middleware for permission checks using OpenFGA Node.js SDK. Install the dependency:

```shell
npm install @openfga/sdk
```

Add the file `src/middleware/openfga.middleware.ts`:

```typescript
// src/middleware/openfga.middleware.ts
import * as dotenv from "dotenv";
import { NextFunction, Request, Response } from "express";
import { ClientCheckRequest, OpenFgaClient } from "@openfga/sdk";

dotenv.config();

export class PermissionDenied extends Error {
  constructor(message: string) {
    super(message);
  }
}

const fgaClient = new OpenFgaClient({
  apiUrl: process.env.FGA_API_URL, // required
  storeId: process.env.FGA_STORE_ID, // not needed when calling `CreateStore` or `ListStores`
  authorizationModelId: process.env.FGA_MODEL_ID, // Optional, can be overridden per request
});

export const forView = (req: Request): ClientCheckRequest => {
  const userId = req.auth?.payload.sub;
  const tuple = {
    user: `user:${userId}`,
    object: `document:${req.params.id}`,
    relation: "viewer",
  };
  return tuple;
};

export const forUpdate = (req: Request): ClientCheckRequest => {
  const userId = req.auth?.payload.sub;
  const tuple = {
    user: `user:${userId}`,
    object: `document:${req.params.id}`,
    relation: "writer",
  };
  return tuple;
};

export const forDelete = (req: Request): ClientCheckRequest => {
  const userId = req.auth?.payload.sub;
  const tuple = {
    user: `user:${userId}`,
    object: `document:${req.params.id}`,
    relation: "owner",
  };
  return tuple;
};

export const forCreate = (req: Request): ClientCheckRequest | null => {
  const userId = req.auth?.payload.sub;
  const parentId = req.body.parentId;
  const tuple = parentId
    ? {
        user: `user:${userId}`,
        object: `document:${parentId}`,
        relation: "writer",
      }
    : null;
  return tuple;
};

export const checkPermissions = (
  createTuple: (req: Request) => ClientCheckRequest | null
) => {
  return async (req: Request, res: Response, next: NextFunction) => {
    try {
      const tuple = createTuple(req);

      console.log("tuple", tuple);

      if (!tuple) {
        next();
        return;
      }
      const result = await fgaClient.check(tuple);

      if (!result.allowed) {
        next(new PermissionDenied("Permission denied"));
        return;
      }

      next();
    } catch (error) {
      next(error);
    }
  };
};
```

Call the middleware from the document router:

```typescript
// src/documents/document.router.ts

documentRouter.post(
  "/",
  validateAccessToken,
  checkPermissions(forCreate),
  async (req, res, next) => {
    try {
      const document = await saveDocument(req.body);
      res.status(200).json(document);
    } catch (error) {
      next(error);
    }
  }
);

documentRouter.put(
  "/:id",
  validateAccessToken,
  checkPermissions(forUpdate),
  async (req, res, next) => {
    try {
      const document = await updateDocument(req.params.id, req.body);
      if (!document) {
        res.status(404).json({ message: "Document not found" });
        return;
      }
      res.status(200).json(document);
    } catch (error) {
      next(error);
    }
  }
);

documentRouter.delete(
  "/:id",
  validateAccessToken,
  checkPermissions(forDelete),
  async (req, res, next) => {
    try {
      const document = await deleteDocumentById(req.params.id);
      if (!document) {
        res.status(404).json({ message: "Document not found" });
        return;
      }
      res.status(200).send();
    } catch (error) {
      next(error);
    }
  }
);

documentRouter.get(
  "/:id",
  validateAccessToken,
  checkPermissions(forView),
  async (req, res, next) => {
    try {
      const document = await findDocumentById(req.params.id);
      if (!document) {
        res.status(404).json({ message: "Document not found" });
        return;
      }
      res.status(200).json(document);
    } catch (error) {
      next(error);
    }
  }
```

Update the error handling middleware:

```typescript
// src/middleware/error.middleware.ts
if (error instanceof PermissionDenied) {
  const message = "Permission denied";

  response.status(403).json({ message });

  return;
}
```

## Send Requests to the Express API

Run the API and try a read operation:

```shell
curl -i -H "Authorization: Bearer $ACCESS_TOKEN" localhost:6060/api/documents
```

```shell
curl -i -H "Authorization: Bearer $ACCESS_TOKEN" localhost:6060/api/documents/<document-id>
```

It should fail with the following `403 Forbidden` response:

```json
{
  "message": "Permission denied"
}
```

Go to https://jwt.io/ and decode the Auth0 access token, and copy the `sub` claim value to use it as UserIDº.

Then grant read access to the document with FGA CLI:

```shell
fga tuple write --store-id=${FGA_STORE_ID} --model-id=$FGA_MODEL_ID 'user:<sub-claim>' viewer document:<document-id>
```

You can add other relationships for the user and document like `owner`, `writer`. Retry the read operation and it should succeed with `200 OK`.

## Learn More about Node.js and Fine-Grained Authorization

In this post, you learned about OpenFGA integration to a Node.js API using the [OpenFGA Javascript and Node.js SDK](https://github.com/openfga/js-sdk). I hope you enjoyed this quick tutorial, and if you'd rather skip the step-by-step and prefer running a sample application, follow the [README](https://github.com/indiepopart/express-typescript-fga) instructions in the same repository.

Also, if you liked this post, you might enjoy these related posts:

- [Secure Node.js Applications from Supply Chain Attacks](https://auth0.com/blog/secure-nodejs-applications-from-supply-chain-attacks/)
- [Authorization in your Next.js application using Okta FGA](https://auth0.com/blog/fine-grained-access-control-with-okta-fga-nextjs/)

Check out the Javascript resources in our Developer Center:

- [Express.js Code Samples: API Security in Action](https://developer.auth0.com/resources/code-samples/api/express)
- [Express.js Code Sample: API Role-Based Access Control](https://developer.auth0.com/resources/code-samples/api/express/basic-role-based-access-control)
- [Node (Express) API: Authorization](https://auth0.com/docs/quickstart/backend/nodejs)

Please follow us on Twitter [@oktadev](https://twitter.com/oktadev) and subscribe to our [YouTube channel](https://www.youtube.com/oktadev) for more Node.js and microservices knowledge.

You can also sign up for our [developer newsletter](https://a0.to/nl-signup/java) to stay updated on everything Identity and Security.

OpenFGA for an Express + Typescript Node.js API

samantha-murphy

Samantha Murphy is a Principal Product Marketing Manager for Okta. She leads the Customer Identity Security portfolio, driving go-to-market strategy, messaging, launches, and strategic growth initiatives. Before Okta, Sam spent over six years in product management roles in Identity and Access Management.

She holds a Bachelor of Commerce degree from Queen’s Smith School of Business and is from Ottawa, Canada.

In her free time, Sam makes the most of winter by playing an awesome ice skating sport called ringette.

Principal Product Marketing Manager, Customer Identity

Samantha Murphy

If you’re curious about how to stay ahead of increasingly sophisticated attacks without putting your business goals at risk with excessive friction, this resource is for you.

Identity is the connective tissue between every person and technology in your ecosystem. This connective role also places Identity at the center of your risk profile. It’s no surprise that Identity remains the No. 1 attack vector in today’s threat landscape —  over 80% of data breaches involve some form of compromised Identity.

Properly addressing this fact means taking a serious and expansive look at your organization’s approach to Identity — because here’s the thing: Identity is more than just a login box. A rigorous, modern approach to Identity mitigates threats before, at, and after authentication.

Accordingly, technology leaders can’t limit themselves exclusively to Identity-related threats. They must also consider the impact their Identity solution has on core business priorities such as revenue, customer satisfaction, and growth goals.

This blog dives into how technology leaders can deliver Identity security solutions that also drive growth. If you’re curious about how to stay ahead of increasingly sophisticated attacks without putting your business goals at risk with excessive friction, this resource is for you.

## It’s Time to Ditch Dated Identity and Excessive Friction

Protecting customers from account takeover and other malicious actions is crucial. But when that protection creates frustrating stumbling blocks for customers, like passwords, frequent CAPTCHAs, and multi-factor authentication (MFA) fatigue, your business is at risk. By introducing excessive friction into customer journeys, good-faith security efforts built on legacy Identity methods can lead to abandoned customer journeys, lower conversion rates, and lost business.

It’s a raw deal, and the worst part is that Identity security that burdens your customers doesn’t necessarily translate to better security. For example, traditional usernames and passwords with SMS as a second factor are vulnerable to social engineering and SIM-swapping attacks.

The clock has run out on legacy Identity. It’s time to embrace a modern approach that leverages Identity as more than a login box and, instead, drives better security and better business.

## Protect Every Stage of the Customer Journey

If the stats on pervasive Identity-related breaches teach us anything, it’s that legacy Identity simply isn’t enough in today’s threat landscape. Technology leaders need Identity security that can discover weaknesses, protect against vulnerabilities, and limit access if an adversary gets in.

In order to modernize security, you must modernize Identity. Auth0’s layered defense strategy improves security before, at, and after the login box alongside a SecOps dashboard, tools, and integrations. Here’s how our Auth0 Identity platform drives stronger security, privacy, and user experience (UX) across the customer journey.

### Before login

Bots make up 42% of all internet traffic today and 65% of these are bad bots.A versatile, scalable method for bad actors to carry out automated attacks, bots are also a major drain on your marketing budget. Whenever bots sign up for new accounts, they eat into your sign-up bonuses and block new connections with real customers.

Generative AI is poised to add gas to the bot fire: Between 2023 and 2030, AI adoption in cybercrime is expected to rise by 37%. Soon, businesses will be dealing with an even higher number of sophisticated bots capable of outsmarting simple bot-detection CAPTCHAs.

Modern Identity should stop bad bots in their tracks while maintaining customer-friendly experiences that protect revenue. Auth0 Bot Detection continuously monitors Identity threats across hundreds of millions of users, enabling us to detect bad bots and respond in real time with user-friendly challenges like the time-based authentication challenge. In addition, our Bot Detection solution now features a machine-learning model designed for signup attacks. Tailored models greatly improve detection and prevention of bots across the user journey, while reducing bot challenges presented to real customers.

Auth0 SOLUTIONS TO EXPLORE FURTHER:

* [Bot Detection](https://auth0.com/docs/secure/attack-protection/bot-detection)

### At login

Ultimately, driving your business forward comes down to providing customers with a simple and seamless user experience without compromising on security. Customers want on-demand convenience — fast, easy access with flexible login options — which means digital teams need to design phishing-resistant authentication experiences that also deliver a quick and easy customer journey.

Modern Identity can provide that perfect balance with flexible, secure passwordless login options. Passkeys allow users to log in quickly and securely, similar to how they unlock their mobile devices. They are also a phishing-resistant alternative to less user-friendly login options like the commonly used username and password plus MFA combination. Adaptive MFA can also reduce MFA fatigue by assessing risk signals such as a new device, network, or location, impossible travel, and untrusted IP, only triggering a second challenge for higher-risk authentication attempts.

In addition to login options, Auth0 offers layered security features for login. Auth0 Breached Password Detection and Credential Guard screen for and block compromised credentials. Auth0’s Brute-Force Protection and Suspicious IP Throttling help prevent account takeover attacks that target single and multiple user accounts, respectively.

Auth0 SOLUTIONS TO EXPLORE FURTHER:

* [Single Sign-On](https://auth0.com/docs/authenticate/single-sign-on) 
* [Passwordless](https://auth0.com/docs/authenticate/passwordless),[ Passkeys](https://auth0.com/docs/authenticate/database-connections/passkeys) 
* [Multi-Factor Authentication](https://auth0.com/docs/secure/multi-factor-authentication)
* [Adaptive MFA](https://auth0.com/docs/secure/multi-factor-authentication/adaptive-mfa)
* [Suspicious IP Throttling](https://auth0.com/docs/secure/attack-protection/suspicious-ip-throttling)
* [Breached Password Detection and Credential Guard](https://auth0.com/docs/secure/attack-protection/breached-password-detection)
* [Brute Force Protection](https://auth0.com/docs/secure/attack-protection/brute-force-protection)

### After login

The ongoing rise in post-login threats also necessitates a defense-in-depth, layered security approach at every step of the user journey. The stakes are high, and the pain caused by breaches has the potential for extensive reach. Breaches not only incur painful financial losses but also lead to substantial brand and compliance-related effects that threaten the core business. Modern Identity can help avoid these outcomes.

Modern Identity elevates security, privacy, and experience post-login to protect sensitive customer interactions and user sessions. For example, with Auth0 Highly Regulated Identity, configure your organization to send financial-grade contextual approval requests to customers’ devices for sensitive interactions like account updates or money transfers. With Auth0 Continuous Session Protection, your organization can also continuously monitor user sessions to detect and prevent hijacking attempts, revoke suspicious sessions, and set custom timeouts.

Auth0 SOLUTIONS TO EXPLORE FURTHER:

* [Highly Regulated Identity](https://auth0.com/docs/secure/highly-regulated-identity)
* [Continuous Session Protection](https://auth0.com/docs/secure/continuous-session-protection)

## SecOps

Security is a team sport, which is why Auth0 enables better collaboration between security, product teams, and developers with real-time insights and ready-made integrations that connect Auth0 functionality to a broader security apparatus.

For example, Auth0’s Security Center helps organizations detect and respond to attacks faster and fine-tune their security posture with intelligent insights and custom threshold alerting for Identity-related events, anomalies, and general efficacy. Security Log Streaming further supports faster event response by allowing the streaming of relevant Customer Identity Cloud activity to third-party SIEM tooling.

Auth0 SOLUTIONS TO EXPLORE FURTHER

* [Security Center](https://auth0.com/docs/secure/security-center)
* [Security Log Streaming](https://auth0.com/docs/secure/security-center/prioritized-log-streams)

## The Perfect Blend of Security and Usability

It’s tempting to think of Identity as a box to be checked. Equip your customer-facing applications with SSO and MFA–check. It's time to dust off your hands and declare victory, right? If only it was that easy.

To adapt to the ever-shifting risks of the business landscape with equal attention to security and revenue, technology leaders need an approach to Identity-based security that also functions as a business driver. That means integrating secure, seamless Identity functions into your security and revenue strategies at each customer touchpoint.

Legacy approaches to Identity fall far short of this goal. But, by entrusting your organization’s Identity with a leader in modern Identity, you can position your business to lead the pack in customer Identity security and core business KPIs.

## It All Starts with Auth0

[Thousands of customers](https://www.okta.com/customers/) worldwide trust Auth0 to strike the perfect balance of robust security and seamless customer experience across more than 10 billion monthly authentications.

We’ve invested in a layered defense strategy to improve security before, during, and after the login box — plus a dashboard and tools for SecOps that improve visibility and enable faster responses to potential and emerging threats.

Curious about how the Auth0 can help you build trust with your customers, secure your applications, and protect revenue?[ Reach out to our team](https://auth0.com/contact-us?place=header&type=button&text=contact%20sales) to schedule a demo.


Identity Security 101: How to Drive Trust and Loyalty across the User Journey

carla_urrea

I've been working as a software engineer since 2014, particularly as a backend engineer and doing system design. I consider myself a language-agnostic developer but if I had to choose, I like to work with Ruby, Python, and Elixir.  

After realizing how fun it was to create content and share experiences with the developer community I made the switch to Developer Advocacy. I like to learn and work with new technologies. 

When I'm not coding or creating content you could probably find me going on a bike ride, hiking, or just hanging out with my dog, Dasha. 

Senior Developer Advocate

Carla Urrea Stabile

The way to implement an authorization system depends on your application's needs. Let's explore Relationship-Based Access Control (ReBAC) and implement it in a Rails API using OpenFGA.

How to Implement Relationship-Based Access Control (ReBAC) in a Ruby On Rails API?

Learn how to integrate CIBA authentication in your .NET applications to improve security and privacy.

There are scenarios where the user cannot interact directly with an application to use its functionality securely. In these scenarios, CIBA can guarantee security and usability at the same time.
This article will walk you through CIBA authentication and how to implement it in a .NET application.

## What Is CIBA?

CIBA stands for *Client-Initiated Backchannel Authentication*, and it's a [standard flow](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) for decoupled authentication defined by the OpenID Foundation. Decoupled authentication occurs when the user is authenticated outside the context of an application. For example, consider a call center agent that is asked to modify a customer's order on the phone. Before executing that request, the agent needs to be sure that the user on the phone is actually the customer who placed that order. In this case, the call center agent sends an authentication request to the customer's phone. Once the customer confirms their identity, the operator can perform the requested action. Notice that the user authentication does not occur in the order management application, i.e., the application where the requested action needs to be performed, but on the user's device. This is why this type of authentication is called decoupled authentication.

Read [this article to learn more about CIBA use cases](https://auth0.com/blog/ciba-authenticate-customers-in-call-centers/).

## The CIBA Flow

Let's dig into the following diagram to understand how CIBA works:

![The Client-Initiated Backchannel Authentication (CIBA) flow](https://images.ctfassets.net/23aumh6u8s0i/3FccU3SUoWUH9TjY8zpSao/0dbdc84a573753cba9505edcf9237ee3/ciba-flow.png)

From this diagram, you see that the actors involved in the flow are:

- **The user**. This is the user who interacts with the application starting the authentication flow. In the use case described earlier, this is the call center agent.
- **The client application**. This is the application that initiates the CIBA authentication flow. In our previous example, it was the order management application. Notice that this application must be a [confidential client](https://auth0.com/docs/get-started/applications/confidential-and-public-applications), i.e., an application running in a controlled environment, such as a server environment. You cannot implement the CIBA flow directly in a SPA or desktop application; these applications must rely on a backend server.
- **The authorization server**. It's the server that authenticates the user and supports the CIBA flow, such as Auth0.
- **The end user**. This is the customer who needs to be authenticated to allow the user to perform actions on the client application. In the context of our example, this is the customer asking for a change to their order. The end user must have a mobile device with an application enrolled with the authorization server to receive push notifications.

> While in this diagram you have two distinct users, in some scenarios, the user and the end user can be the same person. Consider the case of a user accessing a kiosk in a retail shop or a device without a browser. Read [here](https://auth0.com/blog/ciba-authenticate-customers-in-call-centers/) for more use cases.

Following the numbered arrows in the diagram, we have:

1. The user interacts with the client application and requests the end user's authentication.
2. The client application submits an HTTP request to the authorization server's `/bc-authorize` endpoint  and then start polling the `/token` endpoint to receive the response.
3. The authorization server sends a push notification to the end user's device.
4. The end user interacts with the push notification. The mobile application retrieves the data associated with the authentication request (consent details) and presents it to the end user. At this point, the end user sends their response, i.e., they can accept or deny the request.
5. The client application receives the end user's response. If the response is successful, it also receives the tokens to perform the requested action.


This is a high-level overview of the CIBA flow. For more details on the messages exchanged by the actors involved in the flow, check out [this document](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authentication-with-ciba).

## The Sample Application

Once you have a high-level understanding of CIBA flow, let's see how to implement it in a .NET application using Auth0.

Assume a call center scenario where an agent with a user on the phone needs to access that user's sensitive data managed by an application. This could be a hospital call center where users ask for information about their medical records. It could also be a tax center where users ask for information about their current tax situation. The agent needs to be sure that the user is who they say they are before giving this information.

You can imagine a screen like the following in front of the call center agent:

![User data screen to initiates the CIBA flow](https://images.ctfassets.net/23aumh6u8s0i/1Uq6DfvHijZcx1eJVkUXZz/156a145dd050bfbca9600255f3ea9371/user-data-screen-to-initiates-ciba-flow.png)

By clicking the "Load sensitive data" button, the agent initiates the CIBA flow to authenticate the user requesting access to their data.

From a technical perspective, the application is a .NET application running on a server. The screenshot above shows a Blazor Web App, but it could be an ASP.NET Core MVC or a Razor Page application. This application has to call a protected API to get the end user's sensitive data, and for this reason, it needs an access token with the appropriate scopes.

The backend application has a mobile counterpart capable of receiving push notifications, and the user must have this application installed on his device, typically a smartphone.

In the following sections, you will learn how to enable CIBA for this application using Auth0. You will start by enabling CIBA support on the backend application and then enable CIBA on the mobile device.

<div className="alert alert-info alert-icon">
  <i className="icon-budicon-487 icon-info"></i>
  <b>This article focuses on the backend application. It mentions how to deal with the mobile application at a high level but redirects you to the specific platform documentation for more details.</b><br> 
</div>


## Add CIBA Support to the Backend App

To add CIBA support to your backend application, you need first to configure your Auth0 tenant and then configure and modify your application's code.

### Enable CIBA support on your Auth0 tenant

To configure your Auth0 tenant to support CIBA, follow these steps in your [Auth0 dashboard](https://manage.auth0.com/):

- Make sure that [your application is registered with Auth0](https://auth0.com/docs/get-started/auth0-overview/create-applications/regular-web-apps) and take note of the domain, client ID, and client secret.
- Scroll down in the application settings and [enable the CIBA flow](https://auth0.com/docs/get-started/applications/configure-client-initiated-backchannel-authentication#configure-ciba-for-your-application).
- Make sure that the API the application is going to call is [registered with Auth0](https://auth0.com/docs/get-started/auth0-overview/set-up-apis) and take note of its identifier, also known as audience.
- Enable [Auth0 Guardian push notifications for your tenant](https://auth0.com/docs/get-started/applications/configure-client-initiated-backchannel-authentication#enable-auth0-guardian-push-notifications-for-your-tenant) and [configure push notifications for MFA](https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa).
- The user must have [enrolled in MFA push notifications](https://auth0.com/docs/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications) to receive them.

Once you have configured your Auth0 tenant, go to your application's source code and update the `appsettings.json` configuration file with the following settings:

```json
// appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Auth0": {
    "Domain": "YOUR_AUTH0_DOMAIN",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientSecret": "YOUR_CLIENT_SECRET",
    "Audience": "YOUR_API_AUDIENCE"
  }
}
```

Replace the `YOUR_AUTH0_DOMAIN`, `YOUR_CLIENT_ID`, and `YOUR_CLIENT_SECRET` placeholders with the respective application setting values from the Auth0 dashboard. Replace the `YOUR_API_AUDIENCE` placeholder with the audience of the API you want to call.

### Initiate the CIBA flow

Now you are ready to implement the CIBA flow in your backend application.

As the first step, install the [Auth0 Authentication API SDK for .NET](https://github.com/auth0/auth0.net) by running the following command in the root folder of your project:

```bash
dotnet add package Auth0.AuthenticationApi
```

The Auth0 Authentication API SDK is a generic .NET client for the [Auth0 Authentication API](https://auth0.com/docs/api/authentication). It's a low-level library that targets .NET Standard 2.0 and can be used in the legacy .NET Framework as well as the most recent .NET versions. At the time of writing, only the Auth0 Authentication API SDK supports CIBA for .NET.

> Check out [this article to learn more about the various Auth0 SDKs for the .NET platform](https://auth0.com/blog/choose-the-right-dotnet-sdk-for-auth0/).

To initiate the CIBA flow, we assume that when the call center agent clicks the "Load sensitive data" button, the following C# method is called with the user ID as its parameter's value:

```csharp
private async void GetUserData(string userId)
{
  var authenticationApiClient = new AuthenticationApiClient(new Uri($"https://{Configuration["Auth0:Domain"]}"));

  var response = await authenticationApiClient.ClientInitiatedBackchannelAuthorization(
    new ClientInitiatedBackchannelAuthorizationRequest()
    {
      ClientId = Configuration["Auth0:ClientId"],
      ClientSecret = Configuration["Auth0:ClientSecret"],
      Audience = Configuration["Auth0:Audience"],
      Scope = "openid profile read:sensitivedata",
      BindingMessage = "Request to access your private data",
      LoginHint = new LoginHint()
        {
          Format = "iss_sub",
          Issuer = $"https://{Configuration["Auth0:Domain"]}/",
          Subject = userId
        }
    });

  var isAuthorized = false;
  var isPendingAuthorization = true;
  var cibaTokenResponse = new ClientInitiatedBackchannelAuthorizationTokenResponse();

  while (!isAuthorized && isPendingAuthorization)
  {
    try 
    {
      cibaTokenResponse = await authenticationApiClient.GetTokenAsync(
        new ClientInitiatedBackchannelAuthorizationTokenRequest()
        {
          AuthRequestId = response.AuthRequestId,
          ClientId = Configuration["Auth0:ClientId"],
          ClientSecret = Configuration["Auth0:ClientSecret"]
        });
      
      isAuthorized = true;
      isPendingAuthorization = false;
    } catch (ErrorApiException ex)
    {
      if (ex.ApiError.Error == "authorization_pending") 
        Thread.Sleep(5000);
      else
        isPendingAuthorization = false;
    }
  }

  if (isAuthorized)
  {
    await LoadSensitiveUserData(cibaTokenResponse..AccessToken);
  }
}
```

The `userId` parameter contains the ID value of the user in the context of Auth0. Typically, it's a string in the form of `auth0|3813a4b5e...`. Let's break down the code of the `GetUserData()` method into its main parts.

> Be aware that the code shown here is a simplified version of the code you should have in production. Its goal is to explain how to implement the CIBA flow, ignoring performance details and other optimizations.

### Send the CIBA request

Consider the first section of the method:

```csharp
private async void GetUserData(string userId)
{
  var authenticationApiClient = new AuthenticationApiClient(new Uri($"https://{Configuration["Auth0:Domain"]}"));

  var response = await authenticationApiClient.ClientInitiatedBackchannelAuthorization(
    new ClientInitiatedBackchannelAuthorizationRequest()
    {
      ClientId = Configuration["Auth0:ClientId"],
      ClientSecret = Configuration["Auth0:ClientSecret"],
      Audience = Configuration["Auth0:Audience"],
      Scope = "openid profile read:sensitive-data",
      BindingMessage = "Request to access your private data",
      LoginHint = new LoginHint()
        {
          Format = "iss_sub",
          Issuer = $"https://{Configuration["Auth0:Domain"]}/",
          Subject = userId
        }
    });

  //...other code...
}
```

In this part, you create an instance of the `AuthenticationApiClient` class by passing the URL of your Auth0 tenant. Then, you start the CIBA flow by calling the `ClientInitiatedBackchannelAuthorization()` method. This method is responsible for submitting the HTTP request to the `/bc-authorize` endpoint of Auth0. It needs the details of the authorization request, which is passed through an instance of the `ClientInitiatedBackchannelAuthorizationRequest` class.

Apart from the client ID, client secret, and audience, a few other values are passed in the request:

- **Scope**. This is the string containing the [scopes](https://auth0.com/docs/get-started/apis/scopes) requested by the application. In addition to `openid` and `profile`, which are OpenID Connect standard scopes to get the user profile data in an ID token, notice the `read:sensitive-data` scope, which is a specific permission request to access the user's sensitive data.
- **BindingMessage**. This is a message displayed on the user's device to let them know about the request. This ensures that the action taken on the authentication device (the user's phone) is related to the request sent by the application.
- **LoginHint**. It's an object containing information to identify the user who should authorize the requester to access their sensitive data.

### Wait for a CIBA response

After the CIBA request is submitted, the backend application waits for a response from Auth0. This response depends on the action taken by the user on their device, so you need to poll the Auth0's `/token` endpoint to get the needed tokens:

```csharp
private async void GetUserData(string userId)
{
  //...other code...
  var isAuthorized = false;
  var isPendingAuthorization = true;
  var cibaTokenResponse = new ClientInitiatedBackchannelAuthorizationTokenResponse();

  while (!isAuthorized && isPendingAuthorization)
  {
    try 
    {
      cibaTokenResponse = await authenticationApiClient.GetTokenAsync(
        new ClientInitiatedBackchannelAuthorizationTokenRequest()
        {
          AuthRequestId = response.AuthRequestId,
          ClientId = Configuration["Auth0:ClientId"],
          ClientSecret = Configuration["Auth0:ClientSecret"]
        });
      
      isAuthorized = true;
      isPendingAuthorization = false;
    } catch (ErrorApiException ex)
    {
      if (ex.ApiError.Error == "authorization_pending") 
        Thread.Sleep(5000);
      else
        isPendingAuthorization = false;
    }
  }
  
  //...other code...
}
```

You can see a few variables that help control the loop you are about to start.

Within this loop, you call the `GetTokenAsync()` method to get a response from Auth0. This method needs an object as its parameter, which includes the request ID and the application credentials.

Until a positive response is received from the user, you will get an `authorization_pending` exception. In this case, you should suspend the current thread and retry after a few seconds. In the example above, the thread waits 5 seconds. If the user denies authorization, you get an `access_denied` exception.

If the user authorizes the request, you get a response in the `cibaTokenResponse` object containing the ID and access tokens.

> You should catch opportunely the exceptions you get and give the user an appropriate message about why the CIBA flow was not completed.

### Use the tokens

Finally, you have the access token that allows you to call the API to get the user's sensitive data:

```csharp
private async void GetUserData(string userId)
{
  //...other code...
  
  if (isAuthorized)
  {
    await LoadSensitiveUserData(cibaTokenResponse..AccessToken);
  }
}
```

We don't go into the details of calling the protected API using the access token. If you need guidance on this, check out [this article](https://auth0.com/blog/call-protected-api-in-aspnet-core/#Use-Your-Access-Token).

> We have omitted the step of validating the tokens received for simplicity, but it is fundamental for the application's security. Read [this article to learn more about token validation in .NET](https://auth0.com/blog/how-to-validate-jwt-dotnet/). Specifically, read [this section](https://auth0.com/blog/how-to-validate-jwt-dotnet/#Validate-a-JWT--By-Hand-) to learn how to validate them without using a middleware, which applies in our case since we are using the Auth0 Authentication API SDK.

## Add CIBA Support to the Mobile App

While this article focuses on the implementation of the backend application, we can't help but provide some information on its mobile counterpart.

First, you should use the [Auth0 Guardian SDK](https://auth0.com/docs/secure/multi-factor-authentication/auth0-guardian) to handle the communication with Auth0 on your mobile app.

While developing your mobile application, you should take care of the following steps in the CIBA flow:

- Your mobile app [receives the push notification](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authentication-with-ciba#step-4-mobile-application-receives-the-push-notification) from Auth0.
- Then it [retrieves the details of the CIBA request](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authentication-with-ciba#step-5-mobile-application-retrieves-the-consent-details), in particular, the binding message.
- The app [presents the binding message to the user](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authentication-with-ciba#step-6-mobile-application-presents-the-consent-details-to-the-user), asking them to accept or deny the request.
- Finally, it manages the user's response by [sending it back to Auth0](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authentication-with-ciba#step-7-mobile-application-sends-the-user-response-back-to-auth0).

## Summary

This article has given you a high-level idea of what CIBA is and in what scenarios you can use it.
Then, you learned how to configure your Auth0 tenant and application to support CIBA. So, you have seen how to integrate CIBA into a .NET application that runs on a server and what steps to consider when developing the mobile counterpart.

Stay tuned for future evolutions of CIBA support in Auth0.

Use CIBA Authentication with Auth0 and .NET

Find out how you can improve your customers' security and authentication experience using CIBA.

Imagine you're a customer trying to resolve an urgent issue over the phone—for example, a bank transaction, an online order, or a technical support request. Before the agent can help, they need to verify your identity. They ask you for your security passcode, which you’ve forgotten. Then come the security questions: your birthday, your last bank transaction, your best friend's name. These questions are easily compromised and create security concerns.

This frustrating experience is all too common across industries. From financial services to retail, organizations face the challenge of verifying customers securely and efficiently for online, over-the-phone, and in-person interactions. That's where CIBA comes in.

In this blog post, we’ll explore how our new [**Client-Initiated Backchannel Authentication (CIBA**](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authentication-with-ciba)**)** feature, part of Auth0, improves customer authentication for call centers and in-person interactions. CIBA makes authentication faster, more secure, and eliminates the need for outdated PINs or security questions.

## Moving Beyond Less Secure Security Questions and OTPs

Call centers are just one out-of-band scenario currently burdened with inconvenient and insecure authentication protocols. Say you’re trying to verify your Identity so you can personalize the settings in your new car, but in order to do so you need to go through a cumbersome process: open the car’s app, scan a QR code, open a browser and log in –all before you can update your personal settings. Or maybe you’re trying to pick up a retail order in person, but in order to do so, you need to authenticate yourself with security questions or personal information. The problem is that these questions are vulnerable to data breaches and phishing attacks (just like passwords) and revealing private information directly to agents creates obvious privacy concerns that customers shouldn’t have to deal with.

Some organizations may try to get around this by using SMS or emailing one-time passwords (OTPs). However, these methods often introduce an additional, cumbersome step into the authentication process and present security challenges. SMS for example is vulnerable to SIM Swapping, which allows attackers to intercept SMS OTPs. Email OTP assumes that the email account is secure, which may not be the case. Plus, both email and SMS OTPs are vulnerable to the typical phishing and social engineering attacks that trick people into compromising their OTP, and they lack biometric authentication methods (e.g. face ID, fingerprint, etc.).

CIBA offers a more consumer-friendly and secure way of authenticating “out-of-band” customers.

## CIBA: A Superior Approach to Out-of-Band Authentication

Safe, seamless brand experiences go beyond the login box. They extend to critical customer touchpoints—like when customers seek support over the phone, online, or in person. CIBA empowers businesses to deliver **both enhanced security and a smoother user experience**, leading to stronger customer satisfaction and better business outcomes. Let’s unpack what CIBA is and how it drives business success:

**Client Initiated Backchannel Authentication (CIBA)**—also known as a **decoupled authentication flow**—is a protocol that enables a client application (e.g., call center systems, POS terminals, in-person service tools, or autonomous AI Agents) to initiate the authentication process on behalf of the customer.

Let’s walk through an example workflow.

A user would like to withdraw from their bank and agrees to initiate the CIBA mobile app verification process.

![Initiate the CIBA verification process](https://images.ctfassets.net/23aumh6u8s0i/4Z2y3Etq6z8cYdxMHwEHDJ/636c00a03bb28fc64e73e1daebff455d/Uploaded_from_Okta_CIBA_blog_v1)

Right away, the user gets a notification on their phone to approve the request and authenticates with biometrics through the app.

![CIBA flow: the user gets a notification on your device](https://images.ctfassets.net/23aumh6u8s0i/3F7yYxI2qaHLys12sLQcuB/dcb6b0227f0388a95f369023b95f69f3/Uploaded_from_Okta_CIBA_blog_v1)

Lastly, the user approves the request and seamlessly and securely continues their withdrawal.

![CIBA flow: User approves the authentication request](https://images.ctfassets.net/23aumh6u8s0i/QOu1PqIN7gV6Bn5Mars8Q/bd13772e469354c82bfb62a0c780c77a/Uploaded_from_Okta_CIBA_blog_v1)

## Achieving Better Business with CIBA

CIBA improves your business and your customer experience with some great features:

### Stronger Security and Privacy

Traditional out-of-band authentication methods, like security questions or email/SMS one-time passwords (OTPs), are insecure and frustrating. CIBA replaces these outdated approaches with **secure, seamless in-app biometric authentication** (e.g., Face ID or fingerprint). A simple push notification lets customers verify their identity effortlessly with **just one tap**, without sharing sensitive personal information.

### A Financial-Grade Protocol

Trusted by financial institutions, CIBA is a **financial-grade protocol** that provides stronger safeguards against phishing and data breaches. By securing highly sensitive customer interactions, CIBA acts as a **robust fraud prevention tool**, protecting both businesses and customers from scams and breaches.

### Non-Repudiation for Trust

A CIBA authentication flow with the [Guardian mobile SDK](https://auth0.com/docs/secure/multi-factor-authentication/auth0-guardian) supports **non-repudiation**—so that neither party in a communication can deny their involvement. For example, in a call center scenario, this prevents customers or agents from disputing that certain information was exchanged. Non-repudiation builds trust and ensures authenticity for sensitive interactions.

### Enhanced Customer Experience (CX)

CIBA delivers smoother CX with **one-tap in-app authentication** —no browser redirects. This simple, efficient flow reduces abandonment rates, increases app engagement, and empowers customer-facing teams to drive satisfaction and business growth.

With [**Auth0 Guardian SDK**](https://auth0.com/docs/secure/multi-factor-authentication/auth0-guardian), you can further enhance CX by customizing every aspect of the CIBA customer journey to reflect your brand and meet unique business needs—creating an experience that’s as secure as it is smooth.

## CIBA in Action: Real-World Examples

A decoupled authentication flow leveraging CIBA adds a much-needed security boost to sensitive interactions, all while supporting seamless customer experiences across a number of different scenarios and use cases:

*   **Call center verification**.
Say you’re a financial services institution, and a customer is calling in to request help with their bank account. Using CIBA, the bank teller can authenticate the customer by sending a push notification to the banking app your customer has installed on their phone. There, they can confirm their identity using the already-enabled biometric sign-in. No more asking customers to share SMS passcodes or make their social security numbers, and (forgotten!) answers to security questions vulnerable by speaking them out loud.

*   **In-person verification**.
In all kinds of in-person scenarios (e.g., withdrawing money at a bank, checking into a hospital, picking up meds at the pharmacy) CIBA gives employees the option of confirming customers’ Identity in real-time by initiating a push notification sent immediately to their phone. The alternative in these situations is often asking customers to present physical documentation such as utility bills or their driver's licenses––an insecure authentication method that can leave customers vulnerable to fraud if they are stolen or compromised.

*   **Connected device verification**.
CIBA also allows internet-connected devices to initiate push notifications in IoT scenarios. For example, if a customer is registering a new car and customizing their settings, CIBA lets them kick off this process in an easy, authenticated manner by confirming their Identity through a push sent directly to a consumer app. Not only is this a more secure means of authentication, it also allows customers to avoid clunky options currently on the market, e.g., scanning a QR code that redirects to the app.

*   **POS terminal**.
In a retail environment that increasingly favors hybrid shopping experiences (e.g. ordering furniture online and picking it up in person) a CIBA flow allows customers to confirm their Identity on-site through self-serve kiosks that initiate a push notification sent to the customer’s phone. This not only keeps the transaction secure, but it also eases any labor constraints retailers might be experiencing by preventing employees from getting roped into the authentication process.

**Better security. Better CX. Better business.**.
CIBA represents a new addition to the security toolbelt for organizations looking for a more secure, more seamless way of authenticating users in call center scenarios and beyond.

Curious about where CIBA can improve your operations––and your bottom line? [Schedule a demo with your account rep](https://auth0.com/contact-us) to see it in action.

CIBA: Authenticate Customers in Call Centers and Other Out-of-Band Scenarios

Ryan Quinn

Community Support and Engagement Specialist (FGA)

In this post, we will focus on adding fine-grained authorization to your Python Flask application using OpenFGA.

Fine-grained authorization (FGA) refers to the capability of granting individual users permission to perform particular actions on specific resources. Effective FGA systems enable the management of permissions for a large number of objects and users. These permissions can undergo frequent changes as the system dynamically adds objects and adjusts access permissions for its users.

[OpenFGA](https://openfga.dev/) is an open-source Relationship-Based Access Control (ReBAC) system designed by Okta for developers and adopted by the Cloud Native Computing Foundation (CNCF). It offers scalability and flexibility and supports the implementation of RBAC and ABAC authorization models. By moving authorization logic outside the application code, OpenFGA makes it simpler to evolve authorization policies as complexity grows.

[Flask](https://flask.palletsprojects.com/en/3.0.x/) provides a simple framework for rapidly creating web applications in Python. Using add-ons like [SQLAlchemy](https://www.sqlalchemy.org/) and authentication with Auth0, you can save development time and focus your efforts on your application’s core functionality.

In this guide, we will build a simple application that shows how to incorporate OpenFGA, allowing you to leverage the benefits of fine-grained authorization with Flask.

## Prerequisites

Before we start, let's be sure you have the following installed on your development machine:

- **Python 3.x**
- **Flask**
- **SQLAlchemy**
- **authlib**
- **requests**
- **[OpenFGA SDK for Python](https://github.com/openfga/python-sdk)**

Once you have Python installed, you can install the necessary packages using `pip3`.

> On some systems, the command `pip` may be used in place of `pip3`:

```bash
pip3 install Flask Flask-SQLAlchemy python-dotenv requests openfga_sdk authlib
```

You’ll also need an OpenFGA server instance running. You can use a managed instance like [OktaFGA](https://www.okta.com/products/fine-grained-authorization/) or set up a local instance with Docker with:

```bash
docker run -p 8080:8080 openfga/openfga run
```

## Project Setup

Let's set up the project structure:

```
flask_openfga_tutorial/
├── app/
│   ├── __init__.py
│   ├── models.py
│   ├── routes.py
│   ├── templates/
│   │   ├── base.html
│   │   ├── index.html
│   │   ├── resource.html
├── config.py
├── model.fga
├── run.py
└── requirements.txt
```

- `app/`: This directory contains our Flask application code, including our database model, our route handlers, and our functions that interact with OpenFGA.
- `templates/`: Contains HTML (jinja2) templates for our web interface.
- `config.py`: Configuration settings for Flask and OpenFGA.
- `model.fga`: Our OpenFGA authorization model.
- `run.py`: The entry point for our Flask application.
- `requirements.txt`: Lists our project dependencies.

## Configuring Flask, SQLAlchemy, and AuthLib

### config.py

In our `config.py`, we will define the configuration for our Flask application. We will read sensitive values using `os.getenv()`, which allows us to use a `.env` file in our project directory or from environment variables.

```python
# config.py

import os
from dotenv import load_dotenv

load_dotenv()

class Config:
    SECRET_KEY = os.getenv('SECRET_KEY')
    SQLALCHEMY_DATABASE_URI = os.getenv('DATABASE_URL', 'sqlite:///db.sqlite3')
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    FGA_API_URL = os.getenv('FGA_API_URL', 'http://localhost:8080')
    FGA_STORE_ID = os.getenv('FGA_STORE_ID')
    FGA_MODEL_ID = os.getenv('FGA_MODEL_ID')
    AUTH0_CLIENT_ID = os.getenv('AUTH0_CLIENT_ID')
    AUTH0_CLIENT_SECRET = os.getenv('AUTH0_CLIENT_SECRET')
    AUTH0_DOMAIN = os.getenv('AUTH0_DOMAIN')
```

### app/__init__.py

Next, we will initialize Flask, SQLAlchemy, OAuth, and our OpenFGA Client in `app/__init__.py`:

```python
# app/__init__.py

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from authlib.integrations.flask_client import OAuth
from openfga_sdk.client import ClientConfiguration
from openfga_sdk.sync import OpenFgaClient
from config import Config
import os


db = SQLAlchemy()
oauth = OAuth()

def create_app():
    app = Flask(__name__)
    app.config.from_object(Config)

    db.init_app(app)
    oauth.init_app(app)

    # Configure and initialize the Auth0 Client
    oauth.register(
        "auth0",
        client_id=app.config["AUTH0_CLIENT_ID"],
        client_secret=app.config["AUTH0_CLIENT_SECRET"],
        client_kwargs={
            "scope":"openid profile email",
        },
        server_metadata_url=f'https://{app.config["AUTH0_DOMAIN"]}/.well-known/openid-configuration'
    )
    
    #Configure and initialize the OpenFGA Client
    configuration = ClientConfiguration(
        api_url=app.config['FGA_API_URL'],
        store_id=app.config['FGA_STORE_ID'],
        authorization_model_id=app.config['FGA_MODEL_ID'],
    )

    app.fga_client = OpenFgaClient(configuration)
    app.fga_client.read_authorization_models()

    from .routes import main as main_blueprint
    app.register_blueprint(main_blueprint)

    with app.app_context():
        db.create_all()

    return app

```

## Creating Our Launch Script

### run.py

Our `run.py`, in the root directory of our project, is the script we will call in order to run our Flask application:

```python
# run.py

from app import create_app

app = create_app()

if __name__ == '__main__':
    app.run(debug=True)

```

## Defining the Database Models

### app/models.py

We will define the `Resource` model in `app/models.py` to keep track of the resources users create.

```python
# app/models.py

from . import db
import uuid

class Resource(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    uuid = db.Column(db.String(36), unique=True, nullable=False, default=lambda: str(uuid.uuid4()))
    name = db.Column(db.String(120), nullable=False)
    owner = db.Column(db.String(255), nullable=False)

```

## Setting Up the OpenFGA Model

Next, we will create our authorization model in the file `model.fga`. This model will define the types of relationships that can exist between our users and objects:

```plaintext
model
  schema 1.1

type user
  relations
    define owner: [user]

type resource
  relations
    define owner: [user]
    define viewer: owner

```

This model defines two types, `user` and `resource`, and establishes an `owner` relationship. The `viewer` relation is defined to be the same as the `owner`, meaning only owners can view the resource.

### Writing the Model to OpenFGA

We will use the OpenFGA CLI to write our new model for our OpenFGA store. Check the OpenFGA docs to learn [how to use the CLI to create a store](https://openfga.dev/docs/getting-started/cli) where you can write your model. Remember, models, are immutable, so anytime you make changes; you need to write the updated model and update the model ID used in your application.

First, we will create a store where we'll write our model:

```
fga store create --name "FGA Flask Demo Store"
```

The result of that command will include our `store id`, which we will use in our next command to write the model.

```bash
fga model write --store-id <store_id> --file model.fga
```
## Configuring Authentication
This app uses Auth0 for authentication, so to get started, we will need to configure our application to enable authentication.

### Create an Auth0 Account
If you do not have an Auth0 account, create one [here for free](https://auth0.com/signup). 

### Configure an application
Use the interactive selector to create a new Auth0 application.

- Application Type
For Application Type, select "Single Page Application."

- Allowed Callback URLs
Enter `http://localhost:3000/callback` in "Allowed Callback URLs"

- Allowed Logout URLs
Enter `http://localhost:3000/` in "Allowed Logout URLs"

- Allowed Web Origins
Enter `http://localhost:3000` in "Allowed Web Origins"

By default, your app will have two "Connections" enabled to provide user authentication data.

- google-oauth2 - This option allows users to log in with Google. There is no need to configure user accounts with this option
- Username-Password-Authentication - This option allows you to create user accounts in the Auth0 dashboard by specifying usernames and passwords

### Collect required credentials
From your application's page in the Auth0 Dashboard, copy your app's `Domain`, `Client ID`, and `Client Secret`, which we will use later when we configure our application.

## Implementing Routes with AUTH0 and Openfga

### app/routes.py

Next, create the application routes in `app/routes.py`:

```python
# app/routes.py

from flask import Blueprint, request, render_template, redirect, url_for, flash, session, current_app
from .models import Resource, db
from urllib.parse import quote_plus, urlencode
from openfga_sdk.client.models import ClientTuple, ClientWriteRequest, ClientCheckRequest
from app import oauth
import uuid
from functools import wraps

main = Blueprint('main', __name__)

def login_required(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        # This decorated function can be applied to route handers and will ensure that a valid user session is active.
        # If the requestor is not logged in it will redirect their browser to the home page
        if 'user_info' not in session:
            return redirect(url_for('main.login'))
        return f(*args, **kwargs)
    return decorated_function

@main.route("/login")
def login():
    # Login function redirects to the Auth0 login page for our app
    return oauth.auth0.authorize_redirect(
        redirect_uri=url_for("main.callback", _external=True)
    )

@main.route("/callback", methods=["GET", "POST"])
def callback():
    # The callback function that Auth0 will redirect users to after authentication
    try:
        token = oauth.auth0.authorize_access_token()
        session["user_info"] = token['userinfo']    
        session['user_email'] = token['userinfo']['email']
    except Exception as e:
        return redirect(url_for("main.index"))
    return redirect(url_for("main.index"))
    
    

@main.route("/logout")
def logout():
    # Log a user out of the app, clear the session and redirect them to the Auth0 logout url for our app
    session.clear()
    return redirect(
        "https://" + current_app.config["AUTH0_DOMAIN"]
        + "/v2/logout?"
        + urlencode(
            {
                "returnTo": url_for("main.index", _external=True),
                "client_id": current_app.config["AUTH0_CLIENT_ID"],
            },
            quote_via=quote_plus,
        )
    )

@main.route('/')
@login_required
def index():
    resources = Resource.query.all()
    return render_template('index.html', resources=resources, user_info=session.get['user_info'])

@main.route('/create_resource', methods=['POST'])
@login_required
def create_resource():
    resource_name = request.form.get('name')

    resource = Resource(name=resource_name, owner=session.get['user_email'])
    db.session.add(resource)
    db.session.commit()

    # Create a tuple in OpenFGA
    fga_client = current_app.fga_client
    write_request = ClientWriteRequest(
        writes=[
            ClientTuple(
                user=f"user:{session.get['user_email']}",
                relation="owner",
                object=f"resource:{resource.uuid}",
            ),
        ],
    )
    fga_client.write(write_request)

    return redirect(url_for('main.resource', resource_uuid=resource.uuid))

@main.route('/resource/<resource_uuid>')
@login_required
def resource(resource_uuid):
    resource = Resource.query.filter_by(uuid=resource_uuid).first()
    if not resource:
        flash('Resource not found.')
        return redirect(url_for('main.index'))

    # Check permission using OpenFGA
    fga_client = current_app.fga_client
    check_request = ClientCheckRequest(
        user=f"user:{session.get['user_email']}",
        relation="viewer",
        object=f"resource:{resource.uuid}",
    )
    response = fga_client.check(check_request)

    if not response.allowed:
        flash('You do not have permission to view this resource.')
        return redirect(url_for('main.index'))

    return render_template('resource.html', resource=resource)
```

- **User Login**: Users can register or log in using Auth0 via the `login` route.
- **Resource Creation**: Users can create resources, and ownership is established by writing a tuple to OpenFGA.
- **Resource Viewing**: Access to resources is controlled by checking permissions with OpenFGA.

## Creating our Web Templates

### Base Template: `templates/base.html`

Create a base template for consistent layout, our other templates will inherit their top level layout from this template.

```html


<!doctype html>
<html lang="en">
<head>
    <title>{% block title %}OpenFGA Tutorial{% endblock %}</title>
</head>
<body>
    {% with messages = get_flashed_messages() %}
      {% if messages %}
        <ul>
        {% for message in messages %}
          <li>{{ message }}</li>
        {% endfor %}
        </ul>
      {% endif %}
    {% endwith %}
    {% block content %}{% endblock %}
    <a href="/logout">Log Out</a>
</body>
</html>
```

### Index template: `templates/index.html`

This page extends our base template and provides the UI elements for the main page of our application.

```html


{% extends "base.html" %}
{% block title %}Home{% endblock %}
{% block content %}
<h2>Welcome, {{ user_info.name }}!</h2>

<h3>Create a Resource</h3>
<form method="POST" action="{{ url_for('main.create_resource') }}">
    <input type="text" name="name" placeholder="Resource Name" required>
    <button type="submit">Create</button>
</form>

<h3>Resources</h3>
<ul>
    {% for resource in resources %}
        <li><a href="{{ url_for('main.resource', resource_uuid=resource.uuid) }}">{{ resource.name }}</a></li>
    {% else %}
        <li>No resources available.</li>
    {% endfor %}
</ul>
{% endblock %}
```

### Resource template: `templates/resource.html`

This page extends our base template and displays a list of resources a user has access to.

```html


{% extends "base.html" %}
{% block title %}Resource Details{% endblock %}
{% block content %}
<h2>Resource: {{ resource.name }}</h2>
<p>Owned by: {{ resource.owner }}</p>
<a href="{{ url_for('main.index') }}">Back to Home</a>
{% endblock %}
```

## Testing the Application

### Configuration variables

Our application expects several variables to be set as environment variables or in a .env file in our project directory. For this example, we will create a .env file with the following content, including the model and store we created earlier and our Auth0 application details:

```plaintext
SECRET_KEY="your_secret_key"
DATABASE_URL="sqlite:///db.sqlite3"
FGA_API_URL="http://localhost:8080"
AUTH0_CLIENT_ID=""
AUTH0_CLIENT_SECRET=""
AUTH0_DOMAIN=""
FGA_STORE_ID="your fga store id"
FGA_MODEL_ID="your fga model id"
```

- `SECRET_KEY`: A unique value used internally to secure session data in Flask.
- `DATABSE_URL`: In our example, we are using SQLite, but you can also use a MySQL or PostgreSQL connection string.
- `FGA_API_URL`: The URL to connect to your OpenFGA instance. The example above assumes you are running OpenFGA in Docker locally using the command provided earlier.
- `AUTH0_CLIENT_ID`:  The client ID from our application page in the Auth0 Dashboard.
- `AUTH0_CLIENT_SECRET`: The client secret from our application page in the Auth0 Dashboard.
- `AUTH0_DOMAIN`: The domain from our application page in the Auth0 Dashboard.
- `FGA_STORE_ID`: This is the store ID that was returned when you created a store in your OpenFGA instance.
- `FGA_MODEL_ID`:  This is the model ID that was returned when you ran `fga write` to write your model.

### Run the Flask App

Start the application:

```bash
python run.py
```

### Get Started

- Open your browser and navigate to `http://127.0.0.1:5000/`.
- You will be redirected via our login route handler to log in via Auth0. You can log in via one of the OAuth providers you selected or with user accounts created in the Auth0 Dashboard.

### Create a Resource

- After logging in, create a resource by entering a name and clicking "Create".
- The resource will be added to the database, and an ownership tuple will be written to OpenFGA.

### View the Resource

- Click on the resource name to view its details.
- OpenFGA checks whether you have permission to view the resource based on the `viewer` relation.

### Test Access Control

- Log out and create a new user either by logging in with a different OAuth account or by adding another set of login credentials in the Auth0 dashboard.
- Try to access the resource created by the first user by entering its URL directly.
- You should receive a message stating you do not have permission to view the resource.

## Next Steps

This guide presented a basic example of how OpenFGA can be used within a Python Flask application to manage authorization and access to resources. You can find a more detailed example application that implements a web application allowing users to share text files and folders and covers topics including parent-child relationships and sharing resources with others [in this project](https://github.com/openfga/flask-demo).

OpenFGA for Python Flask Applications

Shreya Gupta

Shreya is the Developer Advocate for Auth0 for Startups. She previously founded a non-profit called Bit Project, worked at a YC-backed Startup as a Developer Advocate, and currently hosts The Developer Diaries podcast. Through each experience, she has found her love for building resources and tools that help move the needle for developers. Outside of work, she enjoys traveling, watching K-Dramas, and drinking boba.

Developer Advocate, Startups

Calah Vargas

Calah Vargas is the Associate Manager of Product Led Growth, focusing on nonprofits, startups, and partnerships. She works on product marketing and customer marketing initiatives. Outside work, you can find her cooking, trying new restaurants, and traveling with friends and family.

Associate Manager, PLG

Demo Auth0 - a series where we explore auth use cases and demonstrate how to build them using Auth0

<AmpContent>
<amp-youtube
    data-videoid="fjzahoZQjLs"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>
<NonAmpContent>
<div class='embed-container' style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;"><iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" src='https://www.youtube.com/embed/fjzahoZQjLs' frameborder='0' allowfullscreen></iframe></div>
</NonAmpContent>

Welcome to Demo Auth0, where we discuss different identity use cases proposed by our customers and developers and how they each used Auth0 to solve their specific needs. If you missed our first episode, we featured our good friends at Vercel, where we discussed [our Vercel integration](https://auth0.com/blog/auth0-vercel-integration/), multi-tenancy, and boba; feel free to check it out [here](https://www.youtube.com/watch?v=aU9DWD1RLiM).

In this episode, we sat down with the [Mindfuel](https://www.mindfuel.ai/) team’s CPO and Co-founder, [Max Könnings](https://www.linkedin.com/in/mkoennings/), and Director of Software Engineering, [Anton Reindl](https://www.linkedin.com/in/anton-reindl/). Mindfuel is an [Auth0 for Startups](https://auth0.com/startups/profiles) graduate who helps their customers drive business value from their AI and data. By using Auth0, Mindfuel was able to get up and running quickly and securely. Read on to learn about their implementation journey and where they’re headed next.

## Mindfuel and Delight’s Origin Story

The Mindfuel team started as a consultancy leveraging data science, AI, and product management to support businesses. This resulted in helping clients build data and AI into their services, products, and internal processes, serving many different stakeholders.

“This year, about $150B was invested worldwide in AI and data, and 80% of the technologies never made it to production.” - Max Könnings, Founder and CPO, Mindfuel. To help tackle this problem, the Mindfuel team launched an application called Delight to bridge what they call the “AI business gap” — the gap between what a business needs and how teams can deliver on those needs using AI and data. Delight is a data impact platform that identifies AI opportunities aligned with business needs, assesses them, prioritizes them based on strategic fit, and builds visualizations and reporting to help ensure data-driven decisions. Mindfuel’s biggest competitor is Microsoft Excel. Just as sales teams use CRMs to manage deals, many AI and data leaders manage their projects using Excel. Mindfuel believes in a future where their product will help customers make the right business decisions and will highlight the impact these teams are creating.

<include src="QuoteCard" body="If we come back to the 80% [of technologies] that never make it into production. It’s mostly not because the technology isn’t there, it’s mostly because we have missing management capabilities." name="Max Könnings" title="Founder and CPO" team="" company="Mindfuel" children="" />

## How Mindfuel Leveraged Auth0

Delight is a tool built for businesses that need to collaborate within their teams. The customer base is primarily large enterprises. These enterprises, especially those in Germany and the EU, have very strict data privacy and protection laws that the Mindfuel team must adhere to, and Auth0 helped them navigate this challenge.

<include src="QuoteCard" body="Auth0 is a super partner because it offers flexible configuration options. We have support for multi-factor authentication, and we allow single sign-on for some of our customers. You can set this up instead of investing weeks of development into those features. We can really focus on the core product and not worry about authentication." name="Anton Reindl" title="Director of Software Engineering" team="" company="Mindfuel" children="" />

Many of the backend functions that Delight needed, like resetting passwords or changing a person's email or username, were available out of the box with Auth0. They didn’t have to worry about building their own backups or the overhead needed when you’re not using an out-of-the-box solution.

> Delight leveraged [**Auth0 Organizations**](https://auth0.com/docs/manage-users/organizations) to best support their enterprise customers within the early days of implementation. With Organizations, they created a secure flow for their business users, set up multi-tenancy, added MFA, and integrated SSO for certain customers—this cut weeks' worth of engineering resources down to hours.

Another feature the engineering team leveraged was [Actions](https://auth0.com/docs/customize/actions). Actions are secure, tenant-specific, versioned functions written in Node.js that execute at certain points within the Auth0 platform. The team was able to build Actions that would happen once the customer approached an event, like logging in. This was a real enabler for customization and allowed the team to add this information to each user’s account, for example, to manage users’ MFA settings and Roles.

When evaluating solutions, the ability to monitor logs and workflows was a priority for the Mindfuel team. With Auth0’s[ integration with Datadog](https://marketplace.auth0.com/integrations/datadog-log-streaming) and a few clicks, the team could see all of the data from Auth0 streamed into Datadog. For example, if one of their users has trouble signing in, the team receives a Slack alert so their customer success team can immediately reach out and help.

Pivoting from the development perspective, Auth0 also supported Mindfuel with its GTM motion. Since they are a small startup that sells to larger enterprises, the sales process is very complex, especially because more regulatory and compliance topics are surfacing in Europe and elsewhere. By using a trusted and well-known solution and leveraging features like SSO, Mindfuel was able to instill confidence in its enterprise buyers and seamlessly adapt to their requirements.

## What’s Next for Mindfuel

Mindfuel is launching its new product, Delight Spark, soon. With Delight Spark, the business side of a company can interact conversationally with AI and data teams. For example, if someone on the team wants to increase a conversion rate, the tool will extract information from the business users and ideate with them about more opportunities. This helps extend the Delight product and makes it more approachable for the entire company, meaning fewer Slacks and emails that block the data and AI teams from building and maintaining their products.

If you want to dig deeper into Mindfuel’s interview and hear their insightful advice to other startup founders, check out the video [here](https://www.youtube.com/watch?v=fjzahoZQjLs\&list=PLshTZo9V1-aFWgshQYa0w80tcv8HLffc6). If you’re interested in joining Mindfuel and 4000+ other startups that have been a part of Auth0 for Startups, apply [here](https://auth0.com/startups/profiles). Happy building!


How Mindfuel Builds and Monitors Auth with Organizations, Actions, and Datadog

Native login with passkeys is now available, so let’s take a look at how to sign up and log in on Android using Auth0’s Native Login.

How to Sign Up and Log In with Passkeys in Android Using Auth0's Native Login

Learn how to prevent CSRF attacks from compromising your users when implementing Google OAuth for user registration and user login.

Growing an active user base is a top priority for all developers. Your product pages need copy, design, and engineering that can efficiently and effectively convert visitors into users. A visitor is an anonymous person browsing your site or app. A user is a visitor who exchanges some information to access more layers or features of your app. Even with just an email address or username, you can build a profile or identity for a user.

As such, user authentication is the backbone of conversion. User registration and login must be secure and as frictionless as possible. Long and tedious forms or requirements during registration can turn prospects away. Errors or downtime during login can frustrate even your most loyal customers, leading to dissatisfaction or support tickets.

## Why Use Google OAuth for User Authentication

A reliable way to implement user registration and authentication in an application and turn visitors into users quickly and securely is by using a registration and authentication system that your visitors already use and trust, such as Google.

As a developer, you can take advantage of Google's high security and trust Google as a source to safeguard user credentials so that you don't have to. Google social login leverages the OAuth 2.0 protocol for authorization and uses [OpenID Connect (OIDC)](https://developers.google.com/identity/openid-connect/openid-connect) as the standard for user authentication. You can delegate to Google's UI/UX and engineering the burden of password requirements, password protection, password error handling, email verification, profile data collection, and more. 

How easy or difficult is it to implement Google Login on your own? It depends. On the surface, it may be like a simple endeavor: In the JavaScript ecosystem, use a library like [`google-auth-library`](https://www.npmjs.com/package/google-auth-library), write a few lines of code, and call it a day.

While `google-auth-library` is a robust client library for using OAuth 2.0 authorization and authentication with Google APIs, it's essential to know how to use it effectively to avoid introducing security vulnerabilities in your application that could put your end-users and your organization at risk.

For instance, a recent [post on X](https://x.com/forgebitz/status/1858616526540042521) went viral: a developer named Klaas shared with the X developer community a code snippet on how to implement "google login with just the google-auth-library, no frameworks in 50 lines of code":

```typescript
export const googleLoginAction = {
  getAuthUrl: () => {
    const query = {
      client_id: oauth_google.client_id,
      redirect_uri: oauth_google.redirect_uri,
      response_type: "code",
      scope: oauth_google.scopes,
    };

    const url = new URL(oauth_google.endpoint);
    url.search = new URLSearchParams(query).toString();
    return url.toString();
  },
  verifyGoogleCode: async ({ code }: { code: string }) => {
    log.info({ code }, "verifying google auth code");

    try {
      const tokenResponse = await fetch("https://oauth2.googleapis.com/token", {
        method: "POST",
        headers: {
          "Content-Type": "application/x-www-form-urlencoded",
        },
        body: new URLSearchParams({
          client_id: oauth_google.client_id,
          client_secret: oauth_google.client_secret,
          code,
          grant_type: "authorization_code",
          redirect_uri: oauth_google.redirect_uri,
        }),
      });

      const tokenData = (await tokenResponse.json()) as { id_token: string };

      const ticket = await client.verifyToken({
        idToken: tokenData.id_token,
        audience: oauth_google.client_id,
      });

      const userData = ticket.getPayload();
      log.info({ userData }, "google auth successful");
    } catch (error) {
      log.error({ error }, "failed to verify google auth code");
      throw new Error("Failed to verify Google authentication");
    }
  },
};
```

Klaas' X post ignited a passionate discussion around user authentication and general security. As of the time of writing, the post had gathered 449k impressions, 4.7k likes, 387 reposts, and 83 comments.

## Google OAuth Implementation Can Go Wrong

Some of the commenters asked questions about the code's security posture, while others offered insights and advice on how to improve the security of that Google OAuth implementation.

Some commenters assumed the code was running on the client and were alarmed by the code handling a client secret, which could lead to a security compromise. Klaas clarified that the code is intended to run in the backend and [further explained its purpose as follows](https://x.com/forgebitz/status/1858776267266441324):

 "_this [code] has two simple functions, create a URL where you redirect the user to and a verify code function, you have the create a /callback (on the server) to get that URL. You still need to make authentication/authorization_"

Some other commenters pointed out that the code could be subject to a [Cross-Site Request Forgery (CSRF) attack](https://en.wikipedia.org/wiki/Cross-site_request_forgery), which confused others: How can there be a CSRF attack if there's no cookie involved or when the code does not run in the client?

First and foremost, let's recap what a Cross-Site Request Forgery (CSRF) attack is. [Andrea Chiarelli](https://auth0.com/blog/authors/andrea-chiarelli), Principal Developer Advocate at Okta, [summarizes a CSRF attack as follows](https://auth0.com/blog/cross-site-request-forgery-csrf/#--What-is-CSRF--):

- A typical Cross-Site Request Forgery (CSRF or XSRF) attack aims to perform an operation in a web application on behalf of a user without their explicit consent.
- The attacker leads the user to perform an action, like clicking a link.
- This action sends an HTTP request to a website on behalf of the user.
- If the user has an active authenticated session on the trusted website, the request is processed as a legitimate request sent by the user.

Andrea warns us that "even though CSRF attacks are commonly associated with session cookies, be aware that [Basic Authentication sessions](https://en.wikipedia.org/wiki/Basic_access_authentication) are also vulnerable to CSRF attacks" and that, in fact, "a CSRF vulnerability relies on the authenticated session management".

[Sandrino Di Mattia](https://x.com/sandrinodm) is a Senior Director on the Product Architecture team at Okta with robust and deep experience in cloud, identity, and security. In the thread, Sandrino commented that the code doesn’t seem to perform any state validation, making it open to CSRF attacks.

You may be wondering like others did: ["CSRF attack without any cookies, must be a new thing"](https://x.com/__morse/status/1858951728852295909). Let's explore how improperly implemented OAuth can lead to a CSRF attack.

## Cross-Site Reference Forgery (CSRF) Are Not About Cookies

Sandrino shares that CSRF is not related to cookies. Missing state validation is the most basic vulnerability in OAuth flows. [OAuth 2.0 specification recommends a `state` parameter](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1) that allows you to verify the authenticated state of your browser. The `state` parameter preserves the browser's authenticated state set by the client in an authorization request, and the authorization server makes it available to the client in the response.

[The `state` parameter helps you mitigate CSRF attacks](https://datatracker.ietf.org/doc/html/rfc6749#section-10.12) by using a unique and non-guessable value associated with each authentication request about to be initiated. That value allows you to prevent the attack by confirming that the value from the response matches the one you sent.

**But how does a CSRF attack work without cookies?**

Sandrino explains that an attacker can go through the OAuth flow but stop right when the redirect with the authorization code to the callback URL happens. Now, the attacker can send the link to the callback URL, including the code, to the victim, which consumes the code on their machine.

Depending on the implementation of your application, a few security, privacy, and data exploits could happen. For example, the attacker's account is now forced on the victim’s browser. The victim now could be uploading docs or filling in and sending personal data to the attacker's account, thinking it’s the victim's account. Or a worse scenario: the victim is already signed in, and now this new identity (the attacker's identity) is automatically linked to the victim's existing account.

## Prevent CSRF Attacks in Google OAuth

Sandrino advises us that preventing this type of attack takes a few lines of code. In practice, on redirect, you store a random value in a cookie. You then send that value to Google using the `state` param. On callback, you validate the incoming `state` parameter with the value in the cookie. If the `state` value in the response does not match the `state` value in the cookie, you reject the login operation and stop further access. The `state` parameter and PKCE can help prevent this type of attack.

> For a deep dive on this topic, you can consult the ["More Guidelines Than Rules: CSRF Vulnerabilities from Noncompliant OAuth 2.0 Implementations"](https://www.cise.ufl.edu/~butler/pubs/dimva15.pdf) paper from the Georgia Institute of Technology and the University of Florida. Check out section 3.3 on page 8.

There's a saying that goes: "You don't know what you don't know". But then, how can you know? By doing precisely what Klaas did: share code with others and be open to feedback and constructive criticism. At the same time, you can leverage the knowledge and expertise of others who have been through similar and more complex situations, which can help you avoid falling into traps or dangerous holes.

You may be thinking, "I can rely on AI for that!" You can use AI tools to learn and understand, but remember that those tools are imperfect, as they are an aggregation of human knowledge and can also make mistakes. There are instances where an AI tool can present you with "security" code with high confidence. Still, that code could be anything but secure, missing the implementation of security best practices or defensive mechanisms.

## Use Libraries to Implement Google OAuth 

It's important to highlight that if you want to implement a standard protocol yourself, you need to understand its specifications well, be aware of its nuances, and follow its details diligently. Instruments like the `state` parameter and all other security measures included in specifications and standards are the result of discussions and experience of industry experts throughout the years.

As developers, we often fall into the dilemma of reinventing the wheel (do it yourself) or relying on those who have already done it in the best way (use a library).

Sandrino suggested in the thread that it's better to use a library like Passport.js over the code shared on the tweet&mdash;or rather, X post. Passport.js implements OAuth 2.0 the way that the standard defines it. You can inspect the implementation of Google OAuth in Passport.js by looking at the [`lib/strategy.js`](https://github.com/jaredhanson/passport-google-oauth2/blob/master/lib/strategy.js) file of the [`passport-google-oauth20`](https://github.com/jaredhanson/passport-google-oauth2/tree/master) npm package.

The `OAuth2Strategy` from Passport is well-documented. The comments in the code can quickly guide you on what's happening through that flow:

- The Google authentication strategy authenticates requests by delegating to Google using the OAuth 2.0 protocol.
Applications must supply a `verify` callback function that accepts an `accessToken`, `refreshToken`, and service-specific `profile` and then calls another `cb` callback function, supplying a `user`. The `user` value should be set to `false` if the credentials are invalid. If an exception occurs, `err` should be set.

Let's see an example of how you'd use Google OAuth login with Passport.js:

```javascript
passport.use(new GoogleStrategy({
    clientID: '123-456-789',
       clientSecret: 'shhh-its-a-secret'
       callbackURL: 'https://www.example.net/auth/google/callback'
     },
     function(accessToken, refreshToken, profile, cb) {
       User.findOrCreate(..., function (err, user) {
         cb(err, user);
       });
     }
));
```

As you inspect the implementation code, you'll notice that Passport.js does much more than handle the login. [OAuth 2.0 provides consented access and restricts actions](https://auth0.com/intro-to-iam/what-is-oauth-2) of what a client app can perform on resources on behalf of the user without users ever sharing their credentials with the application. Using Google OAuth 2.0, you can also request access to user contacts and other resources on the Google platform. As the needs of your application scale, you may see yourself needing a more complex data access policy that calls for more code to write and maintain and more scenarios and edge cases to be aware of.

## Google OAuth Attacks Go Beyond CSRF Attacks

Security is an ever-evolving landscape. It's critical for you to stay on the vanguard regarding security in the industry, especially with the rise of artificial intelligence (AI). Implementing authentication on your own is an investment in money, risk, and time. Relying on robust, time-tested libraries or identity service providers can minimize some of those costs.

As mentioned in the post, implementing social login with Google OAuth for your app is just one piece of the authentication puzzle. Once you have users, you are responsible for protecting the data they entrust you. For example, depending on the region where you operate, you may be subject to regulations around user management and privacy, such as GDPR, which also extends to logs, not just the user data you have in your databases.

As you scale and grow in popularity, you may also gain unwanted attention from bad actors and attackers who may want what you are securing: rich user data. But, even on a small scale, you may become the target of bad actors looking to test their skills to break into apps.

> Recommended read: [The biggest underestimated security threat of today](https://techcrunch.com/2024/11/01/the-biggest-underestimated-security-threat-of-today-advanced-persistent-teenagers/)

In the X thread we have been discussing, Jared Hanson, the creator of Passport.js and a Principal Product Architect at Okta, validated that "checking a nonce or state is highly recommended." Jared added, "It’s less simple, but it protects against common attacks."

[Aaron Parecki](https://aaronparecki.com/), Director of Identity Standards at Okta, reminded me that it's not just CSRF attacks that are the concern when it comes to OAuth 2.0 flows. Even if you fix the CSRF attacks we have described, you could still be open to an OAuth 2.0 authorization code injection attack, which you can prevent with PKCE. You can learn more about that type of attack by watching the video below: 

<AmpContent>
<amp-youtube
    data-videoid="1ot45WwQWJE"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>
<NonAmpContent>
<div className='embed-container' style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;"><iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" src='https://www.youtube.com/embed/1ot45WwQWJE' frameborder='0' allowfullscreen></iframe></div>
</NonAmpContent>

Aaron also hosted an "OAuth Happy Hour", which includes [a demo of the authorization code injection attack](https://www.youtube.com/watch?v=moQidjdV5cw). Be sure to check it out!

Let us know if you'd like a detailed follow-up blog post covering the OAuth 2.0 authorization code injection attack.

## Aside: Use Auth0 to Implement Google Social Login

Auth0 makes it even easier to get started with Google. Every new tenant has the Google social connection enabled by default. You don't even have to set up a Google Cloud project to see Google social login in action. Auth0 maintains a set of developer keys you can use to start testing Google social login in your applications in development. Follow the ["Google Social Connection to Login"](https://developer.auth0.com/resources/labs/authentication/google-social-connection-to-login#introduction) lab to learn how to use those Google dev keys and set up ones for production.


Prevent CSRF Attacks in OAuth 2.0 Implementations

Matthew Pereira

Principal Product Designer

Making reliable and scalable decisions in Identity and Access Management using Auth0

## Introduction and Overview

At Auth0, we understand the importance of choosing the right architecture for applications,** especially for security-focused business customers.** The choice between single-tenant and multi-tenant models significantly impacts scalability, security, and success. Making the choice early is crucial — once customers use the application, change can be tough.

When we talk about software architecture, “tenancy” refers to how resources — like data, application logic, and infrastructure — are allocated and shared among users or customers. Software can be set up in different ways, and each instance (or “tenant”) can be occupied in various ways by customers or user groups. In this article, we’ll use the terms “isolated infrastructure” and “shared infrastructure” to be more specific — more on that in the next section.

Auth0 by Okta is built to support every possible identity and access management (IAM) scenario you might encounter when building SaaS applications. We’re here to make sure your journey is smooth, whether you’re just starting with your first login or scaling to support hundreds of business customers and millions of users around the world. The Auth0 platform can create isolated or shared environments and hybrid architectures. As your customer base grows or your product pivots to meet market demands — like adapting a B2C application to handle B2B sales — Auth0 lets you progressively add IAM capabilities and adjust your identity approach appropriately.

This guide will explore the differences between single-tenant and multi-tenant identity, especially in the context of IAM. We’ll also show you how Auth0 simplifies implementing these models and help you choose the best approach for your B2C or B2B needs.


## Understanding Single-Tenancy vs. Multi-Tenancy

### Making Sense of Single-Tenancy vs. Multi-Tenancy

Different companies, applications, and platforms discuss the topic of ‘tenancy’ in software development in different ways.

* Application developers often describe multi-tenancy as a scenario in which multiple customers (tenants) share a single application and database instance.
* Platform developers often think of a “multi-tenant” scenario as one in which a single customer is accessing multiple instances of their platform (referred to as ‘tenants’).

![Single-Tenancy vs. Multi-Tenancy](https://images.ctfassets.net/23aumh6u8s0i/7oMfZHsVewu8lO6fDudH61/c58098cd910d624d41e76f9344bea51c/single-vs-multi-tenancy.jpg)

Isolation plays a large role in evaluating the pros and cons of different tenancy strategies. Multi-tenancy isn’t usually necessary for isolating between customers or branded experiences. (If you use Auth0 Organizations — we’ll talk about that later.)

### Benefits of Isolation for B2B Applications

Traditionally, isolating each business customer to its own infrastructure in B2B scenarios was a matter of **performance** and **reliability**. But there’s more to the conversation than those two details.

1. **Enhanced Security:** Isolation ensures each organization’s sensitive data is kept separate, reducing breach risks and aiding compliance with regulations like GDPR and HIPAA.
2. **Customizability:** Isolated environments allow tailored setups, enabling unique authentication flows, integrations, and experiences that align with client needs.
3. **Performance Stability:** Isolation prevents one organization’s activities from affecting another’s performance, avoiding issues like the “noisy neighbor” effect.
4. **Dedicated Resources:** Organizations can allocate specific resources, ensuring high availability and reliability for their applications.
5. **Simplified Support:** Troubleshooting is easier in isolated environments, as issues are contained within a single tenant, reducing support complexity.

Signing up for an Auth0 account gives you one “Auth0 tenant”, and you can create additional tenants each for isolating between different:

* Environments (e.g., development, staging, or production)
* Geographic locations (e.g., EU, US, JP) 
* Branded experiences
* Customers

### Drawbacks of Isolation for B2B Applications

1. **Higher Costs**: Traditionally, isolated environments are costlier due to separate resources and infrastructure for each tenant.
2. **Increased Management Complexity**: Managing isolated tenants requires more administrative work, including updates, security compliance, and performance monitoring. Auth0 Teams is a product meant to ease the burden of managing some aspects of your organization across multiple tenants, but there are other aspects that will still be more time-consuming than a shared Auth0 tenant architecture.
3. **Reduced Resource Efficiency**: Isolation can lead to underutilized resources, unlike shared architectures that pool resources efficiently.
4. **Slower Configuration Deployment**: Isolated tenants require separate rollouts or migrating changes across multiple configurations, slowing down the development and operation process. This can also lead to version divergence, when a company has updated one environment but not others, giving different end users different experiences and making debugging and management considerably more difficult.

## Choosing the Right Model for Your Application

### Choosing the Right Model for B2C Applications

Creating a **single shared tenant** for a B2C application offers simplicity, cost-effectiveness, and scalability. Think of it as creating one big, cozy house where all your customers can live together but still have their own private rooms. It’s like magic — you get privacy and security where it matters, but one configuration to manage from one central spot. This means you will have fewer headaches and creates a smoother experience for everyone involved.

The best part? It’s simple. You’re not building and maintaining separate houses for each customer group but one efficient space that can grow as you do. Plus, it’s super flexible: You can easily add new features or tweak settings for every one of your customers at once. Just remember, while this setup is great for many scenarios, make sure it fits your specific needs before diving in. After all, you want your digital home to be just right for you and your customers.

### Choosing the Right Model for B2B Applications

When working on a B2B setup there are different approaches we can take from an architecture perspective. In this section we’ll evaluate different scenarios, and how you can leverage Auth0 to simplify your implementation.

#### Isolated Tenants in a B2B Context

Security is a top priority for business customers in 2024. Imagine giving each of your business customers their own digital fortress. That’s what creating a **separate, isolated tenant** for each business customer is like.

This approach is all about giving your business customers the royal treatment. Each one gets its own space, completely separate from the others, which can be a big selling point for companies that are extra careful about their data and security. It’s like having a series of high-security vaults, each with its own unique key. 

Isolating your business customers to separate tenants also allows for ultimate customization —  each business can have things just the way they like them, from security settings to user management. Plus, if one tenant has an issue, the others aren’t affected. It’s a bit more work on your end to manage multiple tenants, but for businesses that demand top-notch security and personalization, this could be your golden ticket.

Signing up for an Auth0 account gives you one “Auth0 tenant”, and you can create additional tenants each for isolating between different:

* Environments (e.g., development, staging, or production)
* Geographic locations (e.g., EU, US, JP) 
* Branded experiences
* Customers

#### Auth0 with Organizations in a B2B Context

Let’s chat about a useful middle-ground approach using [Auth0 Organizations](https://auth0.com/docs/manage-users/organizations) to manage B2B users in a single Auth0 tenant. This is like having a massive, secure office building where each of your business customers gets their own floor. Every floor can have its own layout, look, and feel, but as the application owner, you enjoy the simplicity of managing one building, not a whole city block. 

With this approach, B2B customers get customizable security, branding, and identity provider connections while you get to keep all the perks of managing a single tenant. It's simpler to oversee, and you can still roll out cool new features to everyone at once. Plus, you've got the flexibility to customize each “floor” to fit that particular business needs. Every customer can have their own SSO connection and their own members (or, in more complex use cases, their own distinct databases of members), managed within a single Auth0 tenant. It’s a win-win.

### Choosing a Hybrid Model with Shared B2C Tenant and Isolated B2B Tenants

Modern product development is complicated, and our software often has to play multiple roles. If you’re exploring a combination of B2C and B2B usage, you can also approach a hybrid solution to your IAM needs.

Imagine you’ve got a bustling community center (your B2C shared tenant) where all your individual consumers hang out. It’s vibrant, cost-effective, and easy to manage. But right next door, you’ve got a row of private clubhouses (your B2B isolated tenants), each tailored for a specific business client.

This hybrid approach lets you seamlessly cater to both worlds. Your B2C users get a unified, streamlined experience in their shared space — and you get the perks of managing it in a centralized fashion. Meanwhile, your B2B clients each get their own fortress of solitude, complete with custom security and features.

This setup is perfect if your product needs to juggle the different demands of individual consumers and business clients. You get to optimize your resources for the B2C crowd while still offering that extra layer of isolation and customization that B2B clients often crave.

## Implementation with Auth0

### Creating Isolated Tenants Using Auth0

In Auth0, single-tenancy can be implemented by creating separate Auth0 tenants for each customer. This allows for granular control over the IAM needs of each tenant, ensuring their data and configurations remain isolated. These tenants can be deployed to different regions or configured independently to serve different user pools or compliance needs.

[Learn more about creating tenants in the Auth0 Docs](https://auth0.com/docs/get-started/auth0-overview/create-tenants).

### Creating a Shared Tenant Using Auth0 — Introducing Organizations

Organizations in Auth0 is a feature that allows you to manage and group users who should have access to particular applications. By managing multiple organizations within one Auth0 tenant, you can:

1. Centralize user management and authentication
2. Reduce administrative overhead
3. Maintain consistent security policies
4. Simplify billing and licensing
5. Leverage shared resources and configurations to work faster without working harder

[Learn more about how Organizations work in the Auth0 Docs](https://auth0.com/docs/manage-users/organizations/organizations-overview).

## Conclusion

Whether you opt for a single shared tenant, isolated tenants for each business customer, or a hybrid approach using something like Auth0 Organizations, choosing the right tenancy model for your application is crucial for long-term success. Remember, the best solution depends on your specific needs, balancing factors like security, customization, scalability, and management complexity.

Auth0 provides the flexibility and tools to support you, whatever you choose. As you embark on your journey to build robust B2B or B2C applications, consider exploring Auth0’s comprehensive offerings:

* Learn about [Auth0 Public Cloud and Private Cloud offerings](https://auth0.com/platform/cloud-deployment) to find the right fit for your infrastructure needs.
* Try [Auth0 Organizations](https://auth0.com/organizations) to experience multi-tenancy with built-in security and scalability in an all-in-one centralized management environment.
* Kickstart your B2B SaaS development with [Auth0’s B2B SaaS Starter](https://auth0.com/blog/speed-up-your-customer-identity-journey-with-auth0-saastart/), which includes advanced B2B identity capabilities from the get-go.

By leveraging Auth0’s powerful IAM solutions, you can focus on creating value for your customers while ensuring secure, scalable, and efficient user management.

Building Single-Tenant vs. Multi-Tenant Apps with Auth0

Take control of your encryption keys using the BYOK security model in your Auth0 tenant.

As the cloud continues to spread and sensitive data is entrusted to service providers, customers wonder how it is protected and how they can exercise control over the security of their data. One way to allow a customer to take control of the confidentiality of their data is to use the Bring Your Own Key (BYOK) approach. In this article, you'll learn what BYOK is and how you can leverage it in Auth0.

## What Is Bring Your Own Key?

Cloud service providers secure customer secrets and data using [envelope encryption](https://en.wikipedia.org/wiki/Hybrid_cryptosystem#Envelope_encryption). This is a proven security mechanism that ensures a high level of protection of customer data using a hierarchy of encryption keys. Specifically, to encrypt data, the cloud provider platform uses Data Encryption Keys that are wrapped by a Root Key. So, to access the Data Encryption Key, a service needs access to the Root Key. Optionally, other intermediate keys can exist between the Data Encryption Keys and the Root Key.

This hierarchy not only enables data protection but also aims at protecting the encryption keys. Encryption and decryption of data are performed by a Key Management System (KMS) that leverages this key hierarchy. In addition, most cloud providers use a Hardware Security Module (HSM) to store the Environment Root Key, ensuring the strongest protection.

In the end, customers' sensitive data are encrypted using the Data Encryption Key, but due to this key hierarchy, only those who have access to the root key of this hierarchy can actually access the unencrypted data.

### Why BYOK?

Usually, the cloud service provider issues and manages the Root Key. Ultimately, the cloud service provider has control over the key hierarchy, the data encryption, and the security of the customer data. However, this is not always the situation that a customer wants. There may be several reasons why a customer doesn't want the cloud service provider to control the Root Key and then the key hierarchy:

- They may need to comply with some key provenance requirements.
- They may need to comply with some data protection requirements.
- They may need to attain control of the lifecycle of the cryptography for users' sensible data.

Think of the financial or healthcare sectors, where data confidentiality is key. In these cases, cloud service providers allow customers to issue and use their own encryption key as the Root Key for the key hierarchy, hence the name **Bring Your Own Key** (BYOK) for this approach to take control of the encryption in a cloud environment.

## BYOK in Auth0

As with any cloud service provider, Auth0 by Okta uses envelope encryption to secure customer data, too. To encrypt data, Auth0 uses Data Encryption Keys that are wrapped by a Tenant Master Key, which in turn is wrapped by the Environment Root Key. Take a look [here](https://auth0.com/docs/secure/highly-regulated-identity/customer-managed-keys#auth0-key-hierarchy) to have more details on the Auth0 key hierarchy.

Auth0 stores the Environment Root Key in a Hardware Security Module (HSM), which is deployed in a highly available, multiple geographic configuration. In other words, the HSM will failover to another region in case of a severe region-wide incident. The HSMs are available for [the two private cloud deployments](https://auth0.com/docs/deploy-monitor/deploy-private-cloud) supported by Auth0 &mdash; AWS and Azure &mdash; with [different encryption algorithms](https://auth0.com/docs/secure/highly-regulated-identity/customer-managed-keys#environment-root-key).

With BYOK, Auth0 allows tenant administrators to securely import their own Root Key to the respective cloud provider's HSM. They can use the Auth0 Dashboard or Management API to replace the Auth0 Environment Root Key with their own Customer Provided Root Key, as you will see in the next section.

> Bring Your Own Key is available on [Enterprise plans](https://auth0.com/pricing) with [Highly Regulated Identity](https://auth0.com/docs/secure/highly-regulated-identity) add-on.

## How to Bring Your Key in Auth0

In this section, you will learn how to import your own encryption key in your Auth0 environment using the Auth0 dashboard. Make sure you have an Enterprise plan with the Highly Regulated Identity add-on to be able to use this feature. Basically, the process consists of three steps:

1. Generate and download a wrapping encryption key from the Auth0 dashboard.
2. Generate your own encryption key and wrap it with the downloaded wrapping encryption key.
3. Upload the wrapped encryption key via the Auth0 dashboard.

For demo purposes, you will use OpenSSL to generate and wrap your encryption key, but in a real-world scenario, you should use an HSM, either on-premises or cloud-based, for key generation.

> Make sure you have [OpenSSL](https://www.openssl.org/) installed on your machine. If you have a macOS machine, be aware that it ships with [LibreSSL](https://www.libressl.org/), which is a fork of OpenSSL and has some differences.

### Get the wrapping encryption key

The first step is to get the wrapping encryption key from Auth0. Go to your [Auth0 dashboard](https://manage.auth0.com), click the *Settings* menu item, and select the [Encryption Keys](https://manage.auth0.com/#/tenant/encryption_keys) tab. You will see the following screen:

![Encryption keys management in the Auth0 dashboard](https://images.ctfassets.net/23aumh6u8s0i/3PBjaL5gFyc2iULvFb8ZSk/ad53ccc8484a587cdbea4ed60dec1efd/auth0-dashboard-encryption-keys.png)

Now, click the *Upload Key* button and you will get the modal shown below:

![Download Auth0 wrapping encryption key](https://images.ctfassets.net/23aumh6u8s0i/2ED5p9T6aUpnWPZkGffLcn/ac4069f77c95709a1034d6c80bc3bbef/download-wrapping-encryption-key.png)

Click the *Download* button to get the wrapping encryption key from Auth0. This ensures that your own key will be securely transferred to Auth0.

> Until you have uploaded your own key, Auth0 will continue to use the built-in Environment Root Key.

### Generate and wrap your own key

If you are using a Hardware Security Module to generate your key, follow its specific instructions. For test purposes, we are using Open SSL here, which requires some preprocessing of the content of the PEM file you downloaded from Auth0, the key generation, and then the actual key wrapping. Let's examine each step.

#### Preprocess the wrapping key

Open the file with a text editor and manually remove the PEM header and footer, i.e., the `-----BEGIN PUBLIC KEY-----` and `-----END PUBLIC KEY-----` strings. Then, remove all the line breaks in the file. The result will be a one-line file with the bits of the key.

Now, decode the content of this file from Base64 to binary. In Linux-based systems and macOS, you can use the [`base64`](https://www.gnu.org/software/coreutils/manual/html_node/base64-invocation.html) builtin tool as shown in the following example:

```bash
cat wrapping-key.pem | base64 -d > wrapping-key.bin
```

Assuming that your Base64-encoded file is named `wrapping-key.pem`, the previous command generates the binary decoded version into the file named `wrapping-key.bin`.

On Windows systems, you can use the [`certutil`](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/certutil) tool as follows:

```powershell
certutil -decode wrapping-key.pem wrapping-key.bin
```

#### Generate your own key

Each [cloud provider has its own requirements](https://auth0.com/docs/secure/highly-regulated-identity/customer-managed-keys/customer-managed-keys-dashboard#cryptographic-material-requirements) for the key you should generate, so you should use the appropriate settings for the [CKM\_RSA\_AES\_KEY\_WRAP](https://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/cos01/pkcs11-curr-v2.40-cos01.html#_Toc408226894) algorithm parameters.

Assume you are using AWS as your Auth0 cloud provider in our example. You can generate your 32 bytes (256 bits) symmetric key as follows:

```bash
openssl rand -out customer-key-material-key.bin 32
```

You also need a 32 bytes-long ephemeral AES encryption key that is required for AES Key Wrap with padding step:

```bash
openssl rand -out ephemeral-aes-kek-kwp.bin 32
```

Now you have two new files:

- `customer-key-material-key.bin`, which contains your symmetric key that will be used instead of the Auth0 Environment Root Key. Let's call it the *customer key*.
- `ephemeral-aes-kek-kwp.bin`, which contains another symmetric key that will be used to wrap the *customer key*, as [required by AWS](https://auth0.com/docs/secure/highly-regulated-identity/customer-managed-keys/customer-managed-keys-dashboard#auth0-on-aws-cloud). Let's call it the *ephemeral key*.

#### Wrap your own key

Let's start by wrapping the *customer key* with the *ephemeral key*. Use the following command:

```bash
openssl enc -id-aes256-wrap-pad \
        -K "$(xxd -p < ephemeral-aes-kek-kwp.bin | tr -d '\n')" \
        -iv A65959A6 \
        -in customer-key-material-key.bin \
        -out customer-key-material-wrapped.bin
```

You will get the `customer-key-material-wrapped.bin` file.

Now, wrap the *ephemeral key* with the wrapping key you downloaded from Auth0 and preprocessed earlier:

```bash
openssl pkeyutl \
    -encrypt \
    -in ephemeral-aes-kek-kwp.bin \
    -out ephemeral-aes-kek-kwp-wrapped.bin \
    -inkey wrapping-key.bin \
    -keyform DER \
    -pubin \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha256 \
    -pkeyopt rsa_mgf1_md:sha256
```

The result of this command will be the `ephemeral-aes-kek-kwp-wrapped.bin` file.

As the final step, concat the two wrapped files you generated and encode the result with Base64:

```bash
cat ephemeral-aes-kek-kwp-wrapped.bin customer-key-material-wrapped.bin | base64 > encrypted-key-material-b64
```

The file `encrypted-key-material-b64` is the file you will upload to Auth0 to complete the BYOK process.

### Upload your newly created Root Key

Go back to your Auth0 dashboard and follow the steps again to open the modal to upload the key. This time, click the *Choose File* button and select the `encrypted-key-material-b64` file you created in the previous step:

![Upload customer key to complete BYOK](https://images.ctfassets.net/23aumh6u8s0i/5MSJvTULvP0zSYga5Nzjhq/22c95f9d6faa2e2a3a7ad27c457cc647/upload-customer-key-byok.png)

Click the *Save* button to complete the BYOK process.

Congratulations! Now Auth0 will be using your own encryption key as your Environment Root Key:

![Auth0 dashboard with BYOK enabled](https://images.ctfassets.net/23aumh6u8s0i/6cKLg7wB5TYxqGRL8WRfGr/3b4a64b4d61ce3cff640f46ccddbfd5a/auth0-dashboard-with-byok-enabled.png)

> Keep in mind that by importing your own encryption key, you implicitly deauthorize Auth0 from managing the lifecycle of the Environment Root Key. This means that now you are in charge of rotating the key periodically.

## Automate the Key Generation and Wrapping

As you can see, there are a few manual steps to generate and wrap the encryption key to upload to Auth0. Fortunately, you can blend it all into one script as the following (only for Bash):

```bash
#!/bin/bash

# Check if a .pem file is passed as an argument
if [ -z "$1" ]; then
    echo "Usage: $0 <path to pem file>"
    exit 1
fi

PEM_FILE="$1"

#Ensure the file exists
if [ ! -f "$PEM_FILE" ]; then
    echo "File not found: $PEM_FILE"
    exit 1
fi

#1. Remove the first line (BEGIN CERTIFICATE)
#1. Remove the last line (END CERTIFICATE)
#1. Remove  all line breaks
#4. Remove any trailing characters like whitespace

CERT_DATA=$(sed '1d;$d' "$PEM_FILE" | tr -d '\n\r' | tr -d ' ')


if [ -z "$CERT_DATA" ]; then
    echo "Cleaned certificate is empty"
    exit 1
fi


echo "Processed certificate data: $CERT_DATA"

PUBLIC_WRAPPING_KEY=public-wrapping-key.bin

printf "%s" "$CERT_DATA" | base64 -D  > $PUBLIC_WRAPPING_KEY

if [ ! -f "$PUBLIC_WRAPPING_KEY" ]; then
    echo "Public Wrapping key file does not exist"
    exit 1
fi

openssl_operations() {
    echo "Running OpenSSL..."

    openssl rand -out customer-key-material-key.bin 32
    openssl rand -out ephemeral-aes-kek-kwp.bin 32
    openssl enc -id-aes256-wrap-pad \
        -K "$(xxd -p < ephemeral-aes-kek-kwp.bin | tr -d '\n')" \
        -iv A65959A6 \
        -in customer-key-material-key.bin \
        -out customer-key-material-wrapped.bin

    openssl pkeyutl \
    -encrypt \
    -in ephemeral-aes-kek-kwp.bin \
    -out ephemeral-aes-kek-kwp-wrapped.bin \
    -inkey public-wrapping-key.bin \
    -keyform DER \
    -pubin \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha256 \
    -pkeyopt rsa_mgf1_md:sha256

    cat ephemeral-aes-kek-kwp-wrapped.bin customer-key-material-wrapped.bin | base64 > encrypted-key-material-b64 

    rm customer-key-material-key.bin ephemeral-aes-kek-kwp.bin customer-key-material-wrapped.bin ephemeral-aes-kek-kwp-wrapped.bin public-wrapping-key.bin

    # echo "$DECODED_CERT" | openssl ...
}

openssl_operations
```

This simplifies the generation and wrapping steps, making the process more straightforward, as you can see in the following video:

<AmpContent>
<amp-youtube
    data-videoid="InbHi6fRMKo"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>

<NonAmpContent>
<div
  className='embed-container'
  style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;">
    <iframe
      style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
      src='https://www.youtube.com/embed/InbHi6fRMKo'
      frameborder='0' allowfullscreen>
    </iframe>
</div>
</NonAmpContent>

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## Conclusion

This article showed you how Auth0 supports Bring Your Own Key, an approach that lets you control the provenance of the root key used to encrypt your secrets and data in the Auth0 environment.

You used OpenSSL as a testing tool to generate and wrap your own key and learned how to use the Auth0 dashboard to configure your environment with it.

A special thanks to Filip Palach and Lucas Gomes for their work on the OpenSSL process and the script.

If you want to learn more about BYOK in Auth0, leave a message below.


Bring Your Own Key (BYOK) in Auth0

Native login with passkeys allows you to integrate passkeys into your native applications and offers a smooth user experience with all the benefits of passkeys.

Native login with passkeys allows you to seamlessly integrate [passkeys](https://learnpasskeys.io/introduction) into your mobile applications. If you wanted to add passkeys before, you had to integrate a web redirect flow that uses Universal Login. 

Today, we are announcing Limited Early Access to Native Login with passkeys for Android applications. 

## How Does It Work? 

In order to use Native Login with passkeys in your Android application, there are a few requirements:

* **Enable and configure your passkey policy**: First of all, you need to enable passkeys for your tenant. Learn how to do it using [our documentation](https://auth0.com/docs/authenticate/database-connections/passkeys/configure-passkey-policy).
* **Configure a Custom Domain**: you can learn how to configure a custom domain using [our documentation](https://auth0.com/docs/customize/custom-domains).
* **Enable Android App Links Support**, which you can do following [our docs](https://auth0.com/docs/get-started/applications/enable-android-app-links-support).

Native login is available on the Android SDK from version 3.2.0 and Android API 28. 

### Sign Up 

To sign up, you’ll need to use the "`signupWithPasskey`" method from the "`AuthenticationAPIClient`". When successful, you can handle the passkey creation from your device using Android’s CredentialManager following [Android’s official docs](https://developer.android.com/identity/sign-in/credential-manager#create-passkey). Here’s an example implementation in Kotlin:

```java
val account = Auth0.getInstance("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}")

val client = AuthenticationAPIClient(account) 

client.signupWithPasskey(
            UserData(
                email = "jndoe@email.com"
            ), "{realm}"  
        ).start(object : Callback<PasskeyRegistrationChallenge, AuthenticationException> {
            override fun onSuccess(result: PasskeyRegistrationChallenge) {
                val passKeyRegistrationChallenge = result
                val request = CreatePublicKeyCredentialRequest(
                    Gson().toJson(
                        passKeyRegistrationChallenge.authParamsPublicKey
                    )
                )
                var response: CreatePublicKeyCredentialResponse?

        // start credential creation on the device 
                credentialManager.createCredentialAsync(requireContext(),
                    request,
                    CancellationSignal(),
                    Executors.newSingleThreadExecutor(),
                    object :
                        CredentialManagerCallback<CreateCredentialResponse, CreateCredentialException> {

                        override fun onError(e: CreateCredentialException) {
                        }

                        override fun onResult(result: CreateCredentialResponse) {

                            response = result as CreatePublicKeyCredentialResponse
                            val authRequest = Gson().fromJson(
                                response?.registrationResponseJson,
                                PublicKeyCredentials::class.java
                            )

       // once the device created the key pair and signed the challenge you can sign in to Auth0 
                            client.signinWithPasskey(
                                passKeyRegistrationChallenge.authSession,
                                authRequest,
                                "{realm}"
                            )
                                .validateClaims()
                                .start(object : Callback<Credentials, AuthenticationException> {
                                    override fun onSuccess(result: Credentials) {
                                        credentialsManager.saveCredentials(result)
                                        Snackbar.make(
                                            requireView(),
                                            "Hello ${result.user.name}",
                                            Snackbar.LENGTH_LONG
                                        ).show()
                                    }

                                    override fun onFailure(error: AuthenticationException) {
                                        Snackbar.make(
                                            requireView(),
                                            error.getDescription(),
                                            Snackbar.LENGTH_LONG
                                        ).show()
                                    }
                                })
                        }
                    })
            }

            override fun onFailure(error: AuthenticationException) {
                Snackbar.make(
                    requireView(),
                    error.getDescription(),
                    Snackbar.LENGTH_LONG
                ).show()
            }
        })
```

The `signupWithPasskey` method starts the passkey creation ceremony. It generates the challenge for the authenticator to sign once it has created the public key credential pair. In your case, your Android device acts as the authenticator and you create the key pair and sign the challenge when you use the `CreatePublicKeyCredentialRequest` method from Android’s Credential Manager. 

Then, you can use Android’s Credential Manager method `createCredential` or `createCredentialAsync` to start the creation. Once successful, you can use the result from the creation to send that data to Auth0 and sign in using the ``signinWithPasskey`` method, which is covered below.

### Login 

To sign in, you’ll have to first initiate the passkey challenge by using the `passkeyChallenge` method from the `AuthenticationAPIClient`. When the call is successful, you can initiate the credential retrieval using Android’s [`getCredential` method from the `CredentialManager`](https://developer.android.com/identity/sign-in/credential-manager#sign-in).

When your device retrieves the credential successfully, you can then initiate the sign-in process with Auth0. An example implementation could be:

```java
val account = Auth0.getInstance("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}")
val client = AuthenticationAPIClient(account)

client.passkeyChallenge(realm)
            .start(object : Callback<PasskeyChallenge, AuthenticationException> {
                override fun onSuccess(result: PasskeyChallenge) {
                    val passkeyChallengeResponse = result
                    val request =
                        GetPublicKeyCredentialOption(Gson().toJson(passkeyChallengeResponse.authParamsPublicKey))
                    val getCredRequest = GetCredentialRequest(
                        listOf(request)
                    )
                    credentialManager.getCredentialAsync(context,
                        getCredRequest,
                        CancellationSignal(),
                        executor,
                        object :
                            CredentialManagerCallback<GetCredentialResponse, GetCredentialException> {
                            override fun onError(e: GetCredentialException) {
                                Log.w(TAG, "Error fetching public key credential")
                                callback.onFailure(handleGetCredentialFailure(e))
                            }

                            override fun onResult(result: GetCredentialResponse) {
                                when (val credential = result.credential) {
                                    is PublicKeyCredential -> {
                                        val authRequest = Gson().fromJson(
                                            credential.authenticationResponseJson,
                                            PublicKeyCredentials::class.java
                                        )
                // initiate signin process with Auth0
                                        client.signinWithPasskey(
                                            passkeyChallengeResponse.authSession,
                                            authRequest,
                                            realm
                                        )
                                            .validateClaims()
                                            .addParameters(parameters)
                                            .start(callback)
                                    }

                                    else -> {
                                        Log.w(
                                            TAG,
                                            "Received unrecognized credential type ${credential.type}."
                                        )
                                        callback.onFailure(AuthenticationException("Received unrecognized credential type ${credential.type}"))
                                    }
                                }
                            }
                        })

                }
```

For more detailed examples, you can check out the [Android SDK sample folder on Github](https://github.com/auth0/Auth0.Android/tree/main/sample).

If you need [Java examples, you can check out this doc](https://github.com/auth0/Auth0.Android/blob/main/EXAMPLES.md#passkeys).

## What Use Cases Are Supported?

The initial early access release provides support for the following use cases:

* **Sign Up with a passkey**: users can register a new passkey for Auth0/your app and store it in the device credential manager for future use. 
* **Login with a passkey**: users can retrieve passkeys using the device’s credential manager and use them to log in. 

## How Can You Apply?

If you are interested in joining the early access program, please reach out to your account manager.

_Any products, features, or functionality referenced in this material that are not currently generally available may not be delivered on time or at all. Product roadmaps do not represent a commitment, obligation, or promise to deliver any product, feature, or functionality, and you should not rely on them to make your purchase decisions._

Native Login with Passkeys Is Now in Limited Early Access for Android Applications!

peterfernandez_360

As an Architect, Consultant, and Engineer, I have more than 30 years of experience designing and developing secure and robust software solutions. When not helping teams deal with the complexities of Customer Identity, you can usually find me working behind the scenes, acting in or directing a show at my local theatre.

Peter Fernandez

Why a Multi-Tenant approach is fundamental to B2B SaaS, and how using Auth0 and the Auth0 Organizations feature can help implement it.

Demystifying Multi-Tenancy in a B2B SaaS Application

Learn what Pushed Authorization Requests are and when to use them to strengthen the security of your OAuth 2.0 and OpenID Connect-based applications.

In highly sensitive contexts, such as in financial or healthcare sectors, the security bar must be raised to prevent any breach of information and artifacts that could give unauthorized access to user data. [Pushed Authorization Requests (PAR)](https://datatracker.ietf.org/doc/html/rfc9126) is one extension that enhances OAuth 2.0  and OpenID Connect so that they can be securely used in these scenarios. Let's explore how this OAuth 2.0 extension works.

## Why use PAR?

Let's start by first understanding why you may need PAR and what problem it tries to resolve.

### The OAuth authorization request

If you have some experience with OAuth 2.0 and OpenID Connect, you know that the initial step that a client application must take to get the tokens it needs is to send an authorization request to the authorization server. For this purpose, the user's browser is redirected to the authorization server with a URL similar to the following:

```bash
https://your-authorization-server.com/authorize?
    client_id=1234567890&
    redirect_uri=https://your-app/callback&
    scope=openid profile email phone address&
    response_type=code&
    audience=https://myapi&
    state=12c1d32c1aba2cc14f9b907a9ec90
```

This authorization request URL is pretty basic, but you can add other parameters based on the [OAuth flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow) you are using or on the specific extension/customization your authorization server implements. For example, if you are using the [Authorization Code Flow with PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce), you should also add the `code_challenge` and `code_challenge_method` parameters. In Auth0, you can also specify the `organization` or `invitation` parameters if you are using the [Auth0 Organizations](https://auth0.com/docs/manage-users/organizations) feature, and so on. The complexity of the authorization request can grow considerably depending on your specific use case.

### What's the problem with the authorization request?

As you can see, the authorization request is nothing but a GET HTTP request against a URL with its parameters:

```http
GET /authorize?
    client_id=1234567890&
    redirect_uri=https%3A%2F%2Fyour-app%2Fcallback&
    scope=openid%20profile%20email%20phone%20address&
    response_type=code&
    audience=https%3A%2F%2Fmyapi&
    state=12c1d32c1aba2cc14f9b907a9ec90 HTTP/1.1
Host: your-authorization-server.com
```

In this form, it may raise a few concerns:

- **The authorization request can be altered**. Usually, the client application redirects the user's browser to the authorization server with the authorization URL. Nothing prevents a malicious actor from changing one or more parameters of this request before sending it to the authorization server.
- **No guarantee of the request's provenance**. The authorization request is normally built by the client application, and the user's browser is in charge of sending it to the authorization server. However, there is no guarantee that the request has been built by the client application. Anyone can build an authorization request once they know a few data, such as the client ID and the redirect URI.
- **No guarantee of confidentiality**. Although the browser sends the authorization request via HTTPS, the request parameters can be intercepted by third-party applications, such as a proxy, a load balancer, or even a browser plugin. A malicious network component of this type can inject or change the request parameters, not to mention that the request itself can be logged.
- **Browser limitations**. Finally, a very complex query string in the authorization request may incur [possible browser limitations on URL length](https://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url-in-different-browsers).

This is where Pushed Authorization Requests come into play.

## How PAR Works

The basic idea of Pushed Authorization Requests is very simple: instead of redirecting the user's browser to make the authorization request with all the parameters, the client application *pushes* that request directly to the authorization server with a POST request and gets an identifier for that request. Now, the client application redirects the user's browser to the authorization server with just that identifier to make its authorization request, avoiding exposing all the details.

### The PAR endpoint

The first requirement for an authorization server supporting PAR is to expose the PAR endpoint. This is an additional endpoint that will accept authorization requests with the parameters in the payload. The following example shows how a request to the PAR endpoint looks like:

```http
POST /oauth/par HTTP/1.1
  Host: your-authorization-server.com
  Content-Type: application/x-www-form-urlencoded
  client_id=1234567890&
  client_secret=<YOUR_SECRET>&
  redirect_uri=https%3A%2F%2Fyour-app%2Fcallback&
  scope=openid%20profile%20email%20phone%20address&
  response_type=code&
  audience=https%3A%2F%2Fmyapi
```

Notice the reference to the `/oauth/par` path and how the parameters are passed through POST. You can see some differences between the parameters passed in the standard GET-based authorization request and this request. Apart from the usual parameters such as `client_id`, `redirect_uri`, `scope`, etc., you may notice that the `client_secret` is passed here. This is a request coming from a [confidential client](https://auth0.com/docs/get-started/applications/confidential-and-public-applications#confidential-applications), that is, a client capable of securely storing a secret, such as a server-running application. By passing `client_id` and `client_secret`, the request is authenticated by the authorization server resolving the confidentiality concerns we discussed earlier.

> The PAR specification does not limit access to the PAR endpoint to confidential clients only. It states that "*the rules for client authentication as defined in [[RFC6749](https://datatracker.ietf.org/doc/html/rfc6749)] for token endpoint requests, including the applicable authentication methods, apply for the PAR endpoint as well.*"
>
> This entails that even public clients can potentially access the PAR endpoint. However, their public nature does not allow them to safely determine their identity, so some of the concerns about the integrity and confidentiality of the request still remain in this case.

As a response to this request, the authorization server will respond with something like the following:

```http
HTTP/1.1 201 Created
Content-Type: application/json

{
  "request_uri": "urn:ietf:params:oauth:request_uri:6esc_11ACi5bwq064ltcg4eY28s",
  "expires_in": 30
}
```

The authorization server's response is a JSON object with two properties:

- `request_uri`. This is the identifier of the authorization request pushed by the client application.
- `expires_in`. This is the number of seconds that the authorization request is valid.

With these basic notions, let's take a look at how the whole authorization process works.

### The PAR authorization flow

The following diagram illustrates the OAuth authorization flow using PAR:

![Pushed Authorization Request flow](https://images.ctfassets.net/23aumh6u8s0i/6FWUrUsNmimPr10XuqI26k/984cf829065bab1dacd1a6dafc08e92c/pushed-authorization-requests-flow.png)

Here are the steps highlighted in the diagram:

1. The client application sends an authorization request to the PAR endpoint of the authorization server.

2. The authorization server authenticates the application client, validates the request, and stores it. Then, it replies with a response containing the authorization request's identifier (`request_uri`) and the validity time (`expires_in`).

3. The client application uses the `request_uri` to build the authorization request URL for the user's browser and redirects it to the authorization server. The authorization request URL will look like the following:

   ```bash
   https://your-authorization-server.com/authorize?
       client_id=1234567890&
       request_uri=urn%3Aietf%3Aparams%3Aoauth...4ltcg4eY28s
   ```

4. The user's browser sends a GET request to the authorization server using the authorization request URL received by the client application. The authorization server retrieves the authorization request identified by the `request_uri` value, and from now on, the usual steps of the requested OAuth flow are carried out.

As you can see, the browser's request no longer contains the details of the authorization request. There is no risk of tracking or in-transit manipulation of the request. Also, the complexity of the URL is considerably reduced.

## PAR Metadata

OAuth and OpenID Connect servers publish the configuration metadata in the `/.well-known` URI to publicly declare the supported capability and other protocol details. PAR specification adds two new keys to this metadata:

- `pushed_authorization_request_endpoint`. This key defines the PAR endpoint where the client application can push the authorization request and get the corresponding  `request_uri`.
- `require_pushed_authorization_requests`. This key has a boolean value indicating whether using PAR is mandatory (`true`) or optional (`false`). If this key is not present, the default value is `false`.

With this metadata, your application can check if an authorization server supports PAR using the usual [discovery approach](https://auth0.com/docs/get-started/applications/configure-applications-with-oidc-discovery).

## PAR and Auth0

Auth0 supports PAR as part of the [Highly Regulated Identity](https://auth0.com/docs/secure/highly-regulated-identity) add-on of the Enterprise plan. Highly Regulated Identity is Auth0's implementation of FAPI 1, the set of standards that raises the security level to protect application operations in sensitive contexts, such as finance, healthcare, e-commerce, etc.

By default, PAR is not active in an Auth0 tenant. You have to enable it at the tenant level to make the PAR endpoint available to your applications. You can do it through your Auth0 dashboard. Follow [the steps described here to enable PAR](https://auth0.com/docs/get-started/applications/configure-par#set-par-for-a-tenant) in your Auth0 tenant.

Once you enable PAR at the tenant level, your applications can use the classic authorization endpoint or the PAR endpoint. If you want to make the endpoint mandatory for a specific application, you should require it at the Auth0 application configuration level. You can use the Auth0 dashboard or the Auth0 Management API to set PAR endpoint mandatory. Follow [these instructions](https://auth0.com/docs/get-started/applications/configure-par#set-par-for-an-application) to enable mandatory PAR for your application.

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## Conclusion

Pushed Authorization Requests (PAR) are a great addition to strengthen the security of OAuth 2.0 and OpenID Connect protocols. As you have learned, it enables client applications to make authorization requests without exposing the details of the call to potential tracking and manipulation.

This security improvement is critical in scenarios where data confidentiality must be preserved, and Auth0 offers PAR support through Highly Regulated Identity (HRI). Combined with other strong security enhancements supported by HRI, you can build applications with high-security standards and comply with the most common regulations. Check out this document to learn more about [Highly Regulated Identity](https://auth0.com/docs/secure/highly-regulated-identity).



What Are OAuth Pushed Authorization Requests (PAR)?

paulo-nascimento

Paulo Nascimento is a Machine Learning Engineer at Okta, spearheading AI development for the Customer Identity Cloud (CIC). He brings expertise from AI startups to create innovative solutions powering the CIC organization. Paulo's work focuses on integrating AI technologies to strengthen enterprise security, enhance user experience, and drive intelligent automation across Okta's identity platform.

Machine Learning Engineer

Paulo Nascimento

Waleed Manzoul

Staff Product Designer

Automate user lifecycle, enhance security and boost IT efficiency across your enterprise

## Introduction

Consider a Fortune 500 company, like a bank with 40,000 employees. A financial analyst at this company will use many SaaS tools to do their job, like Slack, Google Suite for Work, Zoom, Tableau, Workday, and more. In fact, enterprise organizations rely on [an average of 211 apps each](https://www.okta.com/businesses-at-work/) to run their businesses.

So, the bank’s central IT team might be responsible for managing 200+ SaaS apps, and our financial analyst may need access to a quarter of them. Naturally, for an employee to use all of those apps, accounts for each one would need to be provisioned first.

Fortunately, our bank’s IT team is smart. They utilize [Okta Workforce Identity Cloud](https://www.okta.com/workforce-identity/) to maintain [a directory of all their employees](https://www.okta.com/products/universal-directory/) and enable easy account creation and access to those SaaS apps using [Single Sign-On](https://auth0.com/docs/authenticate/single-sign-on). That means they don’t have to manually provision SaaS apps every time a new employee joins the company or an existing employee needs access.

But what about other events in an employee’s time with the company, such as when they change their role, change their name or pronouns, or eventually leave the company? How many times might those events happen over 40,000 employees? And how might each of those changes be reflected in the SaaS apps that they use?

## User Lifecycle Management Using SCIM

Fortunately, if a SaaS app used at the company relies on a workforce provisioning engine that utilizes SCIM ([System for Cross Identity Management](https://scim.cloud/), a standard for automating the exchange of user identity information between identity domains), that app can synchronize its user list to the central employee directory and react to changes that happen in the directory.

For the bank’s central IT team, this means they can make updates to users once in their central employee directory and have those changes reflected in all of the SaaS apps an employee uses, **reducing administrative overhead and toil**.

The power of this “live” connection that SCIM provides becomes critical when an employee leaves the company. Once central IT deletes this employee from their central directory, any user accounts they had with those SCIM-powered SaaS apps will be deactivated within seconds, **eliminating the chance of unauthorized access** through “[zombie accounts](https://www.wsj.com/tech/cybersecurity/unused-online-accounts-data-safety-38fa675e)” and **maintaining compliance with data privacy regulations**, like [GDPR](https://gdpr-info.eu/art-5-gdpr/).

Timely deprovisioning of former employees can have **cost savings** as well. When an employee leaves, the central IT team can quickly release the employee’s SaaS licenses and accurately reflect the reduced spend to the respective vendors.

So, you can imagine that the bank’s central IT team would want any new SaaS app it evaluates to leverage SCIM due to its many benefits:

* Saves a lot of manual labor
* Improves their security posture
* Saves their company money

## How Does SCIM Provisioning Work?

SCIM works by providing a defined schema of identity data that represents users and groups, along with a REST API that supports JSON and XML for CRUD operations on those user and group resources. 

Behind the scenes, SCIM is broken down into a few core components:

* SCIM Service Provider
    * This service hosts the identity data and responds to SCIM API requests. It’s also commonly called a SCIM server.
    * _Examples: Cloud applications, identity providers (e.g., Okta)_
* SCIM Client
    * The SCIM Client **initiates SCIM requests to interact with a SCIM server to perform operations that manage identities.**
    * _Examples: Identity management systems, HR systems_
* SCIM Schema
    * The SCIM schema defines the structure of identity data.
    * Core schemas: User, Group, EnterpriseUser (defined in [RFC7643](https://datatracker.ietf.org/doc/html/rfc7643))

The SCIM core components then use an HTTP-based REST API that supports JSON and XML data formats, although JSON is more common. The REST API uses standard HTTP methods like GET, POST, PUT, PATCH, and DELETE to support CRUD operations.

SCIM supports a number of key operations, such as:

* User Provisioning
    * The ”SCIM Client” sends a POST request to create a new user, and the ”SCIM Provider” creates the user and returns a unique identifier (ID).
* User Retrieval
    * The ”SCIM Client” sends a GET request with the user ID or search criteria, and the ”SCIM Provider” returns user data that matches the request, provided the user exists.
* User Update
    * The ”SCIM Client” sends a PUT or PATCH request with the updated user data, and the ”SCIM Provider” applies changes and confirms the update.
* User Deprovisioning
    * The ”SCIM Client” sends a DELETE request, and the ”SCIM Provider” removes or deactivates the user account.

On top of this core functionality, SCIM also provides useful features such as: 

* Bulk Operations
    * Where batch processing can be applied for multiple SCIM operations in a single request
* Filtering and Searching
    * Allows complex queries to find specific users or groups by using a standardized filter syntax

For each request, the SCIM REST API will return with the appropriate HTTP status to indicate success or failure along with detailed error messages for troubleshooting. SCIM typically uses OAuth 2.0 for authorization and supports HTTPS for secure data transmission.

SCIM is also extensible, which means that organizations can extend the standard SCIM schemas to accommodate their specific needs. For example, if an organization wants to include additional information about employees not covered by the standard SCIM schemas, then they can store additional information such as ”department” or ”manager” in their user profiles.

## SCIM vs SAML

Security Assertion Markup Language (SAML) is an XML-based framework for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). It’s most commonly used to enable Single Sign-On (SSO) across different web applications and services.

SCIM and SAML are both protocols for identity and access management (IAM). However, they serve different purposes. 

SCIM is used for user provisioning and management across different systems and applications, ensuring that identity data is consistent across. SAML, on the other hand, is used to access multiple applications with a single set of credentials.

> In summary, SCIM is for user management, while SAML is for user authentication.

## SCIM vs. SSO

Single Sign-On (SSO) is an authentication method that allows users to sign in to multiple applications with a single set of credentials.

Although SCIM and SSO are related, SCIM is a protocol used for provisioning appropriate roles and groups to users, whereas SSO authenticates those users into multiple accounts with a single set of login credentials.

## Inbound SCIM with Auth0

If you’ve been reading about SCIM online, you’ve probably found identity providers like Okta Workforce Identity Cloud and Microsoft Entra ID support SCIM in different ways, and that building for each of them can become a substantive effort. We’d advise that you learn about the identity providers your customers use and tailor your SCIM solution to meet the majority of your customers. However, If you think you will need to integrate your development with more than one identity provider, don't despair: there are solutions that allow you to easily connect to multiple identity providers at once. 

In fact, that's one of the things we do at Auth0. Our [Inbound SCIM solution](https://auth0.com/docs/authenticate/protocols/scim) allows you to integrate with Okta Workforce Identity Cloud, Microsoft Entra ID, and other identity providers via both SAML and OpenID Connect, manage attribute mappings on a per connection basis, and more. 

## Conclusion

SCIM is a powerful way to automate user lifecycles and maintain user accounts across platforms that can save companies time, money, and increase their security. Learn more about SCIM by exploring the [Auth0 docs](https://auth0.com/docs/authenticate/protocols/scim). 


Streamline Account Provisioning and Management with SCIM

Deploy a cloud-native Java Spring Boot microservice stack secured with Auth0 on Google GKE using Terraform and Kubernetes.

Deploy Secure Spring Boot Microservices on Google GKE Using Terraform and Kubernetes

cailyn edwards_24-05-16_OktaASM_3465

Senior Security Engineer

Cailyn Edwards

Everything you need to know about IdPs, from how they work to the benefits of using one.

**TL;DR**: IdPs are services that manage entities' digital identities. They help service providers verify the identity of their users and enable SSO to minimize user password fatigue.

## What Is an IdP?

An Identity Provider (IdP) is a service that stores and manages digital identities. These identities can belong to human or software entities. You can imagine an identity provider like a social register from Regency-era England containing information about specific individuals, including names, titles, and familial connections. This information could be used to dictate who should be invited to which events in high society or even to verify that someone is who they say they are. Modern IdPs probably won’t help you get invited to any major society events, but they do ensure that access to digital services is limited to the intended audience.

### What Do We Mean by Identity?
[**Digital identity**](https://auth0.com/docs/get-started/identity-fundamentals/identity-and-access-management) is the mapping of information about an individual to that person or entity. An identity will consist of user information like a username, address, email, etc. A subset of this information is unique and can be used to validate the identity of the entity it’s mapped to. This subset is what makes up a user's identity factors, which can be things like credentials, biometrics, security questions, or device information. These identity factors fit into three categories: knowledge, possession, and inheritance — in other words, something you know, something you have, and something you are.

## Why Are IdPs Important?

IdPs are crucial in the modern world because they allow entities to access resources securely while ensuring that only the users who are supposed to access them are able to access them. While service providers (SPs) can — and often do — manage identities, they have to balance that specialized service with their standard offerings. IdPs have the advantage of focusing primarily on managing and securely storing identities; thus, they are better suited to work with things like [Single Sign-on (SSO)](https://auth0.com/docs/authenticate/single-sign-on) and [Multi-factor Authentication (MFA)](https://auth0.com/docs/secure/multi-factor-authentication).

## How Do IdPs Work?

IdPs work by allowing users to log in to a variety of service providers using the authentication factors available to them. IdPs often support using existing credentials, like your Google login or a set of credentials set directly with the IdP.

A typical interaction with an IdP might look like this:

1. User requests to log in to the SP
2. SP redirects the user to the IdP for login
3. User enters credentials (or uses other authentication mechanisms)
4. IdP validates the user and reports back to the SP
5. The user is granted or denied access to the SP’s platform

IdPs also allow SPs to have a high level of control over how they manage access. They can have varied policies depending on the resources being accessed and by whom. These policies and rules are managed by admins, and can be changed and improved upon over time.

## What Are the Different Types of IdPs?

You can have different types of identity providers.

**Social** - Social IdPs are an easy way to validate users with minimal friction, saving the user from creating another password and username combination. An example of a social identity provider is Facebook. Web applications can use Auth0 to leverage a social IdP, allowing users to log in using their Facebook credentials.

**Enterprise** - Enterprise IdPs are often used for SSO. They allow employees to have a single set of credentials to access the variety of services needed to do their job. [Okta](https://www.okta.com/) is an example of an enterprise IdP, allowing employees to sign into any applications they are authorized to use through a convenient dashboard.

**Legal** - Legal IdPs are IdPs managed by governments. This is most common in Europe, but is becoming more prevalent elsewhere as well. An example of a legal IdP is [Criipto](https://www.criipto.com/electronic-identities), which offers eIDs for Denmark, Norway, Sweden, and other European countries.

## What Are the Benefits of IdPs?

Because IdPs are specialized in managing identity, they typically offer higher security and easier integration with multiple SPs.

There are many additional benefits to using an IdP, including:

* **Easier Credential Management**: When users have options like SSO, signing in with social or biometric/device-based authentication means one less set of credentials to manage. This leads to less reuse of easy to remember (and easy to guess) passwords — and a secure, seamless experience.
* **Automated User Onboarding and Offboarding**: With identity managed in one place, it’s easier to grant and revoke permissions at once based on things like group membership.
* **Allows SP to Focus on Core Offerings**: Dedicated identity management empowers service providers to concentrate on their primary business functions. By partnering with expert IdPs, SPs ensure secure identity management while devoting their resources to what matters most to their customers.
* **Better Identity Security**: IdPs have significant field experience, are dedicated to identity management, setting industry standards, and focus on protecting user data.
* **Increased Telemetry**: Identity management is the core product of IdPs, and they treat it as such. An IdP tracks who accessed what and when — which is useful for compliance, audits, and incident response.
* **Multiple Ways to Authenticate**: Users and SPs can choose the authentication options that work best for them, meaning less friction on sign-up and login.
* **Service Agnostic:** If you manage multiple service providers, or a user has worked for multiple tech companies, you will likely have run into the same IdPs. This makes onboarding and management easier — and allows you to leverage your existing knowledge. 

## FAQs

**What’s the difference between an IdP and a Single Sign-On (SSO) provider?**

While an IdP stores and manages digital identities, SSO is an authentication mechanism that allows a single user identity to access multiple service providers. SSO will still use an IdP to verify the user’s identity, and link it to a collection of applications a user can access. Think of an employee dashboard that allows the employee to use their corporate login to access their HR tools, travel planning, email, and so on.

**How do IdPs work with MFAs?**

Service providers can define policies for specific resources and user groups. Many IdPs support specifying the requirement for MFA, what MFAs are supported, and the lifespan of the MFA confirmation in these security policies. Most IdPs have their own MFA options, for example [Okta Verify](https://help.okta.com/en-us/content/topics/mobile/okta-verify-overview.htm).

**Can I move users from my custom-built solution to an IdP?**

Most IdPs will allow the import of users from external applications, allowing you to up your security and reduce your workload in just a few clicks. In the case of Auth0, we can support [automatic migrations](https://auth0.com/docs/manage-users/user-migration), so you can make the switch with little to no impact on your users.

## Conclusion

IdPs are a purpose-built solution that helps both SPs and users access resources securely. They allow SPs to manage granular access policies and reduce the mental load of credential management. IdPs are feature-rich identity and access management solutions, and they’re becoming even more crucial in the ever-evolving technical landscape. If you’re interested in learning about the future of IAM, you can [read about the identity challenges facing AI-powered applications](https://auth0.com/blog/identity-challenges-for-ai-powered-apps/).


What is an IdP (aka Identity Provider)?

Join us this October as we celebrate Hacktoberfest 2024 by encouraging developers to contribute to the open-source community.

We are excited to announce our inaugural [Authtoberfest 2024](https://authtoberfest.io/)!

![Authtoberfest 2024](https://images.ctfassets.net/23aumh6u8s0i/XGONROR1fr5aabZYKtkDC/3ef4d233bfbb1e79dcb1fcf755af2bb6/authtoberfest-logo.jpg)

Are you ready for Hacktoberfest? We are excited to participate in [Hacktoberfest 2024](https://hacktoberfest.com/), and we are calling all developers to join us in contributing to the open-source community.

Whether you're new to open source or an experienced contributor, this is your chance to give back, make a difference, and win some cool swag in the process.

At Auth0 by Okta, we believe in the power of community-driven development and open source. That’s why we’re proud to support and celebrate Hacktoberfest and help developers of all levels get involved. Let's code, collaborate, and contribute together!

![Authtoberfest 2024 T-shirt](https://images.ctfassets.net/23aumh6u8s0i/1PWpoxpdJtgsFDs9vx8jJL/118ee5e900b1653da2566238f8b2f60e/t-shirt-image.jpg)

This year, you have the chance to win a cool limited-edition T-shirt from us when you participate in Hacktoberfest and contribute to any of the projects in the Identity and Security space shortlisted by us. The first 100 valid submissions will get the T-shirt.

> A GitHub user with two accepted/merged PRs sending us the confirmation emails and the Hacktoberfest badge will be considered a valid submission.

Visit the [Authtoberfest website](https://authtoberfest.io/) to learn more about the event and how you can participate.

Authtoberfest 2024 is Here!

Nesh Popovic

As a Developer and Solutions Engineer for the past 20+ years, I've been involved in developing and selling secure and robust software solutions. When not helping my sales team deal with the complexities of software platforms, you can usually find me playing pickleball, basketball or backgammon.

Principal Solutions Engineer - CIAM

Learn how to set up an Amazon API Gateway and secure the REST API with Okta Customer Identity Cloud (CIC) Adaptive MFA Risk Score

Protecting REST APIs Behind Amazon API Gateway Using Okta

sam-yapkowitz

I began my career in enterprise software development and got exposure to lots of different frameworks and methodologies. I quickly realized my passion was in the architecture and design of solutions to unique problems. I now get to use these skills to help my customers build high-quality experiences using Okta. When not at work you can find me on the golf course, playing Rocket League or watching football with my friends.

Specialist Solutions Engineer

Sam Yapkowitz

Learn how to leverage Auth0 Forms to implement an invitation code workflow and improve the onboarding of your SaaS users.

Some applications require a user to be verified by an external service before they can log in to the system. This can be in the form of an invite code for a free trial in a SaaS application, address verification for a real estate listing website, or maybe something more robust for a healthcare or financial services application. 

Auth0 recently released [**Custom Prompts**](https://auth0.com/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts) to help app builders collect more information about their users upon signup. These fields can be captured, and further processing can be done with the [**Pre Registration Action Flow**](https://auth0.com/docs/customize/actions/flows-and-triggers/pre-user-registration-flow). Capturing too much information (or capturing information conditionally) can have impacts on the end-user experience. Auth0 has recently released [**Forms**](https://auth0.com/docs/customize/forms), a new drag-and-drop editor for collecting user information, executing workflows, and orchestrating event data, which can be applied to these verification workflows as well. For this article, we will address the invite code workflow where users must verify their invitation code before being able to log in to the application. 

> Note: Custom Prompts and Forms work very nicely together as a user who completes a sign-up will then trigger a Login Flow where Forms can be launched.

In this blog post, we will leverage Auth0 Forms to collect this invite code and make an HTTP request to an externally hosted API to verify that the code + email combo is valid. This is one narrow use case, but the solution we are going to outline can handle any scenario where a user must provide input to be verified externally before granting access.

## Use Case

Let’s imagine you have a SaaS application that has an upcoming private Beta launch. You do not want to restrict users from signing up to your platform (so you can ingest them into your MarTech stack), but you do not want to allow them to officially log in to the platform unless they have been given access by a member of your team or an affiliate. You could solve this use case in many ways, and in this instance, we will solve this by having users provide an “Invite Code” to verify they have been given access by your backend application. You would send the user’s email alongside this code before approving their access to your private launch. You could collect this code during the signup phase using Auth0 Custom Prompts, but if they failed the validation, their account would not be created. Your goal is to create the accounts and then only gate access to the private beta behind this invite code.

## Prompting a User with a Form

We will use a [Post-Login Action](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow) to launch a user into this flow. They will automatically enter this flow after sign up and any time they come back to your application. This Action will check a flag on the user's profile to see if they have been previously verified or not.

```
exports.onExecutePostLogin = async (event, api) => {
  if (event.user.app_metadata.verified !== true) {
     const FORM_ID = 'ap_eJWCKKPimBy86AyTRsQikQ';
     api.prompt.render(FORM_ID);
  }
};
```

You can access the Forms in your Auth0 tenant by navigating to **Actions** → **Forms**, which will launch the editor in a new tab. Here is the visual editor for our specific Flow:

![High-Level Form Flow](https://images.ctfassets.net/23aumh6u8s0i/QXEH3o2wOejR8tqxbrbmv/336b75aecffe19167cae13a8e00e13a5/Uploaded_from_External_User_Verification_with_Forms)

<center> _High Level Form Flow_ </center> <br>


The User is prompted to enter their invite code into a text prompt, and then a flow is invoked. In the image below, you can see the flow diagram that checks if the code result has an error, and if so, we will show an error message; otherwise, the flow continues.

![Verification Flow](https://images.ctfassets.net/23aumh6u8s0i/3GAfnyuteWbHtDHNwROVCg/70627654f98b7ff16b88540c5412d75b/Uploaded_from_External_User_Verification_with_Forms)
<center> _Verification Flow_ </center> <br>

Here, we can see how to configure the HTTP request step to call your endpoint using the user’s email address and the collected invite code.

![HTTP Request Structure](https://images.ctfassets.net/23aumh6u8s0i/oh5XRmbnILUdjN9WLnKML/3407054954d3b100612f18529cea8110/Uploaded_from_External_User_Verification_with_Forms)
<center> _HTTP Request Structure_ </center> <br>

Based on the response, if the result comes back as true, the user will continue the flow, and if not they will be shown an error message which will prevent them from continuing until they input a correct value.

![Conditional Configuration](https://images.ctfassets.net/23aumh6u8s0i/3kzqJOpa2YLCkit2V3gG46/bd4fa60f27b24816454484671952ab49/Uploaded_from_External_User_Verification_with_Forms)
<center> _Conditional Configuration_ </center> <br>

Once the user enters a correct value, the flow exits and returns to the main path, where it will let them know that access has been granted and they can continue using the application. Our Action that launched the flow must have a continue section to resume the authentication transaction, and we will also save a flag on their profile to prevent them from having to enter this flow again.

```
exports.onContinuePostLogin = async (event, api) => {
  api.user.setAppMetadata("verified", true);
};

```

![Success Prompt](https://images.ctfassets.net/23aumh6u8s0i/2YeCQcl1qBzU6IJQhgR2qr/51850095d1c6dda7f814fecc33ebd109/Uploaded_from_External_User_Verification_with_Forms)
<center> _Success Prompt_ </center> <br>

And here is the flow end-to-end for a new user who signs up and has a valid email + code combo.

<AmpContent>
<amp-youtube
    data-videoid="duROpUKZR04"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>
<NonAmpContent>
<div class='embed-container' style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;"><iframe style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;" src='https://www.youtube.com/embed/duROpUKZR04' frameborder='0' allowfullscreen></iframe></div>
</NonAmpContent>
<center> _End to End User Journey_ </center> <br> 

Here is the finished JSON for you to begin building your verification flow today! You can import this directly into your tenant by navigating to the Forms window → Create Form → Import It!

![Importing Existing Flow with JSON](https://images.ctfassets.net/23aumh6u8s0i/3vjVyJ42fDEDF3DC02nRKo/df261abe1b14ee4e6ac30852f80434ef/Uploaded_from_External_User_Verification_with_Forms)
<center> _Importing Existing Flow with JSON_ </center> <br>

```js
{
  "version": "3.0.0",
  "form": {
    "name": "Invite Code",
    "description": null,
    "messages": {
      "custom": {},
      "errors": {}
    },
    "languages": {
      "default": null,
      "primary": "en"
    },
    "translations": {},
    "start": {
      "nextNode": "step_Y3AO",
      "coordinates": {
        "x": 22,
        "y": 167
      },
      "hiddenFields": []
    },
    "nodes": [
      {
        "id": "step_Y3AO",
        "type": "STEP",
        "alias": "Collect Code",
        "config": {
          "nextNode": "flow_Cilk",
          "components": [
            {
              "id": "rich_text_sME2",
              "type": "RICH_TEXT",
              "config": {
                "content": "<h3><strong>Please enter your invite code.</strong></h3>"
              },
              "category": "BLOCK"
            },
            {
              "id": "invite_code",
              "hint": null,
              "type": "TEXT",
              "label": "Invite Code",
              "config": {
                "maxLength": null,
                "minLength": null,
                "multiline": false,
                "placeholder": "XXX-XXX",
                "defaultValue": null
              },
              "category": "FIELD",
              "required": true,
              "transient": false
            },
            {
              "id": "next_button_xlCe",
              "type": "NEXT_BUTTON",
              "config": {
                "text": "Continue"
              },
              "category": "BLOCK"
            }
          ]
        },
        "coordinates": {
          "x": 323,
          "y": -36
        }
      },
      {
        "id": "flow_Cilk",
        "type": "FLOW",
        "alias": "Verify Code",
        "config": {
          "flowId": "#FLOW-1#",
          "nextNode": "step_IifF"
        },
        "coordinates": {
          "x": 1051,
          "y": 139
        }
      },
      {
        "id": "step_IifF",
        "type": "STEP",
        "alias": "Verification Complete",
        "config": {
          "nextNode": "$ending",
          "components": [
            {
              "id": "rich_text_pMye",
              "type": "RICH_TEXT",
              "config": {
                "content": "<h3><strong>Welcome to Demo0, </strong></h3><h3><strong>Click Continue to get Started!</strong></h3>"
              },
              "category": "BLOCK"
            },
            {
              "id": "next_button_Z6Md",
              "type": "NEXT_BUTTON",
              "config": {
                "text": "Continue"
              },
              "category": "BLOCK"
            }
          ]
        },
        "coordinates": {
          "x": 1510,
          "y": -2
        }
      }
    ],
    "ending": {
      "content": null,
      "redirection": null,
      "callback": null,
      "afterSubmit": {
        "email": null,
        "flowId": null
      },
      "coordinates": {
        "x": 2194,
        "y": 110
      },
      "resumeFlow": true
    },
    "social": [],
    "style": {
      "css": null,
      "theme": "ROUND",
      "version": "MODERN"
    },
    "tags": []
  },
  "flows": {
    "#FLOW-1#": {
      "name": "Verify Invite Code",
      "description": null,
      "actions": [
        {
          "id": "http_request_verify_code",
          "type": "HTTP",
          "alias": "Verify Invite Code",
          "notes": null,
          "action": "SEND_REQUEST",
          "params": {
            "url": "https://edge.samyap.dev/api/verify-code",
            "body": {
              "email": "{{context.user.email}}",
              "invite_code": "{{fields.invite_code}}"
            },
            "type": "JSON",
            "basic": null,
            "method": "POST",
            "params": {},
            "headers": {},
            "acceptNOK": false,
            "connectionId": null
          },
          "allowFailure": false
        },
        {
          "id": "if_then_condition_q0Ym",
          "type": "FLOW",
          "alias": "Verify Code Result",
          "notes": null,
          "action": "BOOLEAN_CONDITION",
          "params": {
            "then": [],
            "evaluate": {
              "operands": [
                {
                  "operands": [
                    "{{ http_request_verify_code.body.result }}",
                    "true"
                  ],
                  "operator": "EQ"
                }
              ],
              "operator": "AND"
            },
            "otherwise": [
              {
                "id": "show_error_message_4rkM",
                "type": "FLOW",
                "alias": null,
                "notes": null,
                "action": "ERROR_MESSAGE",
                "params": {
                  "message": "Your code is invalid.  Please contact support for help"
                },
                "allowFailure": false
              }
            ]
          },
          "allowFailure": false
        }
      ],
      "triggers": {
        "webhook": {
          "secret": null,
          "enabled": false
        }
      },
      "synchronous": true,
      "security": {
        "rateLimits": []
      }
    }
  },
  "connections": {}
}

```

## Conclusion

Today you learned how to leverage Auth0 Forms to gather input from users to verify them with external systems using the no-code Forms and Flows editors. This capability can be extended to numerous applications such as Progressive Profiling, Consent Collection and many more.

At Auth0, we aim to provide a high-quality service and developer experience for our customers. The first interaction with your customers is oftentimes a login screen, so we understand how important it is for the user experience to be top-notch. With our hosted Universal Login, we take away the burden of deploying and maintaining these highly secure workflows. With the capabilities of our forms outlined in this post, we are able to help your teams iterate more quickly and customize the experience to be sticky for your brand and ultimately help your business grow.

External User Verification with Forms

Deploy a cloud-native Java Spring Boot microservice stack secured with Auth0 on Azure AKS using Terraform and Kubernetes.

Deploy Secure Spring Boot Microservices on Azure AKS Using Terraform and Kubernetes

Learn how to authenticate users of your .NET MAUI Blazor application using Auth0.

Add Auth0 Authentication to Blazor Hybrid Apps in .NET MAUI

A guide to building B2B SaaS applications using Auth0 and the Auth0 Organizations feature.

A B2B SaaS Application Primer Using Auth0

joey devilla headshot 900px

I’m a Senior Developer Advocate at Auth0, and I like to work on various technologies. I’ve developed software for all sorts of platforms, from CD-ROM and the PalmPilot to my current area of focus, mobile phones, IoT devices, and AI. When I’m not looking for strange new platforms to write software for, I’m playing a strange old instrument — the accordion!

Joey deVilla

Learn how to add authentication (login and logout) to iOS apps built with SwiftUI with Auth0 and the Auth0.Swift package.

Get Started with iOS Authentication using SwiftUI, Part 1: Login and Logout

Add personalization to your iOS/SwiftUI app with user info from the ID token, a JWT (JSON Web Token) that you’ll read with the Swift JWTDecode library.

In Part 1 of this tutorial, you created a SwiftUI-based iOS app that uses Auth0 for basic login and logout functionality. In this part, you’ll enhance your app by giving it the ability to read the user’s profile to display their photo, name, and email address when they’re logged in.

<include 
    src="LinkCard" 
    title="Calling a Protected API from an iOS Swift App" 
    link="https://auth0.com/blog/calling-protected-apis-from-ios-swift/" 
    description="Looking for a step-by-step guide to leveraging OAuth 2.0 when accessing protected APIs via an iOS app built with Swift? If you're integrating with Auth0, then this is everything you need to know!"     img="https://images.ctfassets.net/23aumh6u8s0i/5PC3nu1F68m8S3BmJFv9SN/e83487c6d89d72fb6a49155722959b1d/ios_hero_2021_2.jpeg"
/>

Once again, you can follow the text in this article, or if you prefer learning by video, you can follow the steps in this article’s companion video:

<iframe width="600" height="338" src="https://www.youtube.com/embed/xOBoLegDmTw" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

> Look for the 🛠 emoji if you’d like to skim through the content while focusing on the build and execution steps.
> 
> The 📺 emoji highlights links to specific points in the video.


## Examine the ID Token

📺 [The _Examine the ID Token_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2008s)
 
If you look at the `.success` case of the `switch` statement in `ContentView`’s `login()` method, you’ll see these `print()` functions:

```swift
print("Credentials: \(credentials)")
print("ID token: \(credentials.idToken)")
```

These functions’ output will appear in Xcode’s Debug area:

![Xcode screenshot highlighting the Debug area.](https://images.ctfassets.net/23aumh6u8s0i/2Odv2P2CeeMGBoKSHNl3ly/2ba5ae37dbc5afafb94e82f95f41a722/debug_area.png)

> If the Debug area isn’t visible, open the _View_ menu and select _Debug Area_ → _Show Debug Area_ or use the keyboard shortcut _command-Shift-Y_.

You’ll see the contents of the `credentials` object and its `idToken` property, which should look similar to this:

```
Credentials: Credentials(accessToken: "<REDACTED>", tokenType: "Bearer", idToken: "<REDACTED>", refreshToken: nil, expiresIn: 2022-03-20 04:38:25 +0000, scope: Optional("openid profile email"), recoveryCode: nil)
ID token: eyJhbGciOiJSUzI1NiIsInR5cC...
```

The `credentials` object is a package of information that Auth0 sends to your app after authenticating a user. This information includes:

- **ID token:** Data that proves that the user has been authenticated.
- **Access token:** Data that gives a client application permission to access a specific resource to perform specific actions on the user’s behalf.
- **Refresh token:** Applications use this to get additional access tokens when the original access token expires without requiring the user to re-authenticate.
- **Scopes:** A set of [OpenID Connect (OIDC) scopes](https://auth0.com/docs/get-started/apis/scopes/openid-connect-scopes) — authorizations for access to details about the user — that Auth0 has granted to the app. Unless you specify otherwise, *Auth0.swift* defaults to requesting the following scopes when logging in a user:
	- `openid`: Authorization to use OIDC to verify the user's identity
	- `profile`: Authorization to access the user’s name information
	- `email`:  Authorization to access the user’s email address

> Want to know more about ID tokens and access tokens? We explain all in our article, [_ID Token and Access Token: What's the Difference?_](https://auth0.com/blog/id-token-access-token-what-is-the-difference/)
> 
> Want to know more about refresh tokens? See our article, [_What Are Refresh Tokens and How to Use Them Securely_](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/).

The piece of information that we’re most interested in (for this exercise) is the ID token.

When the `print()` function is used to output the contents of `credentials`, the values of the `idToken` and `accessToken` properties are replaced with the string `<REDACTED>` as a security measure. Malicious parties can use tools to capture the output of `print()` functions from production apps; this is why `Credentials` instances redact the values of their `idToken` and `accessToken` properties when printed.

Note that when we use the `print()` function to output `credentials.idToken` — the ID token itself — the value is _not_ redacted. That’s because this value is useful for debugging, which we’ll do in the next step.

> It’s fine to print the value of the ID token to the debug console while you’re learning about the authentication process or building the app. Make sure you remove `print()` statements — especially those that print sensitive information, such as the ID token — before putting them into production!


### What’s in the ID token?

📺 [The _What’s in the ID token?_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2118s)

To see what’s in the ID token, copy its value from the Debug area, go to Auth0’s [JWT.io site](https://jwt.io/) and paste that value into the _Encoded_ text area on the left side of the page. JWT.io will decode the ID token from its JWT form and display its decoded contents in the _Decoded_ area on the page’s right side:

![JWT.io and the decoded ID token.](https://images.ctfassets.net/23aumh6u8s0i/4sg6VirydfCzVVenH6LWil/174552abed55b4fe3d8100493c1510db/jwt.io_screenshot.png)

In the _Decoded_ area’s _Payload_ section, you’ll see the decoded user information from the ID token, including the data that we want the app to display: the user’s name, email address, and picture.

In the next step, we’ll give the app the same ID token-decoding capability as JWT.io’s.

> Auth0 has plenty of information about JWTs. In addition to the main [JWT.io page](https://jwt.io/), you should visit JWT.io’s [_Introduction to JSON Web Tokens_](https://jwt.io/introduction) and download our [free JWT Handbook](https://auth0.com/resources/ebooks/jwt-handbook).


## Get the User’s Information

📺 [The _Get the User’s Information_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2223s)

The app only “knows” whether the user is logged in or logged out in its current state. It also has information about the user’s identity encoded in the ID token. Let’s extract this user information — the *user profile* — and use it to display the user’s name, email address, and picture when the user is logged in. 

🛠 In `Profile`, add the following `import` statement before the `struct Profile` line:

```Swift
// [ 📄 Profile.swift ]

import JWTDecode

// [ More code here ]
```

🛠 In the `Profile` extension, replace the `// TODO: Implement the 'from()' method.` comment with this `from()` method. It uses a couple of methods from the newly-imported `JWTDecode` library:

```swift
// [ 📄 Profile.swift ]

// [ More code here ]

  static func from(_ idToken: String) -> Self {
    guard
      let jwt = try? decode(jwt: idToken),
      let id = jwt.subject,
      let name = jwt.claim(name: "name").string,
      let email = jwt.claim(name: "email").string,
      let emailVerified = jwt.claim(name: "email_verified").boolean,
      let picture = jwt.claim(name: "picture").string,
      let updatedAt = jwt.claim(name: "updated_at").string
    else {
      return .empty
    }

    return Profile(
      id: id,
      name: name,
      email: email,
      emailVerified: String(describing: emailVerified),
      picture: picture,
      updatedAt: updatedAt
    )
  }
  
// [ More code here ]
```

Given an ID token string, the `from()` function creates a `Profile` instance. If `from()` can extract claims — values about the user’s identity, which include their name, email address, and the URL for their picture — from the ID token, it returns a `Profile` instance with that information in its properties. Otherwise, it returns a `Profile` instance with empty properties.


## Display the User’s Information

📺 [The _Display the User’s Information_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2424s)

Now that there’s a way to extract information from an ID token, let’s put it to use. 

Since `userProfile` is marked with the `@State` attribute, it defines the user interface’s state. Whenever `userProfile` or one of its properties changes, the app redraws the user interface to reflect the change.

We want to display the user’s information when they log in, so we’ll use `Profile`’s newly-created `from()` method in the `login()` method.

🛠 Open `ContentView` and update `login()` as shown below:

```swift
// [ 📄 ContentView.swift ]

// [ More code here ]

  func login() {
    Auth0 // 1
      .webAuth() // 2
      .start { result in // 3
        switch result {
          // 4
          case .failure(let error):
            print("Failed with: \(error)")
          // 5
          case .success(let credentials):
            self.isAuthenticated = true
            // 👇🏽👇🏽👇🏽 New line of code here!
            self.userProfile = Profile.from(credentials.idToken)
            // 👆🏽👆🏽👆🏽
            print("Credentials: \(credentials)")
            print("ID token: \(credentials.idToken)")
        }
      }
  }

// [ More code here ]
```

The newly-added line of code runs after the user logs in, and the app receives the ID token. It creates a new `Profile` instance from the data in the ID token and sets `ContentView`’s `userProfile` property to that instance.

When the user logs out, we should clean up the user profile just to be safe.

🛠 Update `logout()` as shown below:

```swift
// [ 📄 ContentView.swift ]

// [ More code here ]

  func logout() {
    Auth0
      .webAuth()
      .clearSession { result in
        switch result {
          case .success:
            self.isAuthenticated = false
            // 👇🏽👇🏽👇🏽 New line of code here!
            self.userProfile = Profile.empty
            // 👆🏽👆🏽👆🏽

          case .failure(let error):
            print("Failed with: \(error)")
        }
      }
  }

// [ More code here ]
```


## Run the App Again

📺 [The _Run the App Again_ section of the video](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2566s)

Run the app and confirm that the changes work. When you log in, you should see the user’s name, email address, and picture:

![The app’s “logged in” screen, featuring the text “Logged in” and displaying the user’s picture, name, and email address.](https://images.ctfassets.net/23aumh6u8s0i/1zYLUYAU3fdbLLde9PmhCN/90854331950e7557fbcc52db5bcb7379/logged_in_screen.png)

Congratulations, and high-fives and handshakes all around! You’ve taken a SwiftUI app and given it the ability to authenticate users with Auth0.


## Next Steps

SwiftUI is an expansive topic; we only scratched its surface in this tutorial. For your next steps in exploring it, you might want to look at these valuable resources:

- [SwiftUI by Example](https://www.hackingwithswift.com/quick-start/swiftui)
- [Your First SwiftUI App](https://www.youtube.com/watch?v=VlhcNR7Qrno)
- [Stanford University’s “Developing Applications for iOS” course for Spring 2021](https://www.youtube.com/playlist?list=PLpGHT1n4-mAsxuRxVPv7kj4-dQYoC3VVu)

📺 Last but not least, the video ends with [closing remarks and a quick accordion number](https://www.youtube.com/watch?v=xOBoLegDmTw&t=2645s)!

Get Started with iOS Authentication using SwiftUI, Part 2: User Info, ID Tokens, and JWTs

How Auth0 enhances this nonprofit startup’s use case

**Challenge:** You’re a nonprofit or startup, or maybe even both, with [digital experiences](https://www.okta.com/blog/2024/03/how-nonprofits-achieve-their-missions-while-delivering-secure-digital-experiences/)— such as an app or a website—and your team wants to implement a third-party user authentication solution with solid security.

If you oversee authentication and authorization at a nonprofit or a startup, the roadblocks to implementing a third-party solution might be endless. Whether you’re a nonprofit trying to reduce non-program expenses or a startup with a limited budget considering rolling your own user authentication, choosing an off-the-shelf solution will allow you to spend even more time focusing on your mission and core product. This means getting your app to market faster and providing a secure experience to your users, donors, volunteers, community members, and more. 

## Species360, a Global Leader in Wildlife Care and Conservation

[Species360](https://species360.org/), an NGO and global leader in wildlife care and conservation, is an example of a nonprofit organization that transitioned its in-house solution to Auth0 by Okta. “Species360 combines passion-based, non-profit operating principles with cutting-edge software development.” ([species360.org](http://species360.org/)) As a tech-forward nonprofit, it started its journey with Auth0 through our [Auth0 for Startups](https://auth0.com/startups) program and then leveraged our [Okta for Good](https://www.okta.com/solutions/nonprofits/) preferential pricing and support. Learn more about Species360’s journey with Okta [here](https://www.okta.com/customers/species-360/). In this article, we’ll dive into Species360’s assessment and implementation processes. 

## Assessment

Species360 wanted to remove Customer Identity and Access Management (CIAM) from its plate and didn’t want to worry about building anything except for a few customizations. Species360’s acquisition of [Hortis](https://www.hortis.com/), the plant collection platform that already used Auth0, influenced the team’s decision to outsource and enabled them to get up and running quickly. “I felt it was better to focus more on the hard cost of outsourcing it [user authentication] to a company that does it as well as we would want to do it anyways.” - Clint Pidlubny, Director of Technology, Species360. 

## Implementation

In order to modernize its ZIMS (Zoological Information Management System) platform, Species360 is overhauling its legacy application software and rearchitecting the future version of its current platform. In parallel to updating its current platform, Species360 is also building a new version of the platform. As the team continued their setup and interacted with the [Auth0 APIs](https://auth0.com/docs/api) and the [React SDKs](https://auth0.com/docs/quickstart/spa/react/01-login), they decided to fully integrate Auth0 into the new version.

![Implementation](https://images.ctfassets.net/23aumh6u8s0i/4fHpU4ns0uH9boHkdvx7UM/d584896a850f9a774281dc80f0dbcd37/Uploaded_from_Species_360_Developer_Blog_-_Draft)

The Species360 team felt that getting the platform set up and configured was simple on their end. For this, they relied on the [Deploy CLI Tool](https://auth0.com/docs/deploy-monitor/deploy-cli-tool) - an Auth0-provided tool that helps you manage your Auth0 tenant configuration, integrating into your development workflows as a standalone CLI or as a node module. They leveraged the tool and SDKs to ensure that the progression between environments could be done programmatically. 

## Valuable Features

In addition, Species360 leveraged [Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login) and [Enterprise Connections](https://auth0.com/docs/authenticate/enterprise-connections) for its larger and more sophisticated members who preferred a streamlined user experience with SSO connectivity. Species360 also benefits from these features because sometimes its members have different security standards than it does. Auth0 Enterprise Connections allow users to authenticate with an external, federated identity provider (IdP) such as Azure AD, Google Workspace, PingFederate, and more. 

![Valuable Features](https://images.ctfassets.net/23aumh6u8s0i/3BGSDKHrHCYeTQGvomBc34/ce04769498fe349910e27685aa219620/Uploaded_from_Species_360_Developer_Blog_-_Draft)

Today, Species360 uses Enterprise Connections on both its Zims and Hortis platforms. In fact, on the Hortis platform, that feature has allowed the team to win business where SSO connectivity was a requirement.

Species360 has also configured [SMTP Email Providers](https://auth0.com/docs/customize/email/smtp-email-providers/configure-365-exchange-as-smtp-email-provider), so it can integrate Auth0 capabilities with Microsoft 365 and send emails through its usual email provider. 

![Conclusion](https://images.ctfassets.net/23aumh6u8s0i/2tv0ZtGehGSixJm96KLsCT/391bcdcde32633ff98b5301616265110/Uploaded_from_Species_360_Developer_Blog_-_Draft)

## Conclusion

We’re always interested in learning from our customers - specifically, what advice they would give to someone looking to implement user authentication for the first time. Clint rolled his own auth in the past and said, “APIs are ubiquitous…There’s almost a service for everything. The idea is that I can… get into a startup program—or have access to bring on however many users for free and outsource some of these complex pieces so I don't have to think about them.” **His advice is simple: developers should look externally to see who’s done this better and then leverage that capability.**

<include src="QuoteCard" body="We’re not in the business of user management; we’re in the business of data management for the animal species and our members' facilities. I don't want my team to have to spend an hour a month thinking about the user management side of things because, for us, that's not the value we’re creating." name="Clint Pidlubny" title="Director of Technology" team="" company="Species360" />

## Get Started Today

Auth0 by Okta has discounted offerings for [nonprofits](https://auth0.com/nonprofits/get-started) and [startups](https://auth0.com/startups) alike. We want to help extend your team’s capacity and give your customers, members, donors, volunteers, and communities a secure and flexible way to access your services. [Start building today](https://auth0.com/signup?utm_source=blog&utm_medium=auth0&utm_campaign=productblog).

A Developer’s Journey with User Authentication: Species360

Add Private Key JWT authentication to your .NET application to empower security in sensitive contexts.

Sensitive operations require increased security mechanisms, but at the same time, threat actors are on the rise, so it's crucial to raise the bar on application authentication security, such as using Private Key JWT authentication. Private Key JWT is a secure authentication method for applications to get security tokens from an authorization server. In this article, you will learn when you may need it, how it works, and how to implement it in a .NET application using Auth0.

## When a Client Secret Is Not Enough

In the OAuth 2.0 context, your application needs to authenticate in order to get an ID, access, and refresh token. This means that your application must provide its [credentials](https://auth0.com/docs/secure/application-credentials), typically a client ID and a secret, to the authorization server, such as Auth0.

Sensitive applications typically run in a server environment and are [confidential clients](https://auth0.com/docs/get-started/applications/confidential-and-public-applications#confidential-applications), i.e., applications capable of securely storing their credentials. Typically, these are server-rendered web applications or back-end services and applications that run in a protected environment. [Public clients](https://auth0.com/docs/get-started/applications/confidential-and-public-applications#public-applications), such as Single-Page Applications or mobile apps, can't securely store a secret. They must use [specific flows](https://auth0.com/docs/get-started/applications/confidential-and-public-applications#grant-types) that don't include client authentication, and their level of security is generally less reliable than that of a confidential client.

Although client authentication based on client secret provides a higher level of security for obtaining the access token than a public client flow, there are contexts in which it is considered insufficient. Think of banking or financial contexts, where the highest levels of transaction security must be ensured. Or in the healthcare context, where data confidentiality must be protected.

In these contexts, various regulations (e.g., [Open Banking](https://www.openbanking.org.uk/)) require the use of more secure mechanisms to protect transactions. Among these mechanisms, they require a more secure alternative to client authentication based on client ID and secret.

## Private Key JWT Authentication

[Private Key JWT authentication](https://auth0.com/docs/secure/application-credentials#private-key-jwt-authentication) is a secure alternative to client authentication based on a secret. It's a [standard mechanism](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-jwt-bearer) that relies on asymmetric cryptography to authenticate your application.

Basically, you generate a private and public key pair. Keep your private key securely stored and accessible to only your application. Don't even share it with Auth0. Share the corresponding public key with Auth0 instead. By nature, the public key is not sensitive data, so even if an attacker manages to catch it, they can't impersonate your application.

When your application needs an access token, it generates a specific JWT, called *assertion*, and signs it with its private key. Then, it sends this assertion to Auth0 in order to authenticate. The following is an example of an HTTP request to authenticate via an assertion:

```bash
curl --request POST \
  --url 'https://<YOUR-AUTH=-DOMAIN>/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=<YOUR_CLIENT_ID> \
  --data client_assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOi... \
  --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  --data audience=<YOUR_API_IDENTIFIER>
```

Auth0 validates the assertion using your application's public key and, if everything is ok, issues your access token.

If you want to learn more details about [how to authenticate with Private Key JWT, read the documentation](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt). If you use one of the Auth0's SDKs, you don't need to build an assertion yourself, as you will see later in this article.

> Private Key JWT authentication is only available with the [Enterprise plan](https://auth0.com/pricing).



## Highly Regulated Identity and Private Key JWT Authentication

As mentioned, Private Key JWT authentication is a secure client authentication method required in business contexts where higher levels of security must be guaranteed, such as in finance, insurance, and healthcare.

To meet customers' needs in this area, Okta has released [Highly Regulated Identity (HRI)](https://auth0.com/docs/secure/highly-regulated-identity), a set of Auth0 features that enable high levels of security standards, such as [Financial Data Exchange](https://financialdataexchange.org/) and [Open Banking](https://www.openbanking.org.uk/), and compliance with widely adopted regulations, such as the [Payment Services Directive (PSD2)](https://www.europeanpaymentscouncil.eu/sites/default/files/infographic/2018-04/EPC%20Infographic_PSD2_April%202018.pdf).

> Highly Regulated Identity is an add-on for the Enterprise plan. For an overview of [Highly Regulated Identity, check out this article](https://auth0.com/blog/elevate-security-and-ux-with-highly-regulated-identity/).

Private Key JWT authentication is available in the Enterprise plan, so you don't need HRI to use it in your applications. However, if you need to use PS256 as the signing algorithm for your assertions, you need HRI on top of your Enterprise plan. HRI also supports [mutual TLS](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls) as another secure mechanism for client authentication using a public-private key pair.

## The Sample Project

To see how to use Private Key JWT authentication in practice, you will use an ASP.NET Core web application that gets users' health data from a protected API. You can download the sample project by running the following command in a window terminal:

```bash
git clone -b starting-point --single-branch https://github.com/auth0-blog/dotnet-private-key-jwt-authentication
```

You will get two .NET projects:

- *HealthCkeckApi*, an ASP.NET Core Web API project that provides the user's health data through a protected endpoint.
- *HealthCheckWebApp*, an ASP.NET Core MVC application that implements the frontend used by the user to get their own health data.

You need an Auth0 account to configure and run the application. If you don't have one, you can <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for free now</a>. Follow the README document to configure and run the application.

Once your application is up and running and you have logged in, you will see a page like the following:

![HealthCheckWebApp home page](https://images.ctfassets.net/23aumh6u8s0i/6sAQuTcGWazJolzmaTzicI/08d8248e7dcec5cd978f11b633512823/healthcheckwebapp-home.png)

By clicking the *Show Health Checks* button, you will see a list of data like the following:

![HealthCheckWebApp checks data](https://images.ctfassets.net/23aumh6u8s0i/3hLebkfhp5Sn552D5tuppl/f2532b77a0f0577bda3d9cc04b3ddf45/healthcheckwebapp-data.png)

You will work on the *HealthCheckWebApp* application, which represents the OAuth confidential client that needs an access token to call the protected API. The current application implementation uses the [Auth0 ASP.NET Core Authentication SDK](https://github.com/auth0/auth0-aspnetcore-authentication) to authenticate the user and get the access token from Auth0 by using its client ID and secret.

You will modify this application to use Private Key JWT authentication instead of client ID and secret.

## Create and Register Your Public Key

Let's start by creating a private and public key pair. Go to the `HealthCheckWebApp` folder and generate your private and public key pair. For example, using [OpenSSL](https://www.openssl.org/) you can create the key pair with the following command:

```bash
openssl genrsa -out app_keys.pem 2048
```

This command generates an `app_keys.pem` file containing the private and public key pair you will use as a credential for your application.

Extract the public key from that file with the following command:

```bash
openssl rsa -in app_keys.pem -outform PEM -pubout -out pub_key.pem
```

You will get a `pub_key.pem` file containing only the public key. You will be sharing the public key with Auth0, while your private key must be kept safe and never shared with anyone.

Go to your [Auth0 dashboard](https://manage.auth0.com/) and open the *Credentials* tab of your application configuration page, as shown in the following image:

![Private Key JWT credentials in the Auth0 dashboard](https://images.ctfassets.net/23aumh6u8s0i/3jt9HLrTXYTOIwYFkPWSVE/d0c86d8b49331d22f461ea5482a78fac/auth0-private-key-jwt-credentials.png)

Select *Private Key JWT*, and a window like the following will show:

![Private Key JWT credential configuration](https://images.ctfassets.net/23aumh6u8s0i/5YiXuI8YceCxplwKghjmd2/0f8e8d8440e27795de4e6666a6f4ece9/auth0-private-key-jwt-configuration.png)

This window allows you to define a Private Key JWT credential for your application. Assign a name for the credential and upload the `pub_key.pem` file containing the public key. Optionally, select the signing algorithm and set an expiration date. Finally, click the *Add Credential* button to save your changes.

You will see your credential appearing below the *Application Authentication* section:

![Auth0 Private Key JWT authentication credential list](https://images.ctfassets.net/23aumh6u8s0i/0yhreNj2u7io7iTPnyRMB/844280997c40fc67565a27eb0b4fb3bb/auth0-private-key-jwt-authentication-credentials-list.png)

> You can add multiple credentials for your application, as you will learn in a moment.

## Get Your Access Token

Your application is now configured to use Private Key JWT authentication on the Auth0 side. Let's adjust the application code to use this authentication method instead of the client ID and secret.

Open the `appsettings.json` file in the `HealthCheckWebApp` folder and remove the `ClientSecret` key. You don't need it anymore. The file's content will be as follows:

```json
// HealthCheckWebApp/appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Auth0": {
    "Domain": "<YOUR-AUTH=-DOMAIN>",
    "ClientId": "<YOUR-CLIENT-ID>",
    "Audience": "https://myapi.com"
  },
  "HealthCheckApiBaseUrl": "https://localhost:7102"
}
```

Now, edit the `Program.cs` file in the `HealthCheckWebApp` folder by applying the changes highlighted in the following code snippet:

```csharp
// HealthCheckWebApp/Program.cs

// ...existing code...

// 👇 new code
var cryptoProvider = new RSACryptoServiceProvider();
cryptoProvider.ImportFromPem(File.ReadAllText("app_keys.pem"));
var securityKey = new RsaSecurityKey(cryptoProvider);
// 👆 new code

builder.Services
    .AddAuth0WebAppAuthentication(options => {
      options.Domain = builder.Configuration["Auth0:Domain"];
      options.ClientId = builder.Configuration["Auth0:ClientId"];
      // 👇 old code
      //options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
      options.ClientAssertionSecurityKey = securityKey;
      // 👆 new code
      options.Scope = "openid profile email";
    })
    .WithAccessToken(options =>
      {
          options.Audience = builder.Configuration["Auth0:Audience"];
      });

// ...existing code...
```

You load the key pair from the `app_keys.pem` file, generate an instance of the `RsaSecurityKey` class from the content of that file, and assign it to the `securityKey` variable. Then, you replace the assignment of the `ClientSecret` option with the `ClientAssertionSecurityKey` option and assign the value of the `securityKey` variable.

You are done! The Auth0 ASP.NET Core Authentication SDK will take care of creating the assertion and authenticate your application with Auth0 to get the access token. You will notice no difference in the behavior of the application, but under the hood your application uses a more secure authentication method to get the access token to call the protected API.

<include src="ebook-ads/dotnetIdentity" />

## Credential Rotation

When you configured your application to use Private Key JWT authentication, you should have noticed two things:

- You can set an expiration date.
- You can create multiple credentials for the application.

These two optional features allow you to further strengthen the security of Private Key JWT authentication.
In fact, setting an expiration date for a credential is always a good practice, even with secure mechanisms such as Private Key JWT.

However, setting an expiration date can cause some downtime when the old credential expires and the new one has not yet been activated. To avoid this downtime, you can add a new credential before the old one expires. This way, on the application side, you can replace the old credential with the new one before it expires, preventing the application from becoming inoperable.

For more information about credential rotation, see [the documentation](https://auth0.com/docs/get-started/applications/rotate-credentials).

## Summary

Throughout this article, you learned about Private Key JWT authentication and how it increases your application's level of security in obtaining tokens.

Together with other advanced features of Highly Regulated Identity, Private Key JWT helps achieve a high level of security and compliance required in areas such as finance, insurance, and health care.

You also saw how to implement Private Key JWT in a .NET application using the Auth0 SDK, which relieves you of the task of dealing with low-level details.

The final version of the example application code implementing Private Key JWT is available on [GitHub](https://github.com/auth0-blog/dotnet-private-key-jwt-authentication).



Use Private Key JWTs to Authenticate Your .NET Application

Join the Okta event for developers who care about the security of their applications and the identity of their users.

Mark your calendars for **September 24th** for Okta's event designed by developers for developers: **Developer Day 2024**!

Like every year, you'll learn how Auth0 helps you secure your applications and users' identities. But this year, it will be different. You will be hearing many exciting news at the event and discover how much Okta cares about working with you to build a more secure world.

But it's not just about announcements. You will have the opportunity to put the new features into practice through **curated sessions and hands-on labs**.

Developer Day 2024 will be a **free virtual event open to anyone from anywhere in the world**. DevDay will kickoff at **9:00 AM BST** (10:00 AM CEST) with a captivating Keynote followed by 35+ developer sessions and labs that dive into how devs can use the latest features from Auth0.

If you are a developer who cares about the security of your application and your users, you cannot miss this opportunity to learn directly from the experts in the field.

<AmpContent>
<amp-youtube
    data-videoid="UqMxbmY5MNc"
    layout="responsive"
    width="480" height="270">
</amp-youtube>
</AmpContent>

<NonAmpContent>
<div
  className='embed-container'
  style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;margin-bottom:40px;">
    <iframe
      style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
      src='https://www.youtube.com/embed/UqMxbmY5MNc'
      frameborder='0' allowfullscreen>
    </iframe>
</div>
</NonAmpContent>
<p></p>

Curious about the event's agenda? It will be revealed around mid-August, so stay tuned and keep an eye on the [Developer Day website](https://developerday.com/) to be the first to know the cool topics in store for you.

What are you waiting for? **[Register now](https://developerday.com/register)** to ensure your access to this outstanding event!


Developer Day 2024 Is Here!

When you are working on a complex web application, at some point, you’ll want to restrict or grant access. In this post we'll explore some of the most commonly used access control paradigms.

Whether you are working on a complex web application, managing a hosting infrastructure, or configuring your company's applications, at some point, you’ll want to restrict or grant access to specific people, groups, or applications, depending on some properties. These can be a role or permission, the time of day or location, or the relationship between two entities. Based on your scenario and the level of complexity, one or more access control approaches might work for you.

## Coarse-Grained (CGA) Versus Fine-Grained Access Control (FGA)

We can distinguish two general strategies based on how granular you want to be when making access control decisions. You either choose a coarse or fine-grained approach.
A coarse-grained approach assigns permissions to a large group of users and resources.
A fine-grained approach looks at the bigger picture, taking into account a lot of different data points and scenarios or assigning permissions to a more limited group of users and resources, or even unique permission per user and resource.

Both strategies have their place, and choosing the level of detail you want to include in your access control decisions might influence the paradigms you can use. For example, a role-based access control usually implements coarse-grained access control, while the relationship-based access control approach is ready to make very fine-grained decisions.

## Role-Based Access Control (RBAC)

The first access control paradigm we’ll discuss in this article is **role-based access control**. It is the most commonly used approach and the simplest to start with. Role-based access control, as the name implies, uses a system of roles and permissions to make a decision.

A role is a collection of permissions that can be assigned to a user, and a permission indicates a certain allowed action that can be performed by any user assigned a role containing this permission. For example, a `guest` role might have permission to view all posts on a website, while an `admin` role could have both a view and delete permission attached to it.

```
guest: [
  view:post
]

admin: [
  view:post,
  delete:post
]
```

Your application can either check if the current user has `delete` permissions or has been assigned the admin role. Either scenario will let your app know the user should be able to delete posts. Checking for permissions over roles offers the benefit that your application doesn’t need changes when roles and their permissions change over time.

To get the roles or permissions, your application typically requests them from a user-info endpoint, or your authorization server adds them to the access and/or ID tokens issued when the user is authenticated.

Because we check for permission based on a resource type rather than a specific resource like `post x` or `post y`, RBAC is an example of a coarse-grained access control approach.

## Attribute-Based Access Control (ABAC) or Policy-Based Access Control (PBAC)

**ABAC** or **PBAC** is an access control strategy in which a decision is made based on assessing attributes related to a request or situation. Policies define how these attributes are evaluated. The most common types of attributes are **user** (role, job title, security level), **environment** (time of day, location), **resource** (resource type, data sensitivity), and **action** (read, write, delete). Combining multiple attributes into one or more policies offers a highly customizable and fine-grained solution to grant or limit actions within your applications or systems. The more policies you create, the more control you have over your access decisions, but the harder it becomes to maintain these policies.

An attribute-based access control system often consists of at least a decision engine and a policy language you can use to describe scenarios and their outcome. The same is true for ReBAC, but more on that later.

The decision or policy engine will evaluate data presented in a request against one or more policies written in the policy language. The downside is that you first need to gather the relevant data before passing it to the decision engine for evaluation. This often requires some extra database lookups.

If, for example, you’d like to check if a user can view a document in a parent folder owned by the same user, you’d first need to read the document database table. You'd then search the parent folder for that document and check if a user has access to that folder. Once you’ve done the lookup, you can pass this information to the policy engine to make an informed decision. 

### Open Policy Agent (OPA)

[Open Policy Agent (OPA)](https://www.openpolicyagent.org) is a declarative policy engine that strongly focuses on access control for infrastructure like Docker or Kubernetes containers. Their homepage describes OPA as “Policy-based control for cloud-native environments, flexible, fine-grained control for administrators across the stack.”. This doesn’t mean you can’t use it for other use cases, but it is best suited for managing infrastructure access.

Open policy agents are usually deployed as a “sidecar” beside your applications or infrastructure. This sidecar contains all policies and some relevant data in JSON files. If you run multiple applications, containers, or clusters, it can become a difficult chore to keep all policies and data up-to-date across all OPA sidecars.

Let’s look at an example. If a request comes from an origin we have on a disallow list, the policy engine will return a negative decision. For this to work, we would have written a policy that specifies that the engine looks through a list of blocked origins and checks if the origin, which is part of the request to the decision engine, is part of that list.

OPA policies are written in REGO, a generic programming language that allows you to write detailed policies. Because it is a generic language, it has a steep learning curve and usually takes some time to get used to.

Some [pseudocode](https://play.openpolicyagent.org/p/THKqtQ3QME) for the example above written in [the REGO language](https://www.openpolicyagent.org/docs/latest/policy-language/) would look like the following. 

```REGO
deny[reason] {
    disallowedOrigins := ["blocked.com","malicious.com"]

    some input.request.origin in disallowedOrigins
    reason := sprintf("origin %s has been blocked", [input.request.origin])
}
```

Because Policy engines are usually built to make split-second decisions by evaluating a limited dataset against a mostly static set of policies, they are perfect for infrastructure scenarios without constant changes to the data or the policies. Therefore, there’s no need for a scalable, consistent way to add or remove decision data within these engines. 

This might become an issue when dealing with application access control, especially if your application deals with many users who create or manage content. Each time a user performs an action, your application needs to gather all relevant data points before passing them on to the policy engine. Because of this, the latency of your request depends more on how much time it takes to gather this information than on how fast your decision engine can evaluate its policies. As your application scales, so does your data. These lookups can become a bottleneck for fast and reliable access control decisions.

Luckily, the next access control strategy I want to discuss, relationship-based access control, is built just for these use cases.

## Relationship-Based Access Control (ReBAC)

**Relationship-based access control** is a strategy that offers a fine-grained control based on looking at relationships between users and resources, or between multiple (different) resources.

Most ReBAC implementations today are based on Google's Zanzibar paper. In this paper, they describe the system they’ve built internally to handle a variety of access control scenarios across the whole Google ecosystem. This system needs to be flexible enough to handle authorization scenarios for their varied range of products and fast enough not to impact the user’s experience with them. 

To learn more about the Zanzibar paper, visit our informational website [zanzibar.academy](https://zanzibar.academy).

Just like attribute-based access control, ReBAC usually has a decision engine and a modeling language that lets you define relationships the engine will evaluate. New to this paradigm is a database that stores a large and ever-changing set of data related to all users and resources and their relationships. Whenever a user performs an action, this dataset can be impacted.

### OpenFGA 

[OpenFGA](https://openfga.dev) is an open-source solution for Zanzibar-style ReBAC access control. It’s been adopted by the Cloud Native Computing Foundation (CNCF) and actively worked on by members of Okta and the open-source community. OpenFGA uses an easy-to-read domain-specific language (DSL) to model the authorization model and exposes an API to add tuples to a database or query for access control decisions.

<include 
    src="LinkCard" 
    title="Do you prefer a managed ReBAC solution?" 
    link="https://fga.dev" 
    description="Okta FGA is built on top of OpenFGA and takes away the headaches of hosting, scaling, securing, and backing up your data. 
Find out more at fga.dev."
/>

### Direct versus indirect relationships

The relationships defined in the authorization model can be either direct or indirect. Simply put, direct relationships are directly assigned between a consumer and a resource (we call them user and object) and stored in the database. Indirect relationships are the relationships we can infer based on the data and the authorization model. 

We can write our first simple authorization model using OpenFGA DSL to define a `user` and a `repository` type. A repository can have a user or multiple users as a relation. Knowing this, we can assign a user as the owner of a GitHub repository by saving the following tuple in the database:

```
type user
type repository
  relations
    define owner: [user]
```

```
{
  user: "user:sam",
  relation: "owner",
  object: "repository:fga-demo"
}
```

When we ask the decision engine whether user `Sam` is the owner of the `fga-demo` repository, the engine looks in the database, finds the tuple, and gives us a positive response.

The true power of ReBAC lies in its ability to calculate indirect relationships—relationships that are not explicitly defined but can nonetheless be found between a user and an object. If we expand the GitHub example and add an organization, we can check whether members of that organization can commit to a repository owned by that organization, even if they are not directly assigned as a `repo_writer`.

```
type user
type organization
  relations
    define member: [user]
    define repo_writer: [user] or member
type repository
  relations
    define owner: [organization]
    define can_commit: repo_writer from owner
```

```
{
  user: "user:sam",
  relation: "member",
  object: "organization:okta"
},{
  user: "organization:okta",
  relation: "owner",
  object: "repository:fga-demo"
}
```

Given this new model and these two tuples, we can query for some direct and indirect relationships.
- Direct: `Sam` is a `member` of the `Okta` organization 
- Direct: The organization `Okta` is the `owner` of the `fga-demo` repository
- Indirect: `Sam` is a `repo writer` for the `fga-demo` repository
- Indirect: `Sam` can commit to the `fga-demo` repository

By examining the relationships between users (consumers) and objects (resources) instead of a static list of roles and permissions, Rebac offers a highly flexible and powerful way to deal with fine-grained authorization decisions within applications.

## Hybrid Access Control Solutions

While most access control products, services, or libraries started out with a specific approach in mind, many of them added (partial) support for other paradigms to be flexible, all-in-one solutions.

Using **OpenFGA**, [Contextual Tuples](https://openfga.dev/docs/modeling/token-claims-contextual-tuples) allow authorization checks that depend on dynamic or contextual relationships not written to the OpenFGA store, enabling some attribute-based access control (ABAC) use cases. For example, allow or disallow an action based on the time of day. You can also use [conditions](https://docs.fga.dev/modeling/basics/conditions) to make your authorization models more flexible.

**OPA** was originally created to deal with ABAC for infrastructure. There are some initiatives, like [TOPAZ](https://www.topaz.sh), that are adding a database to the system, allowing it to make decisions on a larger, more dynamic dataset, just like ReBAC does, avoiding the need to gather all relevant data before asking your policy engine for a decision.

[OPAL](https://www.openpolicyagent.org/integrations/opal/) is another initiative that adds an administration layer to OPA. This layer helps you sync the policies and data in your OPA sidecars across your agents.

## Conclusion

There is **no magic bullet for dealing with authorization in all scenarios** we, as application builders, have to face. 

Considering which approach works well for your situation will help you scale your authorization decisions as your application or infrastructure grows more complex. So, ask yourself whether you’re looking for a simple role-based or finer-grained solution. An attribute or policy-based approach might work great if you're dealing with infrastructure. Still, a relationship-based approach might be the best solution for complex applications, saving you from doing some extra database lookups before making each access control decision.

An Overview of Commonly Used  Access Control Paradigms

Learn how to seamlessly integrate Auth0 into your newsletter sign-up process, ensuring compliance with GDPR regulations. This simple guide walks you through different methods to collect user consent for newsletter signups.

Engaging your users and keeping them informed about the latest features you deploy is crucial for any successful online business. However, it's equally important to ensure your communication efforts comply with users’ right to privacy and regulations like GDPR.

Thankfully, if you're already using Auth0 for user authentication, you have a powerful tool at your disposal to streamline the process of obtaining consent for email communications.

In this article, we'll delve into how you can leverage Auth0's capabilities to seamlessly integrate GDPR-friendly newsletter sign-ups directly into your existing user registration or onboarding flows. We'll cover best practices for obtaining explicit consent using two different approaches. By the end, you'll have a streamlined system that not only grows your email list but also fosters trust and transparency with your users.

## Method 1: Customize Signup and Login Prompts

Auth0's Universal Login feature provides a convenient way to add a newsletter sign-up option directly into your existing login or registration process. You can easily customize the Universal Login sign-up form to include an input checkbox for newsletter subscriptions.

When designing this checkbox, it's crucial to use clear and concise language that leaves no room for ambiguity. The checkbox should be unchecked by default, and the wording should explicitly state that the user is agreeing to receive marketing emails from your company.

Here's an example using Auth0 signup prompts for gathering consent:

![Example of Auth0 signup prompts for gathering consent for marketing purposes](https://images.ctfassets.net/23aumh6u8s0i/4n1CUQRKeGZDfnh4WaPoH/310a9792c14981c94634e94498d98b72/checkbox-consent-example.png)

Once the user submits the form, Auth0 can store their consent status as a custom field in their user profile. This allows you to easily track who has opted in to receive your newsletter and segment your audience accordingly.

The documentation provides great detail on [how to customize signup and login prompts](https://auth0.com/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts), so I won't be covering the steps here, but I'll share some of the code I used to set up the example above.

To add the new field to the signup form, I made the following call to the management api:

```shell
curl -L -X PUT 'https://{auth0-domain}/api/v2/prompts/signup/partials' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {access-token}' \
-d '{"signup":{"form-content-end":"<div class=\"ulp-field\"><input type=\"checkbox\" name=\"ulp-newsletter-consent\" id=\"newsletter-consent\"><label for=\"newsletter-consent\">I agree to receive information and commercial offers to my e-mail.</label></div>"}}'
```

Which will inject the following HTML after the login form.

```html
<div class="ulp-field">
    <input type="checkbox" name="ulp-newsletter-consent" id="newsletter-consent" />
    <label for="newsletter-consent">I agree to receive information and commercial offers in my e-mail.</label>
</div>
```

Then, I'm using Auth0 Actions to automatically sign up the user to my newsletter service. Here's the code for the action:

```javascript
exports.onExecutePreUserRegistration = async (event, api) => {
  const consent = event.request.body['ulp-newsletter-consent'];

  if(consent) {
    api.user.setUserMetadata("newsletter_consent", consent);
    api.user.setUserMetadata("newsletter_consent_date", Date.now());

    // Call the newsletter service API to subscribe the user
    await fetch(`https://newsletter-api.example.com/u/${event.user.email}`, {
      method: "POST"
    })
  }
};
```

You'll have to adapt the HTTP call to match your newsletter service API, or, what I prefer to do, is to add the email to a processing queue, which then triggers the newsletter subscription.

<include 
    src="LinkCard" 
    title="There's a lot more you can do with prompts" 
    link="https://auth0.com/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts" 
    description="Explore the documentation to find out other use cases and examples for prompts." 
/>

### Key considerations for this approach:

- **Integrated with Sign-Up Form**: This method seamlessly blends the newsletter sign-up with the user's initial interaction.
- **Social Login & Passkeys**: Keep in mind that this approach won't work if your primary login methods are social logins (e.g., Google, Facebook) or passkeys.
- **Custom Domain and Custom Page Template Required**: To leverage this functionality, you'll need to have a custom domain set up for your Auth0 tenant.

## Method 2: Using Auth0 Forms for Dedicated Consent Collection Step

If you need a more comprehensive consent collection solution or want to gather additional information beyond a simple yes/no for the newsletter, [Auth0 Forms](https://auth0.com/docs/customize/forms) is the solution for you. This approach involves presenting users with a dedicated form during the authentication process, allowing for more detailed data collection and tailored consent options.

Auth0 Forms is a powerful visual editor that empowers you to create custom, dynamic forms that integrate seamlessly with your authentication flows. These forms can be, for example, used for:

- **Progressive profiling**: Collect user preferences, demographics, or any other data relevant to your business.
- **Enforce Policies**: Require users to accept updated terms and conditions or privacy policies before accessing your application.
- **Customize Authentication Flows**: Add steps to your login or sign-up processes, such as email or phone number verification, OTP, account linking, or consent collection.
- **Trigger Custom Actions**: Initiate backend processes or workflows based on user input.

### How Can Auth0 Forms Be Used for Consent?

Auth0 Forms provide a flexible framework for obtaining and managing user consent in various scenarios:

- **Newsletter Sign-Ups**:  Create a dedicated form with clear and concise language to request explicit consent for email communications.
- **Terms and Conditions Acceptance**:  Present updated terms or policies to users and require their acceptance before continuing.
- **Data Usage Consent**:  Seek permission for specific data processing activities, such as personalized advertising or data analytics.
- **Granular Permissions**:  Offer users fine-grained control over their data by allowing them to choose which types of communication they want to receive.

Here's an example of a form that collects information about the user and asks for marketing consent the second time the user logs into the application.

![Example of Auth0 Forms to collect user information and marketing consent](https://images.ctfassets.net/23aumh6u8s0i/74OX4QmLN20UuPpyIbglk4/acfcc586f1f472584b3aacea98974da3/auth0-forms-consent.png)

<include 
    src="LinkCard" 
    title="Auth0 Forms is a great resource to further customize your authentication flow." 
    link="https://auth0.com/docs/customize/forms" 
    description="Explore the documentation to find out how to build your own forms or use pre-defined templates for common use cases." 
/>

### Key considerations for this approach:

- **Universal Compatibility**: Auth0 Forms works seamlessly with all authentication methods, including social logins and passkeys, providing flexibility for your user base.
- **Additional Step**: Be aware that this method adds an extra step to the authentication flow, which, only for the purposes of asking consent, can potentially affect user experience. Consider balancing the need for comprehensive consent with the desire for a streamlined login process.
- **Versatile Usage**: Auth0 Forms aren't limited to just newsletter sign-ups. They can be used for a variety of scenarios, such as accepting terms and conditions, requesting permission for specific data usage, or collecting user preferences. This versatility makes Auth0 Forms a valuable tool for managing ongoing compliance and user engagement.

## Best Practices for Obtaining Explicit Consent

To ensure your newsletter sign-up process is fully GDPR-compliant, there are several best practices you should follow. First and foremost, use clear and concise language on your sign-up forms. Avoid legalese or confusing terminology, and be upfront about what the user is signing up for.

Additionally, consider offering granular consent options. Instead of just one checkbox for all types of communication, you could provide separate checkboxes for newsletters, product updates, or other types of emails. This gives users more control over the emails they receive and can improve engagement rates.

Another effective strategy is implementing a double opt-in process. This means that after a user submits their email address, they receive a confirmation email with a link they must click to verify their subscription. This extra step helps ensure that the email address is valid and that the user genuinely wants to receive your newsletter.

Finally, it makes it easy for users to manage their communication preferences. Provide a clear link in your emails where users can update their subscriptions or unsubscribe altogether. This demonstrates respect for their privacy and can help prevent spam complaints.

## Conclusion

By following the steps outlined in this article, you can seamlessly integrate GDPR-friendly newsletter sign-ups into your Auth0-powered website or application. This not only ensures compliance with data protection regulations but also builds trust with your users, leading to higher engagement and a more successful email marketing program.

Thanks for reading!

Using Auth0 to Collect Consent for Newsletter Signups

Learn how to leverage Auth0 Actions to create custom MFA (Multi-Factor Authentication) workflows, enforce enrollment of users based on specific conditions, and validate user authentication.

Multi-factor authentication (MFA) is an essential security measure that helps to protect your organization's data and assets. By requiring users to provide an additional authentication factor, such as a security token or fingerprint, in addition to their username and password, MFA can significantly reduce the risk of unauthorized access.

However, implementing MFA can sometimes create friction in the user experience, potentially leading to frustration and reduced productivity. Additionally, not all users or scenarios may require the same level of security, making a one-size-fits-all MFA approach impractical.

Auth0 Actions is a powerful feature that allows you to customize and extend the functionality of Auth0. With Actions, you can create custom workflows that trigger in response to specific events, such as user login or registration. This enables you to tailor your MFA implementation to meet your organization's specific needs.

For example, you can use Actions to:

- **Enforce MFA based on user roles or permissions**: You can require certain users, such as administrators or those with access to sensitive data, to use MFA while allowing others to bypass it.
- **Implement risk-based authentication**: You can use Actions to assess the risk level of a login attempt based on factors such as the user's location, device, and IP address. If the risk is high, you can then require the user to provide an additional factor of authentication.

## Prepare your Tenant

Before diving into customizing your Multi-Factor Authentication (MFA) flows, let's make sure we have the essentials in place. This quick guide will walk you through the initial setup steps:

- **Activate MFA**: Head over to your Auth0 Dashboard (<a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID"  data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">Get a free account</a> if you don't already have one) and navigate to [Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa). Here, you'll be able to activate MFA for your tenant.

- **Choose Your Factors**: [MFA comes in various forms](https://auth0.com/blog/not-all-mfa-is-created-equal/). Decide which factors suit your security needs and enable them on the same Multi-factor Auth page. You might choose options like push notifications, SMS codes, or even biometrics.
    ![Auth0 Dashboard > Security > Multi-factor Auth](https://images.ctfassets.net/23aumh6u8s0i/5NSKKAcGSjkj40ZkTmUlDD/3165f217e14e7a85b9f0304695fdf9d5/MFA_Auth.png)

- **Enable Customization**: To personalize your MFA flows, toggle on the "Customize MFA Factors using Actions" setting. This is like unlocking a secret level – it opens the door to fully customized experiences for your users.
    ![Auth0 Dashboard > Security > Multi-factor Auth > Additional Settings](https://images.ctfassets.net/cdy7uua7fh8z/2hv0ELTkkka3t230SXfxw/46def5395652b2451cfc9e0ad01a371a/MFA_actions.png)

> Actions with `enrollWith` or `enrollWithAny` commands override any existing policies or rules that enable or disable MFA in a tenant.

## Understand the APIs

Once you've enabled Multi-Factor Authentication (MFA) in your Auth0 tenant, you can go beyond the basic settings and create truly customized enrollment flows using Auth0 Actions. Actions are snippets of code that run at specific points in the user's authentication journey, giving you granular control over your authentication workflow and, in particular, how MFA is presented.

To customize your MFA experiences, Auth0 Actions provides a set of APIs designed for enrollment and requiring authentication challenges. Here's a breakdown of the four key APIs you can use: 

### `enrollWith(factor, options)`

Initiates MFA enrollment for a specific factor (e.g., `otp`, `push-notification`, `webauthn-roaming`, etc. Visit the docs to learn about [all supported values](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/api-object#:~:text=api.authentication.enrollWith(factor%2C%20options)).

Example:

```javascript
api.authentication.enrollWith({type: 'otp'})
```

### `enrollWithAny(factors)`

Similar to `enrollWith` but prompts the user to select an MFA factor to enroll in from the supplied list.

Example:

```javascript
api.authentication.enrollWithAny([{type: 'otp'}, {type: 'webauthn-roaming'}])
```

### `challengeWith(factor, options)`

Challenge the user with one or more specified multifactor authentication factors. This method presents the default challenge first, then allows the user to select a different option if additional factors have been supplied. If the user has not enrolled in any of the factors supplied (including both the default and any additional factors), the command fails.

Example:

```javascript
api.authentication.challengeWith({type: 'otp'})
```

### `challengeWithAny(factors)`

Trigger a MFA challenge and allow the user to select their preferred factor from the supplied list.

Example:

```javascript
api.authentication.challengeWithAny([{type: 'otp'}, {type: 'webauthn-roaming'}])
```

## Create a New Auth0 Action

To begin, let's create a new [Auth0 Action](https://auth0.com/docs/customize/actions/actions-overview). Actions are serverless functions that run in a secure Auth0 environment.

To create an Action, log into your [Auth0 Dashboard](https://manage.auth0.com/#/actions/flows), select Actions from the left sidebar menu, then select Flows. This page shows the different flows you can customize. For our use case, we’ll choose the “Login” flow.

![The “Actions” page of the Auth0 dashboard.](https://images.ctfassets.net/23aumh6u8s0i/3Es0FEV0EEyNeKgN6LXEeM/67763781d697663da79113ba381e8610/actions_flows.png)

This will take you to the “Login” flow page, where you can install, create, and add Actions to the flow.

![The “Login” flow page of the Auth0 dashboard.](https://images.ctfassets.net/23aumh6u8s0i/5dveq8h22H0Nje8Rub6sa9/7071335d4db1571af98440e527f1b999/actions_login_flow.png)

The screen has two main sections: the diagram in the center of the page shows the login flow and the Actions panel.

On the diagram, we can see the default login flow, which contains two states.

- **Start:** The user completed the login form and is ready to log in.
- **Complete:** The system issues the user’s credentials (an ID token and, if required, an access token).

You can drag and drop Actions in between these states to add custom logic to the login flow or deny the login request before the tokens are issued.

On the right panel, we have the Actions panel with two tabs.

- **Installed**: Pre-installed Actions from the [Auth0 Actions Marketplace](https://marketplace.auth0.com/features/actions)
- **Custom:** Actions created for this tenant

To create an Action, click the plus icon on the Actions panel and select "Build from scratch".

![Create a custom Action using the Actions panel](https://images.ctfassets.net/23aumh6u8s0i/3TABItaKOdq9dpsUIdQIpx/47d5010f5642123942ba3b7afd710300/actions_login_flow_create_menu.png)

After that, a modal window will appear to enter the information for our Action: you’ll have to provide a name, and you can leave the trigger and runtime as the default values. For my Action, I’ll name it “Require webauthn MFA for admins”.

![Enter the Action name and click create](https://images.ctfassets.net/23aumh6u8s0i/H6zvDcXGyg2a773gW790H/07ce6e74ee07f115d0e58d6e3863642f/actions_login_flow_create_dialog.png)

After clicking on "Create", you’ll be taken to the Action’s code editor, where you can write the code for your Action, install packages, test it, and more:

![Auth0 Actions code editor page](https://images.ctfassets.net/23aumh6u8s0i/6OzG8Oe3XU8lFnzLIr5Ver/4644c79782edaa0d279d4cf2112ae32c/actions_editor.png)

An Action can make use of two JavaScript functions to alter the Login flow:

- `onExecutePostLogin`: defines what should happen immediately after the user provides login credentials that Auth0 verified. This method receives two parameters, `event` and `api`.
    - `event`: contains details about the login request, such as the user and the context.
    - `api`: contains methods to manipulate the login’s behavior.
- `onContinuePostLogin`: defines what should happen when control returns to the Login Action after a redirect to another web page. It’s used only when the user returns after being redirected, which is why it’s commented out by default.

For this tutorial, we’ll focus on the `onExecutePostLogin` method.

## Writing the Actions Code

Next, we'll write the Action's code that will require users under the Admin's group to use `webauthn` as an additional authentication step. If the user isn't already enrolled with `webauthn`, the first time they login they will be prompted to do so.

The action will make use of the APIs `challengeWith` and `enrollWith`, in addition to using the user's property `enrolledFactors` to determine if the user has an MFA factor enrolled already.

Here's the actual code:

```javascript
exports.onExecutePostLogin = async (event, api) => {
    // Check if the user is an admin, enforce webauthn
    if (event.authorization?.roles?.includes('Admin')) {
        // Check if the user is already enrolled with webauthn
        if (event.user.enrolledFactors && event.user.enrolledFactors.some(m => m.type === 'webauthn-roaming')) {
            api.authentication.challengeWith({type: 'webauthn-roaming'})
        } else {
            api.authentication.enrollWith({type: 'webauthn-roaming'})
        }
    }
};
```

## Attach an Auth0 Action to the Login Flow

After coding and testing your Actions, it’s time to deploy and use them as part of the login flow. Once you are ok with your testing results, you can hit the `Deploy` button on the top right corner of the screen. This will take the existing code and settings and generate a function snapshot you can use in your login flow.

If you ever need to change the code on the function, all changes will automatically be saved as a new draft, and if you want the changes to become effective, you’ll have to deploy your latest version once again.

Once your code is deployed, it doesn’t mean it is actively used as part of your login flow. To check for that, please refer back to the [login flow screen](https://manage.auth0.com/#/actions/flows/login/), where the login diagram is shown. If you don’t see your Action as part of the diagram, it means that, even if your Action is deployed, it has not yet been activated. To activate the Action as part of the flow, click on the “Custom” tab on the Actions panel, locate your Action by name, and simply drag and drop the box over the login diagram between the "Start" and "Complete" steps. After that, you can apply changes using the “Apply” button on the top right corner of the screen.

![Apply an Auth0 Action to the Login Flow](https://images.ctfassets.net/23aumh6u8s0i/5IKiEeHy8WharqTOjJnSLh/eb5025dfd22de94c2446ccc22f1b524d/actions_attach_to_flow.gif)

## Test Your New Authentication Flow

Now, you can try your new Action by logging into your Auth0-powered application using both admin and non-admin accounts. When you log using any method (e.g. username/password, or social login) with a non-admin user, you'll get direct access to your application or continue with the authentication flow as you have it specified for your tenant.

When you log in using an admin user (a member of the group "Admin", as we defined it on the Action), you'll be prompted to either register or validate your account with webauthn. The screen may look something like this:

![Auth0 MFA Validation Step](https://images.ctfassets.net/23aumh6u8s0i/7duWHgEkhhz2e7rLgLJV1X/d174ce044c7a8011f660cd83be1cc815/mfa_validate.png)

## Conclusion

Auth0 Actions provides a versatile and powerful toolkit to revolutionize your organization's MFA implementation. By harnessing the flexibility of Actions, you can create personalized, risk-based, and context-aware MFA workflows that enhance security without compromising user experience.

The ability to tailor MFA requirements based on user roles, risk assessments, and specific applications empowers you to implement a layered security approach. This means that you can enforce stricter MFA for high-risk scenarios, such as administrative access or sensitive data handling while offering a streamlined experience for regular users.

As you explore the possibilities of Auth0 Actions, remember that Customization is key. By experimenting with different workflows and conditions, you can fine-tune your MFA implementation to perfectly align with your organization's unique security requirements and user expectations.

Thanks for reading!

Using Actions to Customize Your MFA Factors

How to add Fine-Grained Authorization (FGA) to a Spring Boot API using the OpenFGA Spring Boot starter.

OpenFGA for Spring Boot Applications

Let’s take an overview of the new Session Management API, which allows you to manage your user sessions.

User session management allows developers to implement features ranging from controlling session concurrency to monitoring and terminating sessions. In this article, we will discuss the Session Management API, which allows you to manage user sessions in applications that integrate with Auth0.

## The Need for Managing User Sessions

When a user logs in to your application using Auth0, at least two sessions are initiated:

- The *Local Session* (*Application Session*). This session exists on your application's side. It typically uses cookies or similar mechanisms to store information like the user's login status, preferences, or any other data relevant to your application's functionality. Its primary role is to indicate to your application whether the user is currently logged in and authorized to access specific resources or features.
- The *Authorization Server Session* (*Auth0 Session*). This session is managed by Auth0's servers. It's typically stored in a cookie within the *auth0.com* domain or a custom domain associated with your Auth0 tenant. It's primarily used by Auth0 to facilitate features like Single Sign-On (SSO) and to determine if a user needs to re-authenticate when accessing other applications within the same Auth0 tenant.

> In case the user authenticates using a third-party Identity provider, such as Google, Facebook, GitHub, or others, you have a third session, the *3d party IdP session*, which tracks the interactions between the user and that Identity provider. See [this document](https://auth0.com/docs/manage-users/sessions/session-layers) for more info.

Your application's sessions are entirely in your hands, although Auth0 SDKs can help you with session creation. Auth0's session management is under Auth0's control. However, thanks to the new [Session Management API](https://auth0.com/docs/manage-users/sessions/manage-user-sessions-with-auth0-management-api), you can now manage Auth0 sessions from your application as well. The ability to manage authenticated user sessions in Auth0 can meet a few needs, such as:

- You can allow users to list their active sessions and close them by remotely logging out.
- You can allow an administrator to list all the user sessions and possibly force any of them to log out for security reasons.
- You can limit the number of concurrent user sessions.

Let's explore how you can use this new API.

## Set Up Access to the Session Management API

To use the Session Management API, you need the [Enterprise plan](https://auth0.com/pricing). If you don't have this plan but want to test the API, you can create a new tenant and get a free trial period.

You can use the Session Management API as you do with all the [Management API](https://auth0.com/docs/api/management/v2): basically, you need to enable your client application, [get an access token](https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens), and call the API endpoints.

### Enable your client

As a first step, you need to enable your client application to use the required scopes to use the Session Management API. In particular:

- The scope `read:sessions` enables your client to list sessions and get details about them.
- The scope `delete:sessions` allows your client to close a session, i.e., logging a user out.

To enable a client to these scopes, go to your [Auth0 dashboard](https://manage.auth0.com/) and select the application you want to enable. Make sure this is a [Machine to Machine application](https://auth0.com/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps). Select the APIs tab on the application page and then toggle the *Authorized* switch button corresponding to the Auth0 Management API, as shown in the following picture:

![Auth0 Management API authorization](https://images.ctfassets.net/23aumh6u8s0i/2Lo0IwblYRUHaYSZumG0KV/5ba4a67cf84835252167fac11102c2c4/auth0-management-api-authorization.png)

Then, expand the Auth0 Management API section and filter the permissions list using the `session` keyword. You should get the `read:sessions` and `delete:sessions` items. Check them as shown in the following picture:

![Auth0 Management API session scopes](https://images.ctfassets.net/23aumh6u8s0i/6hTwgUYPtXviFLa5BlZtph/7167f08b695580ac2aac827a9e0a809f/auth0-management-api-session-scopes.png)

Don't forget to click the *Update* button to save your changes.

### Get an access token

Now, your application must request an access token to call the Management API. Depending on your specific scenario, you can get an access token in different ways. For example, in a test scenario you can [get it manually](https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-testing#get-access-tokens-manually) from the Auth0 dashboard or you can use cURL, while in a production scenario, your application must request an access code programmatically.

For demonstration purposes, let's see how you can request an access token via cURL:

```bash
curl --request POST \
  --url https://YOUR_AUTH0_DOMAIN/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"https://YOUR_AUTH0_DOMAIN/api/v2/","grant_type":"client_credentials"}'
```

Replace the placeholders `YOUR_AUTH0_DOMAIN`, `YOUR_CLIENT_ID`, and `YOUR_CLIENT_SECRET` with the respective values from your client configuration.

This request generates a response as the following:

```bash
{ "access_token":"eyJhbGci...",
  "scope":"read:sessions delete:sessions",
  "expires_in":86400,
  "token_type":"Bearer"
}
```

You will use the value of the `access_token` property to demonstrate that you are authorized to call the Management API.

### Call the API

Now that you have the access token, you can call the API endpoints by passing it in the `Authorization` header, as shown in the following cURL request:

```bash
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/AUTH0_API_ENDPOINT' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json'
```

Replace the placeholders `YOUR_AUTH0_DOMAIN`, `YOUR_ACCESS_TOKEN`, and `AUTH0_API_ENDPOINT` with the respective values.

## Managing the User Sessions

Once we have enabled the client and obtained the access token, let's see how to actually use the Session Management API.

Let's start by listing the active sessions of a specific user. You can use the `/api/v2/users/{userId}/sessions` endpoint as shown in the following example:

```bash
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/sessions' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

In this example, you send a GET request to the endpoint by specifying your Auth0 domain, the user ID, and the access token. As a response, you will get a JSON object like the following:

```bash
{
  "sessions": [{
    "id": "2Lw8dT76wJpOl924",
    "user_id": "auth0|8374f7459j7493u84335",
    "created_at": "2024-05-10T12:04:22.3452",
    "updated_at": "2024-05-10T12:04:22.3452",
    "authenticated_at": "2024-05-21T11:29:12.4251",
    "authentication": { "methods":[
      {
        "name": "pwd",
        "timestamp": "2024-05-21T11:29:12.4251"
      }
    ]},
    "idle_expires_at": "2024-05-21T12:29:12.4251",
    "expires_at": "2024-05-21T18:29:12.4251",
    "device": {
      "initial_ip": "142.250.184.206",
      "last_ip": "142.250.184.206",
      "user_agent": "Mozilla/5.0...",
      "initial_asn": "8612",
      "last_asn": "8612"
    },
    "clients":[ {"client_id": "Hwo482a51heU632d34"} ]
    }
  ]
}
```

This is an object with the `sessions` array that lists the user's active sessions. Each session is represented by an object with some properties: the session ID (`id`), the user ID (`user_id`), the time stamp of their authentication (`authenticated_at`), the authentication method (`authentication`), the device on which the session is active (`device`), the application client used by the user (`clients`), etc.

In the example above, only one session is returned for that user.

If you have a session ID, you can access the data about that session by using the `/api/v2/sessions/{id}` endpoint. You can get a session ID from the `sid` claim of the ID or [Logout token](https://auth0.com/docs/authenticate/login/logout/back-channel-logout#tokens-in-oidc-back-channel-logout-communications). The following example shows how to get the session details given its ID:

```bash
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/sessions/2Lw8dT76wJpOl924' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

You will receive a JSON object representing that single session, as shown in the following:

```bash
{
  "id": "2Lw8dT76wJpOl924",
  "user_id": "auth0|8374f7459j7493u84335",
  "created_at": "2024-05-10T12:04:22.3452",
  "updated_at": "2024-05-10T12:04:22.3452",
  "authenticated_at": "2024-05-21T11:29:12.4251",
  "authentication": { "methods":[
    {
      "name": "pwd",
      "timestamp": "2024-05-21T11:29:12.4251"
    }
  ]},
  "idle_expires_at": "2024-05-21T12:29:12.4251",
  "expires_at": "2024-05-21T18:29:12.4251",
  "device": {
    "initial_ip": "142.250.184.206",
    "last_ip": "142.250.184.206",
    "user_agent": "Mozilla/5.0...",
    "initial_asn": "8612",
    "last_asn": "8612"
  },
  "clients":[ {"client_id": "Hwo482a51heU632d34"} ]
}
```

## Forcing Session Termination

In addition to getting information about the user sessions, you can also terminate them if your application has the `delete:sessions` scope enabled. You can call both endpoints `/api/v2/users/{userId}/sessions` and  `/api/v2/sessions/{id}` using the `DELETE` method. For example, the following cURL command terminates a specific user session:

```bash
curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/sessions/2Lw8dT76wJpOl924' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

The following command deletes all the sessions of a specific user:

```bash
curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/sessions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Session termination does not automatically log a user out of the application. As mentioned earlier, multiple sessions are involved in an application, and logout must be handled properly. Read [this article to get an idea of logout complexity](https://auth0.com/blog/the-not-so-easy-art-of-logging-out/).

In particular, session termination events are connected to the [OpenID Connect Back-Channel Logout](https://auth0.com/docs/authenticate/login/logout/back-channel-logout) mechanism. Therefore, to trigger application logout through the Session Management API, your application must be configured to use the `session-revoked` initiator. Read [this document](https://auth0.com/docs/authenticate/login/logout/back-channel-logout/oidc-back-channel-logout-initiators#configure-oidc-back-channel-logout-initiators) to learn how to configure your application to use the `session-revoked` initiator.

## Sessions and Refresh Tokens

Session termination forces the user logout. However, if an application requests a refresh token at login time, this refresh token is still available to the application even after the user session terminates.

This may be an intended or unintended situation, depending on the application's specific requirements. For example, consider an application that needs to call an API on a scheduled basis. It needs a refresh token to ensure an access token even if the user does not have an active session. On the other hand, your application can use a refresh token only to renew an access token with a limited lifetime, but you do not want the refresh token to survive the user session.

In the first case, terminating a user session will work as shown so far. You don't need to take an extra step to revoke the refresh token.

In the second case, the session termination is not enough. You also need a way to invalidate the current refresh token. For this purpose, you can use a few endpoints to help you manage refresh tokens.

> To enable your client application to manage refresh tokens, you have to add the `read:refresh_tokens` and `delete:refresh_tokens` scopes to the Management API configuration in the Auth0 dashboard.

The following command shows how to list all the refresh tokens associated with a given user:

```bash
curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/refresh-tokens' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

You get a JSON object containing the list of the refresh tokens with all the details, as in the following example:

```bash
{
  "refresh_tokens": [{
    "id": "6srfsU4dh510",
    "user_id": "auth0|8374f7459j7493u84335",
    "client_id": "Hwo482a51heU632d34",
    "created_at": "2024-05-10T12:04:22.3452",
    "updated_at": "2024-05-10T12:04:22.3452",
    "idle_expires_at": "2024-05-21T12:29:12.4251",
    "expires_at": "2024-06-21T18:29:12.4251",
    "session_id": "2Lw8dT76wJpOl924",
    "rotating": true,
    "resource_servers": [{ audience: "http://myapi.com", scopes:"read:users"}] 
  }]
}
```

To delete this specific refresh token, you can call the `/api/v2/refresh-tokens/{tokenId}` endpoint as in the following example:

```bash
curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/refresh-tokens/6srfsU4dh510' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Notice how you specify the ID of the refresh token to delete.

If you want to delete all the refresh tokens associated to a user, you can use the following command:

```bash
curl --request DELETE \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/users/auth0%7C8374f7459j7493u84335/refresh-tokens' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

> Consider that refresh token revocation through the `DELETE` command on the endpoints shown above runs asynchronously. This means that refresh tokens are not immediately revoked when the command finishes running.

## Summary

This article has given you an overview of Auth0's Session Management API with some examples of endpoint invocation via cURL. We started with activating the client application and getting the access token, then moved on to getting a user's session list and terminating a specific session.

You then learned about the relationship between sessions and refresh tokens and how to revoke refresh tokens associated with a user.

Now that you have a basic understanding of how to use the Session Management API, you can build a better security experience for your users.


"us"