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 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

andres

I’ve been at Auth0 since 2017. I’m currently working as a Product Manager for the Auth0 FGA and OpenFGA products. Previously, I worked in the teams that owned the Login and MFA flows. <br>
I spent my entire 20+ year career building tools for developers, wearing different hats. When I'm not doing that, I enjoy spending time with my family, singing in a choir, cooking, or trying new kinds of local cheese.

Product Manager

Andrés Aguiar

Now, you can deploy Auth0 FGA in several AWS regions with high availability and requests per second.

We are thrilled to announce that [Okta Fine Grained Authorization](https://fga.dev/) (FGA) is now available as an AWS private cloud deployment option.

Authorization is where Authentication was a decade ago. We aim to simplify Authorization for developers, just as we did with Authentication. In early March, we made significant progress toward this goal by [launching Okta Fine Grained Authorization](https://www.okta.com/blog/2024/03/setting-the-bar-for-authz-okta-fine-grained-authorization-is-now-generally-available/). Auth0 FGA is an authorization service that enables developers to implement centralized, flexible, scalable, and easy-to-use authorization.

Auth0 FGA has two deployment options: public cloud and private cloud. The public cloud option is a multi-tenant SaaS service available in three geographies: the United States, Europe, and Australia, offering a highly available multi-region deployment. The private cloud option, on the other hand, is tailored for enterprises seeking dedicated resources. Auth0 FGA Private Cloud [leverages the same architecture principles](https://auth0.com/blog/securing-auth0s-new-private-cloud-platform/) that have been battle-tested with Auth0 for over two years.

**Benefits of Running Auth0 FGA in Private Cloud**

* **Higher RPS**: Private cloud instances are optimized for high request-per-second (RPS) performance, scaling up to five times the average RPS based on your application’s needs. 
* **Data Residency and Compliance**: Deploy your Private Cloud environment in any AWS region to help meet specific data residency and compliance requirements. Initial regions include the US, Germany, Ireland, the UK, France, Japan, India, Singapore, Australia, and Brazil.
* **Reduced Latency**: Choose the AWS region closest to your application servers, which will significantly reduce latency for faster access control checks.
* **Multi-Geography Deployments:** Businesses can replicate the same authorization data across multiple regions worldwide, allowing them to maintain low-latency authorization services even for globally distributed applications. For example, a company can have the same data in the US, EU, and Australia, have their authorization data replicated across all regions, and have their applications routed to the closest region.
* **Automated, Hardened Release:** Benefit from automated weekly releases that are previously validated in Okta’s public cloud deployments.
* **Centralized Management:** Manage both private and public cloud instances seamlessly from the Auth0 FGA dashboard.

The availability of Auth0 FGA in Private Cloud on AWS marks another significant milestone in our vision of running Auth0 FGA across all major cloud providers and regions. Stay tuned for further updates, and [Contact Us](https://auth0.com/contact-us?place=header&type=button&text=contact%20sales) to learn more.

Auth0 Fine Grained Authorization is now Available in Private Cloud on AWS

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.

Principal Developer Advocate

Sam Bellen

In this post, we will focus on adding fine-grained authorization to your Next.js application using Auth0 FGA.

In this post, we will focus on adding fine-grained authorization (FGA) to your Next.js application. We will check for permissions whenever we request or update data. You'll use Auth0 FGA, a managed solution for making relationship-based access control (ReBAC) decisions. 

This tutorial will explain the steps needed to add a flexible, fine-grained authorization model to your Next.js application.

- Create an [Auth0 FGA account](https://dashboard.fga.dev)
- Create your first Auth0 FGA model
- Add the [Open FGA SDK](https://docs.fga.dev/integration/install-sdk) to your codebase, and configure it to use your Auth0 FGA account
- Check for permissions in your application
- Update the data Auth0 FGA can use to make decisions when making changes in our application.

## What You'll Be Building 

Together, we'll go through the codebase of a Google Drive-style application that lets users upload images, create folders, and share these images and folders with other users.

The focus of this blog post is not on how to upload files, so we're not going to spend time on this. We're going to have a look at how we can deal with sharing files and folders and make sure each user only sees the files and folders they own or the ones that have been shared with them.

The app is structured as follows:

- The application's pages come from `/src/app/folder/`, `/src/app/shared/`, and `/src/app/login/`.
- Components can be found in `/src/components/`.
- We use Server Actions to pass data to and from the frontend. These actions live in `/src/app/actions.ts`.
- There's a Data Access Layer in place to handle fetching and writing data to your Vercel KV store and to upload the files to `/upload/`. The code for the Data Access Layer can be found in `/src/data`.
- The code in `/src/store/` helps us communicate with the Vercel KV since you'll need to make multiple requests for certain actions.

All these elements together give us an architecture that looks like this:

![The demo application architecture](https://images.ctfassets.net/23aumh6u8s0i/1OYq4vAITTzTDJhvvFneJW/8ee89cf32dd2a03ba7a79329cb74b8b3/architecture-light.png)

To follow along, you can download the codebase [here](https://github.com/oktadev/fga-drive-example) or run the following command in your terminal.

```bash
git clone git@github.com:oktadev/fga-drive-example.git
```

The application relies on Auth0 and Vercel services. If you haven't already, create an account for them:

 - Auth0, Create a [free Auth0 account](https://auth0.com/signup).
 - Auth0 FGA uses the same Auth0 account.
 - Vercel KV, create a free Vercel account and a KV store through your [Vercel dashboard](https://vercel.com/dashboard).

## What Is Relationship-Based Access Control

One of the most commonly used approaches to authorization is [Role-Based Access Control (RBAC)](https://auth0.com/blog/what-is-rbac-and-how-to-implement-it-rails-api/#What-is-Role-Based-Access-Control--RBAC-), where a role contains a set of permissions and is assigned to each user. This is a simple way of determining what permissions a user has and what actions they should be able to perform within our application.

More complex applications often require a more flexible approach to authorization, where access can be granted on a user and resource level instead of a general resources type, as done with RBAC. Enter Relationship-Based Access Control or ReBAC. Don't let the one extra letter in the acronym fool you; it's a completely different approach to authorization.

Instead of checking a fixed set of permissions assigned to a user via roles, we're going to look at the relationship between a consumer (or group of consumers) and a resource (or group of resources) to determine if they should be able to access a specific resource(s) or perform an action on them. 

Because we're looking at the bigger picture and determining relationships between two entities, these relationships often don't need to be explicitly defined.

For example, if a user belongs to a group, it is enough to grant that group access, and all its members will automatically be granted access. The same is true for a group of resources. If a user has access to, for example, a folder, they should automatically get access to all files within that folder without explicitly defining these relationships. These are called indirect relationships as opposed to direct ones.

## What Is Auth0 FGA

[Auth0 FGA](https://fga.dev) is a managed solution by Okta that helps you deal with complex authorization decisions in your application. It uses the OpenFGA modeling language (DSL) and decision engine, designed by Okta and adopted by the Cloud Native Computing Foundation (CNCF).

If you prefer to set up your own instance of OpenFGA, follow the ["Setup OpenFGA"](https://openfga.dev/docs/getting-started/setup-openfga/overview) document.

Auth0 FGA provides a set of APIs that let you check for permissions or add more data to the decision engine whenever data changes in your application so the decisions can stay up to date.

The decision engine can check for existing relationships between users and objects, but a user should not always be seen as a literal application user. For example, when checking if a folder is the parent of a file, the parent folder is the user, `parent` is the relation, and the file is the object. Therefore, in this guide, I will often refer to the user in the context of an Auth0 FGA check as a consumer and the object as a resource.

## Create an Auth0 FGA Account

Good news! If you already have an Auth0 account, 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)

<div class="alert alert-info alert-icon">
  <i class="icon-budicon-487"></i>
  If this is the first time you log into the Auth0 FGA dashboard, you might be prompted to create a new store. This store will house your authorization model, together with all the data the engine needs to make authorization decisions. Go ahead and choose a name and create a new store.
</div>

## Create Your Authorization Model

Auth0 FGA uses an authorization model to determine all possible relationships it should consider when making a decision. You'll navigate to the Model Explorer page in our dashboard and add the following model to the model editor. Don't forget to hit save!

![The Auth0 FGA Dashboard model page](https://images.ctfassets.net/23aumh6u8s0i/4SVEzhIEkv6khWhSGmFhTj/c9b9a233ad6db70fba0836e59a55b983/fga-model.png)

<div class="alert alert-info alert-icon">
  <i class="icon-budicon-487"></i>
  Check out the [Auth0 FGA Playground](https://play.fga.dev) to play around with the model editor or see some example models for applications like Google Drive, GitHub, or Slack.
</div>

```bash
model
  schema 1.1

type user

type file
  relations
    define can_delete: owner or owner from parent
    define can_share: owner or owner from parent
    define can_view: viewer or owner or viewer from parent
    define can_write: owner or owner from parent
    define is_owned: owner
    define is_shared: can_view but not owner
    define owner: [user]
    define parent: [folder]
    define viewer: [user, user:*]

type folder
  relations
    define can_create_file: owner or owner from parent
    define can_create_folder: owner or owner from parent
    define can_share: owner or owner from parent
    define can_view: viewer or owner or viewer from parent
    define owner: [user]
    define parent: [folder]
    define viewer: [user, user:*] or owner or viewer from parent
```

When you look at this model, you'll notice you defined three types: `user`, `file`, and `folder`. You'll be able to assign relationships between these types. For example, a `user` can be an `owner` or `viewer` of a `file` or a `folder` can be a `parent` of a file (or folder, when nesting folders).

You have also defined some permissions related to actions that can be performed on your types, like `can_view` or `can_share` for the file resource type. It's sometimes more future-proof to create relations like this, so if you expand your model in the future, your application can continue to check for these, even if their definition changes. 

<div class="alert alert-info alert-icon">
  <i class="icon-budicon-487"></i>
More information about the Google Drive model can be found in [our documentation](https://docs.fga.dev/modeling/advanced/use-cases/gdrive ).
</div>

With your authorization model in place, Auth0 FGA has half of what it needs to make decisions. The other half is data on your actual relationships, such as which user owns which file or which folder is a parent of which file. You'll do this in our application code whenever you create a new file or folder or share one of them. But first, let's set up the OpenFGA SDK.


## Install the SDK

To install the OpenFGA Node.js SDK, you'll run the following command in your terminal.

```bash
npm install @openfga/sdk
```

<div class="alert alert-info alert-icon">
  <i class="icon-budicon-487"></i>
  You use the OpenFGA SDK to connect to your Auth0 FGA instance. Both use the same engine and API endpoints and are interchangeable at this point.
</div>

Once installed, you can create a new OpenFGA client in your codebase. You'll find the client in `/src/app/authorization.ts`, and it looks something like this:

```typescript
// [ 📄 /src/app/authorization.ts ]

const fgaClient = new OpenFgaClient({
  apiUrl: process.env.FGA_API_URL,
  storeId: process.env.FGA_STORE_ID,
  authorizationModelId: process.env.FGA_AUTHORIZATION_MODEL_ID,
  credentials: {
    method: CredentialsMethod.ClientCredentials,
    config: {
      apiTokenIssuer: process.env.FGA_API_TOKEN_ISSUER as string,
      apiAudience: process.env.FGA_API_AUDIENCE as string,
      clientId: process.env.FGA_CLIENT_ID as string,
      clientSecret: process.env.FGA_CLIENT_SECRET as string,
    },
  },
});
```

The client needs some details to connect to our Auth0 FGA tenant, which you can add to the `.env.local` file. You'll find these details on the settings page of your Auth0 FGA dashboard. If you haven't created a set of API credentials before, you can also do this on the settings page.

- `apiUrl`: The url to your Auth0 FGA in the form of `https://api.<region>1.fga.dev`
- `storeId`: Found in your Auth0 FGA Dashboard 
- `authorizationModelId`: Found in your Auth0 FGA Dashboard, this changes with each update to your model 
- `apiTokenIssuer`: This is currently always `auth.fga.dev` when using Auth0 FGA 
- `apiAudience`: The same as your `apiUrl` with a trailing slash `/`
- `clientId` & `clientSecret`: Can be found in your Auth0 FGA Dashboard

The SDK exposes a lot of helpful methods to help you interact with Open FGA, but for this example, you'll focus on these two:

- `fgaClient.check()` checks if there's a relationship between a consumer and a resource; for example, can a user view a certain file.
- `fgaClient.writeTuples()` can write new tuples containing data about specific relationships to our OpenFGA store. You'll use this whenever we create a new file, for example.

When you dive deep into the `/src/app/authorization.ts` file, you'll notice there are some helper methods, but in the end, most of these use one of the two functions above.


## Check For A Relationship

When your application requests data, adds more data, or changes existing data, you want to ensure that these actions are actually allowed. 

Next.js [recommends using a Data Access Layer (DAL)](https://nextjs.org/docs/app/building-your-application/authentication#authorization) to manage data being pulled from or written to your database or data store. This happens to be the ideal location to check if the current user is Authenticated and Authorized for each action. You can find the Data Access Layer in `/src/data`.

The OpenFGA exposes the [`check()`](https://www.npmjs.com/package/@openfga/sdk#check) and [`batchCheck()`](https://www.npmjs.com/package/@openfga/sdk#batch-check) methods to check for a relationship before we perform the actions above.

For example, when you request a file, you'll want to make sure that the current user is allowed to see it. Your authorization model defined a relation `can_view` that specified that either a user that has a `viewer` or `owner` relationship defined to the file or a user that is the owner of a parent folder of the file should be able to view the file. 

So let's check for the `can_view` relationship using the `check()` method. 

```typescript
// [ 📄 /src/data/files.ts ]

export async function getFileDTO(
  fileId: string,
): Promise<{ file?: StoredFile; error?: unknown }> {
  try {
    if (await !isAuthenticated()) {
      return { error: "Unauthorized" };
    }

    const userId = await getUserId();
    // 👇 Check for a "can_view" relation in Auth0 FGA
    const { allowed } = await fgaClient.check({
      user: `user:${userId}`,
      relation: "can_view",
      object: `file:${fileId}`,
    });
    // 👆

    if (!allowed) {
      return { error: "Forbidden" };
    }

    const file = await getFileFromStore(fileId);

    if (file) {
      return { file };
    }

    return { error: "No file found" };
  } catch (error) {
    return { error };
  }
}
```

Here, you're checking if a user has a `can_view` relationship to a specific file. The `check()` method will return an object containing the decision as an `allowed` property.

## Create a New Relationship Tuple

Whenever you add, update, or delete some of the data your application works with, you want to make sure your Auth0 FGA instance knows about these changes so it can continue to make accurate decisions. You do this by adding or deleting tuples from the Auth0 FGA Store.

Whenever a user adds a new file or folder, you'll notice we create 2 new tuples, e.g., `/src/data/files.ts` line `188`.

The first tuple defines the current user as the owner of the file or folder. The second tuple sets the parent folder as the parent of a new file or folder. For example

```typescript
// [ 📄 /src/data/files.ts ]

export async function uploadFileDTO(
  parent: string,
  file: File,
): Promise<{ files?: Array<StoredFile>; error?: unknown }> {
  try {
    //...
    await writeFile(filePath, fileBuffer);
    const files = await createFileInStore(fileId, parent, uploadedFile);

    if (files) {
      // 👇 write new tuples to Auth0 FGA
      await fgaClient.writeTuples([
        {
          user: `user:${userId}`,
          relation: "owner",
          object: `file:${fileId}`,
        },
        { 
          user: `folder:${parent}`,
          relation: "parent",
          object: `file:${fileId}`,
        },
      ]);
      // 👆
      return { files };
    }

    return { error: "No files uploaded" };
  } catch (error) {
    return { error };
  }
}
```

From this point onward, each check to make sure our user can view this file will return true.

Whenever a user decides to share a file or folder with another user, you also write a new tuple like: 

```typescript
// [ 📄 /src/data/files.ts ]

export async function shareFileDTO(
  file: string,
  email: string,
): Promise<{ file?: string; error?: unknown }> {
  try {
    ...

    try {
      // Check the Auth0 management API for a user with the given email address
      const { data } = await auth0ManagementClient.usersByEmail.getByEmail({
        email,
        fields: "user_id",
      });

      // No known user with the email address, return an error
      if (data.length === 0) {
        return { error: "A user with this email address does not exist." };
      }

      // 👇 Write a new tuple to Auth0 FGA
      await fgaClient.writeTuples([
        {
          user: `user:${data[0].user_id}`,
          relation: "viewer",
          object: `file:${file}`,
        },
      ]);
      // 👆

      return { file };
    } catch (error) {
      return { error };
    }
  } catch (error) {
    return { error };
  }
}
```

Once this tuple has been written to your store, a check for a relation `can_view` between the user with the passed `userId`, and this file will return true.

You can view and manage all created tuples on the tuple management page of your Auth0 FGA dashboard.

![The Auth0 FGA Dashboard tuples manager page](https://images.ctfassets.net/23aumh6u8s0i/2MiUxTxBwFkUZEGP4Ryld0/fea080ec24342ff12b81b2a11c2b0f31/fga-tuples.png)

## List Objects With A Certain Relationship

On the `/shared` page, you'd like to show all files shared with you. The OpenFGA SDK has a convenient method that can list all objects with a certain relation. In your case, you're interested in all files that have a relation of `is_shared` to your user.

You can call the `listObjects()` method to get a list of shared file IDs that you can then fetch from your data store.

```typescript
// [ 📄 /src/data/files.ts ]

export async function getAllSharedFilesDTO(): Promise<{
  files?: Array<ReadableStoredFile>;
  error?: unknown;
}> {
  try {
    ...
    // 👇 List all files with an "is_shared" relation
    const sharedFiles = await fgaClient.listObjects({
      user: `user:${userId}`,
      relation: "is_shared",
      type: "file",
    });
    // 👆 
    ...
  } catch (error) {
    console.error(error);
    return { error: "Something went wrong." };
  }
}
```

## Next Steps

You've successfully implemented fine-grained authorization into your Next.js application. You can check for relationships between resources and consumers and create new tuples that inform Auth0 FGA about new or changed relationships.

Next, you can play around with the authorization model and adapt it to your needs, look at [conditional relations](https://docs.fga.dev/modeling/basics/conditions), or even create [context-aware relations](https://docs.fga.dev/modeling/basics/contextual-time-based-authorization).

Fine-Grained Authorization in your Next.js application using Auth0 FGA

Auth0 FGA achieves unprecedented scalability, paving the way for global authorization systems.

We believe that [Auth0 Fine Grained Authorization](https://fga.dev) (FGA) will fundamentally change how applications are going to be built over the next decade. At Okta, we aim to solve authorization for both application builders and workforce IT administrators, and FGA is a key piece of that strategy.

Scalability is crucial when designing a global-scale authorization system. It must be capable of delivering the performance and capacity expected from top-tier cloud services, like modern distributed databases. An authorization system capable of supporting a global scale must:

- Be highly available,
- Scale to support the most visited websites in the world,
- Provide low latency, as every millisecond you spend in authorization will impact the application’s overall latency,
- Be able to store a very large amount of data.

This [Google Zanzibar](https://research.google/pubs/pub48190/) paper describes how Google achieves those goals. We built FGA with these goals in mind, and our early tests of the Auth0 FGA validated that it could handle anything our beta and early access customers could throw at it.

As FGA gained traction among customers, we realized that we needed to push FGA even further to prove out this scale. 

So, we decided to run a test with **1 million Requests per Second (RPS)** and **100 billion relationship tuples** to evaluate how the system behaves. 

## Auth0 FGA Primer : Model + Relationship Tuples

When implementing authorization using Auth0 FGA, you need to define an authorization model that describes the different entities in your system that are relevant when making authorization decisions and provide the data required to instantiate the model in the form of relationship tuples.

For example, in the model below, we define groups that can contain users, documents that can have an owner, and viewers that can point to specific users or all members of a specific group:

```yaml
type user
type group
  relations
   define member : [user]

type document
 relations

   define owner : [user]
   define viewer : [user, group#member]
```

Relationship tuples would look like:

| user                   | relation | object              |
| ---------------------- | -------- | ------------------- |
| user:anne              | member   | group:marketing     |
| user:peter             | owner    | document:sales-plan |
| group:marketing#member | viewer   | document:sales-plan |

FGA defines an API method called `Check()` that will let you ask the system if a user is related to an object in a specific way. 

For example, we can call `Check(user:anne, viewer, document:sales-plan)` and we’ll get `“{ allowed: true }”` as a result, given `anne` is a member of the `marketing` group, and their members are related to the `sales-plan` document as viewers.

If you want to learn more, check out how to model with Auth0 FGA [here](https://docs.fga.dev/modeling).

## Modeling Authorization

When using FGA, the performance characteristics of a specific implementation will depend on the authorization model and relationship tuples in the system. 

The flexibility of FGA means that customers with varying use cases, traffic, and business models are able to harness the full power of FGA. In initial implementations, we’ve seen that customers with a Business-to-Business (B2B) use case tend to have more complex models but with far fewer active users and less traffic. And we’ve seen that customers with a Business-to-Consumer (B2C) use case tend to have less complex requirements but with more data, active users, and traffic. We decided to target these B2C use cases for our performance testing since these are the businesses that are more likely to require a scale of 1 million RPS and 100 billion tuples.

We modeled a social network where users can post content and other users can interact with it. One example of this would be publishing a tweet and commenting on it. The model is described below:

```yaml
type user
  relations
  # Users can have followers, can block specific users, 
  # and can decide if they are visible to all users or just to their followers
  define _self: [user]
  define follower: [user]
  define blocked: [user]
  define visibility: [user:*, user#follower]
  define viewer: visibility but not blocked
  # User profiles can be viewed by the user itself or by the users who have access to their profile
  define can_view: _self or viewer

type content
  relations 
  # Content is owned by the user that published it
  define owner: [user]

  # The content can be visible for anyone or just their followers, for users that are not blocked, and by the owner itself
  define visibility: [user:*, user#follower]
  define viewer: visibility but not blocked from the owner
  define can_view: owner or viewer

type interaction
  relations
  # Content iterations (e.g., comments) have a creator and a content piece as their parent
  define creator: [user]
  define parent: [content]
  # interactions can be viewed if the user can view the creator's profile and the content itself or if they are the creator of the interaction
  define viewer: can_view from creator and can_view from parent
  define can_view: creator or viewer
```

After defining the model, we had to decide how to distribute the relationship tuples in the system. We decided to use a [Pareto distribution](https://en.wikipedia.org/wiki/Pareto_distribution) where:

- 20% of users are generating 80% of content, and 80% of users are generating 20% of content
- Similarly, 20% of users are doing 80% of the interaction, and 80% of users are doing 20% of the interaction

The tests focused on the `Check()` endpoint because this endpoint is the one that will be called more often and have the most impact on the customer's applications. We checked if a user is able to view specific content, a specific user profile, or a specific interaction (e.g., `Check(user:john, can_view, interaction:1)` ).

## Modeling User Activity

Another critical decision point on how to perform the test was how to model user activity.

FGA has a cache that is set to 10 seconds. If we decide that a very small set of users is going to be active, we’d be able to serve all the requests from the cache. That would make it very easy to misrepresent the test results, as serving everything from memory would only happen in very specific use cases and won’t take into consideration the execution paths that require database access. 

We decided to run the tests in three ways:

- Disabling the caches
- With a 50% cache ratio, which seems realistic based on what we observed as an average ratio across all of our customers.
- With a 75% cache ratio, assuming that for a specific customer, ratios can be higher.

## One Million RPS and Beyond

We were very happy with the results and achieved the outcome we hoped for with only minor tweaks to the product.

We allocated three weeks to complete it, and most of the time was spent on generating the dataset, importing them into the database, and making sure we could launch all the clients that called FGA API. 

We completed the test run in just two days without any significant adjustments in our code. 

The tests ran for over 10 minutes and got 1.05M RPS. The images below are from our DataDog dashboard when we ran the tests with 0% cache ratio:

![Request rate received in FGA performance test](https://images.ctfassets.net/23aumh6u8s0i/2aWUERQeZCzKOa7FZUHB3O/cbd911fbacf051c2683221b78e032ca2/fga-rps-performance.png)

![Latency in FGA performance test](https://images.ctfassets.net/23aumh6u8s0i/D14o99yPNCvvNpFlDMDk9/c11f56a116346ee36e0980b48157eed4/fga-latency-performance.png)

The metrics above show that 50% of the calls were completed in up to 11.9 ms, 95% were completed in less than 19.5 ms, and 99% of them were completed in less than 38.5 ms.

We incrementally increased the load while executing the test, and we saw the number of FGA instances increase linearly, maintaining the latency within the same range. We felt confident that we could go way beyond 1M RPS, but we had to stop somewhere 🙂.

When running the tests with caching, the latency decreased significantly, and the number of Auth0 FGA nodes running too:

<style>
  table {
    width: 100%;
    border-collapse: collapse;
    font-size: 15px;
  }
  table, td, th {
    border: 1px solid;
  }
  table th {
    background-color:#eeeee4;
  }
  td {
    padding: 5px;
    text-align: center;
  }
</style>

| Cache Ratio | RPS per Auth0 FGA Instance (ECS Fargate 16 vCPU 32GB) | P95 Latency |
| ----------- | ---------------------------------------------------- | ----------- |
| 0%          | 3,500                                                | 19.5 ms     |
| 50%         | 6,000                                                | 9.4 ms      |
| 75%         | 18,000                                               | 5 ms        |

## Auth0 FGA and You

We were thrilled to have tangible proof that FGA can support the global scale it was designed for. FGA provides a highly flexible, highly available, and scalable solution to implement authorization, supported by a company that is a trusted leader in the identity space.

You can try Auth0 FGA today by signing up for an evaluation account [here](https://fga.dev). If you want to use it in production, you can apply to our Limited Early Access Program by reaching out to your technical account manager or account executive. 

"auth0-fga"