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

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

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

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

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

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

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

Juan Cruz Martinez

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:

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

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

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?

Explore how tools like Auth0 Organizations, OPA, and Okta FGA can streamline your authorization strategy for secure, scalable SaaS development.

When building a multi-tenant SaaS application, selecting the right authorization model is critical to ensure the security and scalability of your system. Authorization is not only about managing user access but also about ensuring that tenants remain isolated, protected, and—where necessary—able to collaborate. The right model for your SaaS depends on the complexity of your application, the relationships between users and resources, and how dynamic or flexible your access control needs to be. This guide provides a deeper dive into how **RBAC**, **ABAC**, and **ReBAC** can be implemented for multi-tenancy, focusing on what needs to be handled in code versus what can be centralized in a system. We’ll also touch on popular services like [Auth0 Organizations](https://auth0.com/organizations), [OPA](https://www.openpolicyagent.org/), and [Okta FGA](https://fga.dev/) to streamline your implementation.

## Role-Based Access Control (RBAC)

**Role-Based Access Control (RBAC)** is often the first choice for SaaS applications that have clear roles with distinct access privileges and is often the most familiar option among developers. It’s a straightforward model where users are assigned roles (e.g., admin, editor, viewer), and those roles come with specific permissions. In a multi-tenant environment, RBAC needs some enhancements to ensure roles are properly scoped to each tenant. This way, the users' permissions are restricted to their organization.

In a multi-tenant setup, RBAC handles tenant isolation primarily by scoping roles to individual tenants. This means that roles like “admin” or “viewer” are not globally applicable across the system but are assigned on a per-tenant basis. For instance, a user might be an “admin” in “Tenant A” but only a “viewer” in “Tenant B”.

To enforce this isolation, your application will need to ensure that roles are checked **within the tenant context** before allowing access to resources.

At the **code level**, this means ensuring that the application always verifies which tenant the user is operating under when making role-based decisions. For example, when a user tries to access a resource, the system should confirm whether their “admin” role applies to that specific tenant’s resources, not to another tenant’s resources.

> Notice that when using RBAC for authorization, a user under a certain role will get access to all the resources for that tenant. Other authorization models provide ways to scope the privileges of a user to specific resources within the tenant, and we’ll cover them later in the article.

There are simpler approaches to implementing RBAC into your application; for example, when using Auth0 for authentication, Auth0 offers an **Organizations** feature, which simplifies authentication and role assignments in multi-tenant environments. Auth0 Organizations allows you to easily manage users across multiple tenants (or organizations), where each user can be assigned roles specific to the organization they belong to. By using Auth0’s built-in support for multi-tenancy, you can delegate much of the tenant-specific role management to the identity provider, reducing the amount of tenant-scoped logic that needs to be hardcoded into your app.

### Example use cases for RBAC:

- **HR Management Platform**: In an HR platform used by multiple companies, each company (tenant) has its own set of roles, such as "HR Admin" and "Employee." When an HR Admin from Company A logs in, their permissions are limited to the records of Company A, while an HR Admin from Company B has access only to their company’s records.
- **AI-Powered Customer Support Tool**: A SaaS platform for AI-powered customer support allows companies to manage their support teams. Each team has a role structure, where the "Team Lead" has access to configure the AI responses, and the "Support Agent" can only see suggestions.

## Attribute-Based Access Control (ABAC)

ABAC allows you to define access control policies based on various attributes related to the user, resource, or environment. Unlike RBAC, which assigns static roles, ABAC dynamically evaluates attributes such as the user’s department, resource sensitivity, or even contextual factors like time and location. This makes ABAC more flexible for scenarios where access decisions depend on dynamic conditions.

In multi-tenant SaaS applications, ABAC can handle tenant isolation by including the tenant ID as an attribute in access control decisions. For instance, you can create policies that grant access to users based on their `tenantId`, `role`, and `department`. This allows for more granular control over what users from each tenant can access and when.

At the **code level**, the application needs to collect the relevant attributes (e.g., `tenantId`, `userRole`, `resourceSensitivity`) and pass them to the authorization engine for evaluation. The actual logic for determining whether access is allowed is centralized in the policy engine, reducing the need for complex, tenant-specific logic in your app.

There are some caveats, though; while ABAC allows for dynamic evaluation of the information, the relationships and structure of the information are hardcoded throughout the application, and if your attributes change, it may require code changes throughout the application. This is because the relationships between a user, its role, tenant, etc, are not inferred by the policy engine, but rather specified during authorization checks. For an inferred and more fine-grained approach, there’s a different authorization model which I will cover next.

For **system-level implementation**, ABAC policies can be managed using tools like **Open Policy Agent (OPA)** or a custom policy engine. These tools evaluate attributes dynamically, ensuring that access is granted only if all conditions are met. For multi-tenancy, this would include ensuring that users are only accessing resources within their tenant.
`

### Example use cases for ABAC:

- **AI-Driven Healthcare SaaS**: A hospital management system uses ABAC to grant access to patient records based on a doctor’s role, department, and the patient’s condition. Additionally, access is restricted to working hours.
- **AI-Powered Marketing Platform**: Marketing managers can access reports based on their role, the campaign they are working on, and the region of the campaign. ABAC policies check the region, `campaignType`, and `role` attributes to ensure the user is accessing data for their tenant’s campaigns only.

## **Relationship-Based Access Control (ReBAC)**

**Relationship-Based Access Control (ReBAC)** is ideal for SaaS applications where access control is based on complex relationships between users, resources, and organizations. Instead of simply granting permissions based on roles or attributes, ReBAC models relationships (e.g., "is the owner of," "can edit") and uses these to make access decisions. This is particularly useful for collaborative SaaS platforms where permissions are based on how users interact with resources.

> If your SaaS application handles user-generated content, you’ll likely benefit from a ReBAC model)

In multi-tenant ReBAC implementations, tenant isolation is enforced by defining relationships within and across tenants. For example, a user might "own" a resource within one tenant, and another user might have "edit" permissions for that resource based on their relationship. Unlike RBAC, which assigns roles based on predefined hierarchies, ReBAC focuses on how entities (users, resources, tenants) are related.

At the **code level**, your application doesn’t need to hard-code tenant checks. Instead, all access control decisions are based on querying the relationship graph, which models how users and resources are linked. This reduces complexity, as the app doesn’t need to maintain tenant-specific logic.

For **system-level implementation**, **OktaFGA** (or **OpenFGA**, based on Google Zanzibar’s model) provides a powerful platform for managing ReBAC at scale. OktaFGA stores and manages relationships in a graph database and allows your application to query these relationships in real time. You can model tenant-specific relationships and even handle cross-tenant scenarios, such as allowing external collaborators limited access to certain resources.

### Example use cases for ReBAC:

- **AI-Enhanced Document Collaboration Platform: In this multi-tenant SaaS, users can create, share, and edit documents within their tenant. ReBAC models relationships like "owner," "editor," and "viewer" for each document.**
- **AI-Powered Learning Management System**: A university (tenant) uses the platform to manage courses and student access. Students are "enrolled" in courses, and professors "teach" those courses. ReBAC models these relationships, ensuring that only enrolled students can access course materials. If a student transfers to a new university (tenant), their access is automatically updated based on their new relationships within the system.

## Summary

When it comes to building a multi-tenant SaaS application, your choice of authorization model determines how much of the access control logic is handled by your code versus the authorization system and how wide or fine grained the access control is over the resources of the tenants.

- **RBAC** requires tenant-specific role checks in your code, but tools like **Auth0 Organizations** can offload much of this complexity by managing roles and tenants externally.
- **ABAC** offers fine-grained, context-aware access control, where the system dynamically evaluates policies based on attributes like `tenantId` and `role`. Tools like **Open Policy Agent (OPA)** can centralize these decisions, reducing the need for custom code.
- **ReBAC** excels in scenarios with complex, dynamic relationships. Solutions like **OktaFGA** allow you to manage relationships at scale without embedding tenant-specific logic in your app. Instead, the relationship engine handles access control based on real-time relationships between users and resources.

By leveraging these models and tools, you can build a secure, scalable, and maintainable multi-tenant SaaS platform that fits your unique authorization needs.

Thanks for reading!

How to Choose the Right Authorization Model for Your Multi-Tenant SaaS Application

Kapil Patil

Sr. Partner Solutions Technical Architect

Discover how combining AWS Lambda Authorizers with Auth0 FGA can strengthen your API security. This approach ensures precise, scalable access management across your applications with minimal overhead.

Streamlining API Security with AWS Lambda Authorizers and Auth0 FGA

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

How to add Fine-Grained Authorization (FGA) to a Spring Boot API using the OpenFGA Spring Boot starter.

OpenFGA for Spring Boot Applications

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. 

Getting Unlimited Scalability with Auth0 Fine Grained Authorization

Limited early access is available for production usage; learn how you can apply!

In 2021, [we introduced you](https://auth0.com/blog/auth0-fine-grained-authorization-developer-community-preview-release/) to the Developer Preview of our new SaaS solution, Auth0 Fine-Grained Authorization (FGA). We had one goal —to simplify and streamline your experience with authorization-at-scale. Today, we're excited to bring you even closer to the future of authorization as Auth0 FGA launches into a Limited Early Access Program. A select group of customers now have the chance to integrate and use the product in their real-world production environments. 

## So, What Is Auth0 FGA?

[Auth0 FGA](https://fga.dev) enables developers to design authorization models, from coarse-grained to fine-grained, in a way that’s centralized, flexible, fast, scalable and easy to use. 

Auth0 FGA supports granting access at any level of granularity. You can use it to implement role-based access with complex hierarchies or atomic object-level access in any system. This makes it easy to enable collaboration between users, going far beyond typical role-based access control (RBAC). It also supports building custom roles into any system, empowering your customers to define how to manage access. Auditing capabilities in Auth0 FGA provide fundamental building blocks for security and compliance teams. The more we’ve spoken to customers about it, the more we’ve learned just how many use cases it can solve.

Auth0 FGA is a single place for you to define your authorization model, store your authorization data and make your authorization decisions — across all your apps and products.

Centralizing your authorization logic and decisions into a single service that has the flexibility to handle use cases across your different products gives you distinct advantages:

* **Simplify security auditing:** Implement explicit authorization rules that are easier to audit by internal and external parties.
* **Lower costs:** Standardize authorization across all of your applications, making it easier for developers to focus on building new products and features without worrying about building and maintaining authorization into each app. 
* **Deliver faster:** Ship new products and features faster with an extensible authorization model that scales with your business.
* **Enhance security logging:** Generate logs for all operations out-of-the-box, both reads and writes.
* **Empower your users: **Allow users to take control of granting access to their data directly in your application.
* **…All in a way that’s fast and reliable at scale:** A centralized service dedicated to fine-grained authorization should scale with you as your business and products grow. Since Auth0 FGA specializes in authorization and nothing else, it can be particularly optimized for access control patterns and use cases, improving the latency and reliability of your authorization approach.

## The Path to General Availability

Since we launched the product as a Developer Preview, we have onboarded several customers in a private beta release. These customers are now using Auth0 FGA for their production applications. During this period, we completed all the internal processes required to ship a product in early access with the quality Okta customers expect from a feature, reliability, security, and compliance perspective.

During this period, we've meticulously fine-tuned all aspects necessary for a top-notch product that meets the high standards Okta customers anticipate. This includes feature enhancement, reliability improvements, security, and compliance reviews.

We've also been busy enhancing Auth0 FGA with a host of features:

* We open sourced [OpenFGA](https://openfga.dev/), Auth0 FGA’s core, and donated it to the Cloud Native Computing Foundation.
* We added support for [inviting multiple stakeholders](https://docs.fga.dev/intro/dashboard#manage-collaborators) to collaborate on a single Auth0 FGA model.
* We added initial support for ABAC-like authorization with [Contextual Tuples](https://docs.fga.dev/modeling/basics/contextual-time-based-authorization).
* We implemented APIs that allow [subscribing to all changes](https://docs.fga.dev/api/service#/Relationship%20Tuples/ReadChanges) in an Auth0 FGA store or retrieving [all resources that a user can access](https://docs.fga.dev/integration/perform-list-objects).
* We've [enhanced](https://docs.fga.dev/modeling/migrating-schema-1-1) our Authorization Model Language, making it more intuitive to read and write.
* We added a [Command Line Interface](https://github.com/openfga/cli) tool to simplify how to manage Auth0 FGA.
* We shipped a SDK for [.NET](https://www.nuget.org/packages/OpenFga.Sdk) and [Python](https://pypi.org/project/openfga-sdk/)

## Applying for Auth0 FGA Limited Early Access Program (EAP)

The Auth0 FGA EAP is designed to enable customers to implement authorization in their production applications while helping Okta validate the solution. We are very confident in the product we build, but our standards for the products we ship as Generally Available are very high.

Given that when integrating with Auth0 FGA, you’ll call our APIs very frequently, minimal latency is important. To minimize latency, your application's services need to run as close as possible to the Auth0 FGA services. For that reason, we are initially accepting customers that are deploying their applications in the same data centers as our Early Access deployments. Auth0 FGA is currently available on the AWS cloud in the US, and it will be deployed to more regions and clouds in the future.

We believe Auth0 FGA is the future of authorization that will enable businesses of all sizes to manage authorization at scale, without the complexity, and we’re excited to bring it closer to the hands of our customers with this milestone. 

If you are interested in participating in the Limited Early Access Program, please **reach out to your account manager**, or contact the Auth0 FGA team in our [Discord channel](https://discord.gg/8naAwJfWN6).

Streamline Your Authorization Workflow with Auth0 FGA

Learn which is the right authorization model for your application based on your use case.

Authorization is the process of verifying access to specific resources. In modern systems, using modern security workflows, an application can control what a user is authorized to do; this process is known as access control. 

In this post, you'll learn about access control and why you'll probably want to use an access control model to provide the structure and rules for deciding who can access what.  

Let's think of an example application like an *expense report management system* to walk you through the different access control models. In these types of systems, you want some users to be able to approve the expense reports submitted by other users. 

You start working on an [MVP](https://en.wikipedia.org/wiki/Minimum_viable_product) for this project and want to iterate as the product evolves and grows. You decide to build it in Ruby On Rails because you are proficient in it. You have built your brand new expense app and are proud of it. It has all the features anyone needs: the ability to create a new expense report, update and delete reports, list and approve, and so on. **Now it's time to restrict who can do what, i.e., to build your authorization system.**

## First Step: Authentication 

You don't want just anyone to access your app and create expense reports or see the existing reports. You need to restrict access to your app to users who are authorized. Who are those users? Well, these are the users that your app recognizes as being authenticated.

If a user provides valid credentials (i.e., is authenticated), then they are authorized to access your app.

Often people [confuse the terms authentication and authorization](https://auth0.com/docs/get-started/identity-fundamentals/authentication-and-authorization), and the main reason is that **authentication is usually the first step in the authorization.** 

> Authentication is the process of verifying someone is who they say they are, and authorization is the process of verifying what they can and cannot access.

Only in very simple use cases is authentication enough to authorize users to use an application. For example, in your expense report app, using just authentication as the criteria for authorizing users leads to potential problems: any authenticated user can create, list, and approve reports. Presumably, this is different from what you want.

So how can you make sure only *some* users can perform operations on your reports? 🤔

## Using Roles

Your users can submit reports, but at this point, you might need a group of users in charge of approving them. It might be a case of defining an "expense approver" role. 

When you are defining your authorization model, and you realize you can **group your users based on their shared responsibilities, you are referring to [Role-Based Access Control (RBAC)](https://auth0.com/docs/manage-users/access-control/rbac).** This model offers a simple, manageable approach to access management that allows your app to determine what a user can or cannot do based on their specific responsibility, i.e., their role.

In Auth0, a [role](https://auth0.com/docs/manage-users/access-control/rbac#roles) is defined as a collection of operations that can be executed on a resource. In this case, you want to create an "expense approver" role to perform the *approve* operation on *expense reports*, which fulfills your current use case. Great! 🙌

At this point, your users can submit reports, and expense approvers can approve them. Although you haven't defined which users can see which reports, meaning **any user could see the report of another user.** 😩 

## Using Permissions

Roles have limitations in access control implementation; the more your application grows, the more complex it is to maintain the list of possible roles. Using RBAC alone can lead to role explosion, meaning you can end up having hundreds of roles to manage. So you decide to also implement permissions. 

> [A permission is a declaration of an action that can be executed on a resource](https://auth0.com/blog/permissions-privileges-and-scopes/#What-Are-Permissions). Permissions defined for an API in Auth0 can be used as part of the access control mechanism used by your application.  

Using permissions allows your application logic to no longer rely solely on roles for access control. Permissions allow you to define more granular access control, and Auth0 also allows you to add permissions to a role as a handy way to assign them to users en masse. 

In this case, you want permission that allows users to read expense reports only if they are expense approvers or the creators of such reports. To implement permissions, you need to add some logic in your application to define which reports a user can see. Let's break this down into two groups: the expense approvers and the rest of the users.  

What you want to achieve is that expense approvers can see all expense reports while the rest of the users can only see their own reports. For the expense approver use case, you can add the permission *read expense report*, say, to their role and define in your application logic that this implies all expense approvers can see all expense reports. So far, so good. The expense approver role still suffices for the use case 🙌.

For the rest of the users to see only their reports, they require the *read expense report* permission. Because they do not have the "expense approver" role, then your application logic can prevent them from reading any expense report except their own. The use of roles in conjunction with permissions allows your application to tell which report(s) the user can read and which they can't.

You could have a method that verifies if the user has the role of expense approver; otherwise, check against your relational database if the user is the submitter of the expense report. In ruby-like syntax, it would translate to something along the lines of: 

```ruby
def can_read_expense_report(user)

  return true if user.expense_approver?

  expenses = db.fetch(
    "SELECT expenses.id, users.user_id
     FROM expenses WHERE id = %
     JOIN users WHERE users.user_id = expenses.submitter_id")

  authorize!(user, :read, :expenses)
end
```

Another option is for you to use an external gem, like [CanCanCan](https://github.com/CanCanCommunity/cancancan) or [pundit](https://github.com/varvet/pundit). Implementation details are completely up to you and your application.    

At this point, each user can see the reports they have submitted, and there is an expense approver role that can see all reports and approve them. You show your application to your stakeholders, and they decide that now **expense approvers can only approve expenses of their direct reports** 😧

You take a deep breath 🧘 and start thinking this through...

## Using Attributes for Access Control

Let's assume that in your system, you know the direct reports of your users because your user entity has a `manager_id` attribute. 

**When you define an authorization system that evaluates attributes (or characteristics), you are using [Attribute-Based Access Control (ABAC)](https://www.okta.com/blog/2020/09/attribute-based-access-control-abac/).** The purpose of ABAC is to protect objects from unauthorized users and actions — those that don't have "approved" characteristics as defined by an organization's security policies.  

In your case, your security policy will be as follows: 

> If user A is the manager of user B, then user A can approve an expense report from user B

Then, in your application code, you have to define the method that executes this policy. Let's say you have this information available in your relational database, and you can run a query to get the expenses of a user and, if they are the manager of the submitter user, approve the expense. A way to do this in *ruby-like (more like pseudo-code)* syntax, similar to what you did with your implementation of permissions, would be:

```ruby
def approve_expense(user)
  expense = db.fetch(
    "SELECT expenses.*, users.manager_id as submitter_manager_id
     FROM expenses WHERE id = %
     JOIN users WHERE users.user_id = expenses.submitter_id")

  authorize!(user, :approve, :expense)
end
```

The code above is similar to the one you wrote when implementing permissions. The key difference is that you are basing your `approve_expense` method and policy on the attributes of an object, in this case, the user. As you see, ABAC, RBAC, and permissions can all be used together. 💡

The `approve_expense` method works pretty great with your application 🥳 so you think of ways to optimize it and make it scalable. In a small organization with only one level of management, your authorization system works well, but when you take it to a bigger organization with multiple levels of management, you realize your solution can cause performance and maintenance issues. 🤔

The above code is **embedding authorization logic in your application code**, making it difficult to understand how authorization is implemented in the system without looking at the source code.

Also, if there are any **changes in your authorization policy, it will require you to change your application code.**

Lastly, every time you need to approve or verify if a user can read an expense report, you are hitting your operational databases, adding more load to those databases and therefore **adding latency to your requests.** 

You see, there is a clear relationship between the expense approver, the submitter, and the expense report; the attribute of being a manager works but adds complexity you don't need, so you decide to take a step back and re-think your implementation.

## I Need to Grant Access Based on Relationships

You were on the right track when you modeled your authorization system based on the user's attributes and the object you're trying to access. But that solution didn't work so well when management changed their mind and the application needed to grow 🙄 So now you decide that instead of using attributes, **it makes more sense to work based on the user's relationships with each other and the expense report too**. And the good news is that there is an authorization model out there that can help you do just that!

**[Relationship-Based Access Control (ReBAC)](https://docs.fga.dev/intro/authorization-and-auth0-fga#what-is-relationship-based-access-control-rebac) allows you to express rules based on relations that users have with objects and that objects have with other objects, providing a more expressive authorization model that can describe very complex contexts.** An example of where you find this authorization model is a social media app, where users can control who has access to their profile or information based on their relationship with other users. 

ReBAC is an example of a model that will typically offer you the most flexibility; models with a high degree of flexibility are often referred to using the term [Fine-Graned Authorization (FGA)](https://docs.fga.dev/intro/authorization-and-auth0-fga#what-is-fine-grained-authorization-fga). At scale, a system could have millions of objects, users, and relations with a high change rate, meaning that objects are regularly added, and access permissions are constantly being updated. An example is Google Drive, where you can grant access to documents or folders and where access can be granted to users individually or as a group. Access regularly changes as new documents are created and shared with specific users, whether inside the same company or without.

A Fine-Grained Authorization model sounds exactly like what you need for your use case 🤩. But wait. Surely something like this will be complex to build, right? Well, yes, it is. However, the good news is that we've already done it for you! [Auth0 FGA](https://auth0.com/developers/lab/fine-grained-authorization) provides an easy solution and offers a way to define your authorization model and relationships between a user and a report using something like the following:

```python
type report
  relations
    define approver: can_manage from submitter
    define submitter: [user]
type user
  relations
    define can_manage: manager or can_manage from manager
    define manager: [user]
```

With this model, you are stating the `manager` relationship between users and that the manager of the submitter is the only one who can approve a report by using the `can_manage` relation.

If you want to check if a user is a manager of another user in the management hierarchy, you could use the [Auth0 FGA Check API](https://docs.fga.dev/api/service#/Relationship%20Queries/Check). In Ruby, it'd look as follows: 


```ruby
require "uri"
require "json"
require "net/http"

FGA_API_URL="YOUR_FGA_API_URL"
FGA_BEARER_TOKEN="YOUR_BEARER_TOKEN"
FGA_STORE_ID="YOUR_STORE_ID"

url = URI("#{FGA_API_URL}/stores/#{FGA_STORE_ID}/check")

http = Net::HTTP.new(url.host, url.port);
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer #{FGA_BEARER_TOKEN}"
request["content-type"] = "application/json"
request.body = JSON.dump({
  "tuple_key": {
    "user": "user:alex",
    "relation": "can_manage",
    "object": "user:sam"
  }
})

response = http.request(request)
puts response.read_body

# Response: {"allowed":true,"resolution":""}
```

<div class= "alert alert-info alert-icon">
  <i class="icon-budicon-487"></i>
<strong>You can check out the <a href= "https://play.fga.dev/sandbox/?store=expenses">Auth0 FGA Playground</a> for more info about this concrete example as well as other useful examples for you to learn more about FGA.</strong>
</div>

Some advantages of using a third-party service like Auth0 FGA to manage your authorization system is that you remove the authorization logic from your application code and make sure all your policies are in one place, making it easier to maintain. You also minimize the latency in your requests because Auth0 FGA is optimized for reliability and low latency at a high scale, and in your specific case, you'll reduce latency even more because you won't be hitting your database every time you want to check if a user can approve an expense report. 

When you finish implementing your authorization model, you go back to your stakeholders and show them your progress; they are thrilled! 🥳 They like the progress you've made. Still, now they decided they want to have a [git-like](https://git-scm.com/) system where you can have multiple versions of the same report, branches, and teams, and you take another deep breath 🧘 and proceed to explain that this will move the initial deadline, and so the drama continues...

<include src="SmallBannerCTA" text="Want to take your Authorization to the next level? → " linkText="fga.dev" link="https://a0.to/oktafga_blog" imgLink="https://cdn.auth0.com/website/blog/banners/fga.png" imgAlt="Okta FGA Logo" />

## Conclusion 

Authorization models give you the structure and rules for deciding who can access what in your application. Depending on your use case, one model can be better than another. Or you may end up using multiple models to serve your needs, depending on the complexity of your use case. 

You almost always want to have authentication in your system, but it's usually not enough for users to be authenticated to verify if they have access to a resource or not. A Role-Based Access Control (RBAC) model might be enough for simple applications, especially if you have a few roles. However, the more granularity you want in your access control model, you might consider using permissions and assigning them to users regardless of their roles. You might define the access control based on some of your user's attributes, for example, by implementing ABAC, or you can restrict access to resources based on your object relationships using ReBAC. Whatever your requirement is, Auth0 and Auth0 FGA offer you a solution that can be used to address your authorization needs at scale in a progressive manner.

What's the Right Authorization Model for My Application?

vincenzo-chianese

Vincenzo Chianese is an Italian Software Developer focused on Web APIs and User Interfaces. He has been working for the last years in API companies such as Apiary, Oracle, LunchBadger, Stoplight. Currently, he is working for Microsoft to help move Microsoft Graph forward and authored some open-source tools in the market (Prism, Express Gateway).

API Architect

Vincenzo Chianese

Learn how to overcome the limitations of your authorization system by switching to OpenFGA.

Supercharge Your Authorization System with FGA

Join us at KubeCon + CloudNativeCon Europe on April 17th, 2023, for the official launch of OpenFGA v1.0

We’ve been talking to hundreds of developers who consistently tell us that they want to change how authorization is implemented in their applications. Authorization logic is embedded in the code and implemented differently in each service. It’s not flexible enough to define complex policies or finer-grained authorization. They struggle with load at scale. The existing RBAC/ABAC solutions can’t handle this complexity. That’s why we built OpenFGA.

We are thrilled to announce the release of [OpenFGA](https://openfga.dev) v1.0, a modern, flexible authorization system inspired by [Google's Zanzibar](https://zanzibar.academy). OpenFGA, designed for reliability and low latency at scale, has been embraced by the developer community since its open-sourcing in June 2022. As a Cloud Native Computing Foundation (CNCF) Sandbox Project, OpenFGA is having a significant impact in the world of authorization.

## OpenFGA v1.0: A Host of Enhancements

OpenFGA v1.0 brings a wealth of improvements since it was open sourced, raising the bar for authorization systems and providing developers with the tools they need to create secure, scalable applications. Here's a rundown of the new features:

1. Enhanced Authorization Model Language: OpenFGA v1.0 offers a [significantly improved](https://openfga.dev/docs/modeling/migrating/migrating-schema-1-1) language for defining authorization models, making them easier to read and author.
2. ListObjects API: This [new API](https://openfga.dev/docs/interacting/relationship-queries#listobjects) lets you retrieve all resources that a user can access based on the defined authorization policies, greatly simplifying auditing and access controls.
3. Elevated Observability: OpenFGA v1.0 takes [observability to new heights](https://openfga.dev/docs/getting-started/setup-openfga/docker#telemetry) with Open Telemetry tracing, Prometheus metrics, and prof profiles, providing insights into your authorization system's performance.
4. Effortless Deployment: Deploying OpenFGA to Kubernetes has never been easier, thanks to [official Helm chart](https://artifacthub.io/packages/helm/openfga/openfga) support. Get your Kubernetes cluster provisioned with just one command.
5. Postgres Storage Adapter Performance Boost: OpenFGA v1.0's Postgres storage adapter is supercharged, ensuring rapid performance and seamless scalability.
6. New Python SDK: A brand-new [Python SDK](https://pypi.org/project/openfga-sdk/) makes it even more convenient for Python developers to integrate OpenFGA into their projects.
7. Batching support in SDKs: OpenFGA v1.0's enhanced SDKs support batching queries, providing greater efficiency when making authorization requests, available for [JavaScript](https://github.com/openfga/js-sdk#batch-check) and [.NET](https://github.com/openfga/dotnet-sdk), [Go](https://github.com/openfga/go-sdk) coming pretty soon!

## Experience OpenFGA v1.0 at KubeCon + CloudNativeCon Europe, April 17, 2023

Mark your calendars and join us at KubeCon + CloudNativeCon Europe for the official launch of OpenFGA v1.0. Be among the first to discover the future of authorization systems and learn how OpenFGA can transform your cloud deployments and bolster your application security.

You’ll be able to connect with the OpenFGA team in different ways:

* Find us at Kiosk #27 in the Project Pavilion in the afternoons.
* Join the [OpenFGA project meeting](https://kccnceu2023.sched.com/event/1JWSb) on April 18, 9:30 AM CST in Room D406, Congress Center
* Participate in the Cloud Native Authorization Birds of a Feather meeting on April 21st from 11 AM - 12:30 PM CST. You can register [here](https://kccnceu2023.sched.com/event/1KW9e).

## Join us!

An open-source project is only as good as its community, so we are extending a warm welcome to everyone who wants to get involved. 

The project already has more than 30 contributors from multiple companies, and it’s being deployed in production by many of them.

The community has contributed a [MySQL Storage Adapter](https://github.com/openfga/openfga/pull/210), SDKs for [ASP.NET Core](https://github.com/Hawxy/Fga.Net), [Elixir](https://github.com/msutkowski/fga-elixir-sdk),  [Kotlin](https://github.com/Ozee-io/fga-kotlin-sdk) and integrations with [Quarkus](https://github.com/quarkiverse/quarkus-zanzibar), [Open Policy Agent](https://github.com/thomasdarimont/custom-opa-openfga), [Keycloak](https://github.com/embesozzi/keycloak-openfga-workshop), [Kratos](https://github.com/tx7do/kratos-authz) and [SCIM](https://github.com/SUSE-Skyscraper/openfga-scim-bridge).

You can help by simply trying the product, providing feedback, and engaging with other OpenFGA users in [Discord](https://discord.gg/6xzMMuU8YR) / [Github Discussions](https://github.com/orgs/openfga/discussions), attending our [monthly meetings](https://github.com/openfga/community/blob/main/community-meetings.md), or [contributing](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md) to the project.

Find out more by checking out the Github repository [https://github.com/openfga/openfga](https://github.com/openfga/openfga), and learn how to use it in our [documentation](http://openfga.dev). Keep up to date with the latest news by following us on [Twitter](https://twitter.com/openfga).


Announcing OpenFGA v1.0: A New Milestone in Cloud Native Authorization Systems

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.

Andrea Chiarelli

Broken Object Level Authorization is the most critical API security vulnerability. Learn how Fine Grained Authorization (FGA) can help fix it.

According to [OWASP](https://owasp.org/), the worldwide web security community, Broken Object Level Authorization (BOLA) is the most critical vulnerability affecting APIs. What is this vulnerability? How can it be exploited? How can you prevent it in your API? Keep reading to find the answers to these questions.

## What Is OWASP API Security Top Ten?

One of the main goals of the OWASP community is to make developers and technologists aware of the risks their applications and systems are exposed to. With this in mind, the community publishes some documents that highlight what are the most common security risks.

The [OWASP Top Ten](https://owasp.org/www-project-top-ten/) document is the most popular one. It focuses on web development in general. But there is also a more specific document for APIs: the [API Security Top Ten](https://owasp.org/www-project-api-security/).

Both the 2019 and the [2023](https://owasp.org/www-project-api-security/announcements/2023/02/api-top10-2023rc.html) versions of the document report that [Broken Object Level Authorization](https://github.com/OWASP/API-Security/blob/master/2023/en/src/0xa1-broken-object-level-authorization.md) is the most critical security risk. It's incredible that after four years this security risk is still affecting APIs around the world! Is there a way to mitigate if not eliminate this vulnerability?

The answer to this question is positive: you can prevent  this vulnerability from affecting your API by designing a proper authorization system. But before you get to the solution, let's learn what Broken Object Level Authorization is.

## What Is Broken Object Level Authorization?

Authorization is the process of determining what a user has access to. This access control can be done in many different ways based on the business rules of the specific application.

In the API context, each request to a protected endpoint should be analyzed to determine if the client is authorized to access and perform the requested action. Typically, this check is done at the code level and is based on verifying that the client has the right permissions to access the resource (the object) exposed by the API endpoint.

The main problem in this case is to define what is the actual resource to protect.

In some scenarios, it's the API endpoint itself. Consider the `/profile` endpoint: it implicitly returns the profile data of the current user. The API may know who the current user is from the session storage or from the access token sent along with the request.

In other scenarios, the object to protect is the requested resource. Consider the endpoint `profile/42`, which returns the profile data of the user with ID 42. In this case, comparing the current user ID to the requested user ID may not be correct. Think of an administrator who should have access to the profile data of all the users. The authorization check should verify that the current user has permission to access the requested object.

Inaccurate permission checking in endpoints that use object IDs exposes the API to BOLA attacks. In fact, an attacker could manipulate the object ID to gain access to an object for which they have no permissions.

> In the past, the Broken Object Level Authorization (BOLA) vulnerability was called Insecure Direct Object Reference (IDOR). The name was changed because it suggested that the problem was with the ID, while in fact it's with the authorization check.

## An Example of BOLA Vulnerability

To understand how a Broken Object Level Authorization vulnerability can be exploited by an attacker, let's use a practical example.

Suppose your bank provides you with an app to manage your account. Being a curious developer, you take a look at how your app interacts with the server. You notice that it calls the endpoint `https://thebankwebsite.com/accounts/9876543` to get data about your own account whose number is 9876543.

You remember that one of your friends has the same bank as you. You also remember that you made a money transfer to him in the past, so you look for his account number in the messages he has sent you. You find out that his account number is 1029387. So, you take curl or another HTTP client and replay your HTTP request to the bank's server by changing the endpoint's URL: `https://thebankwebsite.com/accounts/1029387`.

Surprisingly, you get the data about your friend's account from the server! This means that the bank's API has a BOLA vulnerability. Their authorization check fails at the object access level.

You can imagine, for example, that the API implementation for that particular endpoint is as follows:

```javascript
const express = require('express');
const app = express();
const { auth, requiredScopes } = require('express-oauth2-jwt-bearer');

//This checks that the provided access token is valid
const validateAccessToken = auth({
  audience: '...yourApiIdentifier...',
  issuerBaseURL: `https://...yourDomain.../`,
});

//This checks that the provided access token grants reading permissions
const checkReadPermissions = requiredScopes('read:account');

app.get('/accounts/:accountNumber', 
        validateAccessToken, 
        checkReadPermissions,
        function(req, res) {
          res.json(getAccountData(req.params.accountNumber));
        }
);
```

This Node.js Express code snippet shows how a GET request on the `/accounts/:accountNumber` endpoint is handled. Note that the endpoint is protected by two middleware:

- `validateAccessToken`, which ensures that the client provides a valid access token.
- `checkReadPermissions`, which ensures that the access token contains the required `read:account` scope in order to allow the client to access the requested account.

Unfortunately, these checks are not sufficient to implement an accurate access to the account object. In fact, they will not prevent you from accessing your friend's account.

<include src="ebook-ads/WebSecurity" />

## How to Prevent BOLA Vulnerabilities

What measures can you take to prevent BOLA vulnerabilities?

A common suggestion is to avoid using easily recognizable object identifiers in your endpoint URL, such as the bank account number in the example above. This measure prevents the knowledge of the object ID from allowing an attacker to compose a specific HTTP request. For example, you could use a GUID in the URL to identify the bank account instead of the bank account number itself. GUIDs are randomly generated values and make them very difficult to guess.

This approach can mitigate the risk of BOLA attacks, but it doesn't solve the problem. If the attacker finds a way to determine the GUID associated with a bank account, this protection will be bypassed.

The real problem is not in the object ID but in the authorization mechanism. The access control of your API should not be limited to controlling access to the endpoint. It should verify that only authorized users can access **the object exposed by the endpoint**.

In the bank account example, this means that additional checks should be performed. For example, you can check that the current user is the owner of the account, as outlined below:

```javascript
// ...existing code...

app.get('/accounts/:accountNumber', 
        validateAccessToken, 
        checkReadPermissions,
        function(req, res) {
          const userId = req.auth.payload.sub;
          const account = getAccountData(req.params.accountNumber);
  
          if (account.userId == userId) {
            res.json(account);  
          } else {
            res.status(403).json("Permission denied."); 
          }
        }
);
```

This would solve the unauthorized access to the bank account described earlier. However, it might not cover other scenarios. For example, consider a bank account with multiple owners. Each owner could have different permissions on the account. Also consider a bank employee: they should be able to access the accounts of their branch customers. And perhaps a regional manager should be able to access the accounts of multiple branches.

As you can see, the authorization policy that your API should implement strictly depends on the specific business logic. This logic is mainly determined by the relationship between users and resources. When this relationship becomes complex, your API code run the risk of getting messed up.

## What Is Fine-Grained Authorization?

To handle complex authorization policies, you should use Fine Grained Authorization (FGA). FGA allows you to control access to resources by analyzing a context described by various attributes and relationships. By having access to a detailed context, you can more effectively control who can access what in your system.

You can design and implement FGA in a variety of ways, but the most common models are as follows:

- **Attribute-Based Access Control (ABAC)**. This authorization model allows you to make authorization decisions by evaluating attributes such as the user's role or age, the resource type or size or status, the action requested, the current date and time, and so on.
- **Policy-Based Access Control (PBAC)**. This authorization model allows you to make authorization decisions based on policies. It is very similar to ABAC. The main difference is that PBAC focuses more on logic while ABAC relies more on data.
- **Relationship-Based Access Control (ReBAC)**. This authorization model focuses on the relationship between users and resources. This also includes relationships between resources. ReBAC provides a more expressive and powerful authorization model that can describe very complex contexts.

Okta offers [Fine Grained Authorization](https://fga.dev) through two solutions based on the ReBAC model:

- [Auth0 FGA](https://dashboard.fga.dev/). This is an *authorization service* that centralizes your authorization logic and data. It allows you to define your authorization model, store your authorization data, and make your authorization decisions across all your applications. Read the [Auth0 FGA documentation](https://docs.fga.dev/intro/authorization-and-auth0-fga) to learn more.
- [OpenFGA](https://github.com/openfga). This is the Open Source project powering the Auth0 FGA service. You can install the [OpenFGA Server](https://github.com/openfga/openfga) and use its SDKs to integrate authorization into your applications.

## How FGA Solves BOLA Vulnerabilities

Auth0 FGA and OpenFGA allow you to fix Broken Object Level Authorization vulnerabilities in your APIs without messing up your code. Whether you use the hosted product or install the Open Source engine on your servers, FGA allows you to centralize the access control to the resources protected by your API.

You can do this in three steps:

1. **Define your authorization model**. In this step, you define the types of objects in your system and their possible relationships with each other. The authorization model is usually fairly static once written. Check out [this document to learn more about defining your authorization model](https://docs.fga.dev/modeling).
2. **Store your authorization data**. This step allows you to define the actual data and its relationships according to the authorization model you defined in the previous step. This represents the state of the system and will be changing as users interact with your application.
3. **Add authorization check to your API**. In the third step, you integrate authorization checks into your API and start leveraging the power of FGA.

### Define your authorization model

Going back to the bank account example, you can define your authorization model in Auth0 FGA by using its [configuration language](https://docs.fga.dev/modeling/configuration-language). The following code shows a minimal example of how your model could be written:

```yaml
model
  schema 1.1
type user
type branch
  relations
    define employee: [user]
type account
  relations
    define branch: [branch]
    define owner: [user]
    define can_create: employee from branch
    define can_view: owner or employee from branch
```

Notice that the last line in the model above defines the account owner and the employees of the branch where the account was opened as the legitimate viewers. This is the basis for avoiding the Broken Object Level Authorization problem.

Using the [Auth0 FGA Playground](https://play.fga.dev/), you can also get a visual representation of this model:

![The bank authorization model in the Auth0 FGA Playground](https://images.ctfassets.net/23aumh6u8s0i/3cklRF8G4IPBGWb07P4JsI/a75e9daf57459430a9c40f620aad7792/auth0-fga-bank-authorization-model.png)

> You can play with the model used in this article by [making your own copy](https://play.fga.dev/stores/create/?id=01GVMW810J23DEBPGT22MFE4M7).

### Store your authorization data

As the next step, you fill this model with actual data. You define your users and add a direct relationship to the objects in your model. You also define relationships between objects and other aspects that depend on your specific model. You provide data to the system using tuples. For example, the following tuples define some relationships related to the bank model presented earlier:

```json
[
  // User Mary is the owner of the account 12345
  {
    "user": "user:mary",
    "relation": "owner",
    "object": "account:12345"
  },
  // User John is an employee of the branch b1
  {
    "user": "user:john",
    "relation": "employee",
    "object": "branch:b1"
  },
  // Account 12345 was created in the branch b1
  {
    "user": "branch:b1",
    "relation": "branch",
    "object": "account:12345"
  }
]
```

To learn how [to populate your authorization model with data, read this document](https://docs.fga.dev/writing-data).

### Add authorization check to your API

Finally, you can add the authorization checks to your API using one of the [available SDKs](https://docs.fga.dev/integration/install-sdk). Referring back to the bank example, the Node.js Express code will perform its authorization checks as follows:

```javascript
const { OpenFgaApi } = require('@openfga/sdk');
const fgaClient = new OpenFgaApi({
  //...configuration...
});

// ...existing code...

app.get('/accounts/:accountNumber', 
        validateAccessToken, 
        checkReadPermissions,
        function(req, res) {
          const userId = req.auth.payload.sub;
          const account = getAccountData(req.params.accountNumber);
  
          const { allowed } = await fgaClient.check({
            tuple_key: {
              user: `user:${userId}`,
              relation: 'can_view',
              object: `account:${req.params.accountNumber}`,
            },
          });
  
          if (allowed) {
            res.json(account);  
          } else {
            res.status(403).json("Permission denied."); 
          }
        }
);
```

The authorization check is performed by `fgaClient.check()`, which passes the tuple to be verified to the FGA engine. The FGA engine uses the authorization model and the data you provided to determine if the current user is authorized to view the requested account. Since you have defined there who the legitimate viewers of this account are, your API is not BOLA vulnerable. In addition, your code is kept clean.

Read more about [integrating FGA into your API](https://docs.fga.dev/integration).

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## Summary

By the end of this article, you should have a clearer idea of what Broken Access Level Authorization is and how Fine Grained Authorization can help prevent it.

You have begun to explore what BOLA is and how it can be exploited with a practical example. You have seen that the root cause of this vulnerability is an inadequate authorization system. You learned about FGA and saw what Auth0 offers in this area.

Using the API example analyzed earlier, you learned how to integrate it with Auth0 FGA to overcome the BOLA vulnerability in three steps: define an authorization model, populate the model with data, and invoke the authorization check from the API.

In addition to avoiding BOLA vulnerabilities, Auth0 FGA provides a powerful authorization system to solve very complex scenarios effectively and efficiently. [Give it a try](https://fga.dev/).


How Fine Grained Authorization Solves the Most Critical API Security Risk

Fine grained authorization-at-scale, available for everyone

[A few months ago](https://auth0.com/blog/auth0-fine-grained-authorization-developer-community-preview-release/) we announced a Developer Preview of Auth0 Fine Grained Authorization (FGA), our upcoming SaaS product to solve authorization-at-scale for developers. Today we’re announcing [OpenFGA](https://openfga.dev/), the open-source engine that powers Auth0 FGA.

OpenFGA is a fast, flexible Fine-Grained Authorization System inspired by [Google's Zanzibar](https://research.google/pubs/pub48190/) paper, and has been designed for reliability and low latency at a high scale. It makes it easy for application developers to model their access control layer, and to add and integrate fine-grained authorization in a way that is consistent across all of their applications. It’s designed, built, and sponsored by Okta/Auth0.

## Why Is Fine-Grained Authorization Important?

Modern applications have evolved in a way that end-users now drive permission management. This makes fine-grained authorization an increasingly critical element in software. For example:

**Collaboration** and **Social** features are things users expect. These features range from the **‘Share’** button where users proactively grant specific permissions to a set of users for a specific resource, to **‘Request Access’** workflows that allow users to reactively grant access on demand. These features are useful both for business-related assets such as documents or project boards, as well as social sharing personal content like photo albums, social media posts, and even IoT devices.

**Security, compliance and privacy** are mandatory problems to solve for any software application from day one, and authorization is a big part of any solution. In fact, the top [2021 OWASP risk is broken access control.](https://owasp.org/Top10/)

Organizations like Airbnb and Carta have built Zanzibar-like systems to solve their authorization needs. We don’t think organizations should have to keep building the same authorization tools, again and again, so we set out to build one version that any developer can use. 

## How Does It Work?

As an example, we’ll use OpenFGA to model a simple expense management system. Imagine expense reports have the following requirements:

* Can be submitted by any employee.
* Can be approved by the submitter’s manager, or by the manager’s manager (or their manager, etc..).
* Can be viewed by the submitter, the approver, and anyone else that got the report shared with them.

To solve this problem in OpenFGA you would define the following authorization model:

```go
// There are reports in the system
type report
 relations
   // Reports have submitters (user who have submitted that report)
  define submitter as self
   // Reports have approvers (users who can approve reports)
   // A report's approvers are the managers of the submitter
   // of that report
  define approver as manager from submitter
   // Reports have viewers (user who can view that report)
   // The users who can view a report are the submitter,
   // the users who can approve it, anyone it has been shared directly with
  define viewer as self or submitter or approver

// There are employees in the system
type employee
 relations
   // Employees have managers, managers are those directly assigned
   // or anyone who's a manager of a manager
  define manager as self or manager from manager
```

The OpenFGA language uses `self` to indicate that the relationship can be assigned.

* Submitters and viewers of a report can be directly assigned.
* Direct managers of an employee can be directly assigned.

Definitions without `self` can not be assigned directly but can be inherited.

In addition to defining an authorization model, OpenFGA requires you to provide the actual data to instantiate these permissions. In this example, we’ll have 4 participants:

* Daniel, who is Sam’s manager
* Matt, who is Daniel’s manager
* Sam, who will submit an expense report
* Peter, who works in the same team as Sam. Sam wants to share the report with him.

You would provide this data by using the [OpenFGA’s Write API](http://openfga.dev/api/service/#/Tuples/Write) and a few “tuples”. 

Some of the tuples will define the direct reports. This data will probably be synchronized automatically from an HR system (e.g. Workday):

```json
{ 
    "user": "employee:daniel",  
    "relation": "manager", 
    "object": "employee:sam" 
}
```

```json
{ 
    "user": "employee:matt",  
    "relation": "manager", 
    "object": "employee:daniel" 
}
```

Whenever Sam submits an expense report (in this example, ‘sam-trip’), the following tuple should be created:

```json
{ 
    "user": "employee:sam",  
    "relation": "submitter", 
    "object": "report:sam-trip" 
}
```

When Sam later shares the report with Peter, the following tuple should be created:

```json
{ 
    "user": "employee:peter",  
    "relation": "viewer", 
    "object": "report:sam-trip" 
}
```

With the above information now in the system, we can now ask OpenFGA if a specific user has a specific relation with a particular object. We do that by using [OpenFGA’s Check API,](https://openfga.dev/api/service#/Tuples/Check) which will return true or false. For example, if we check:

```json
{ 
    "user": "employee:matt",  
    "relation": "approver", 
    "object": "report:sam-trip" 
}
```

OpenFGA will return **TRUE**, as Matt is the manager of Sam’s manager, and Sam is the submitter of the expense report.

You can also use the [‘Expand’ API](https://openfga.dev/api/service#/Relationship%20Queries/Expand) to understand why OpenFGA returns that result. The Auth0 FGA Playground provides a visualization of the results of calling that API:

![OpenFGA](https://images.ctfassets.net/23aumh6u8s0i/1eSifra3BxJLVtV6XtR4xv/58c1a82f8770c9a2555b9632dbc80507/OpenFGA.jpg)

It needs to answer “is `employee:matt` related to `report:sam-trip` as approver”. To do that, OpenFGA:

1. Expands the “approver” relationship for Sam’s report
2. Finds out that the approver needs to be Sam's manager (the report submitter’s manager), and finds out who the managers are <br>
    **a**. Daniel is Sam’s assigned manager, but Daniel is not the one we are looking for <br>
    **b**. Daniel's managers are also Sam's managers, so OpenFGA needs to expand them <br>
3. Expands the “manager” relationship for Daniel <br>
    **a**. Matt is Daniel's manager, which is what we were looking for! <br>
    **b**. Matt's managers would also be Sam's managers, but there's no manager defined for Matt <br>

To summarize, you need to:

* Define a domain-specific authorization model.
* Use the `Write()` API to add relationship tuples.
* Use the `Check()` API to check for permissions.
* Use the `Expand()` API in cases where you need a detailed understanding of the `Check()` results instead of a simple `TRUE` or `FALSE` response

## Why Open Source?

Both Auth0 and Okta maintain a large number of open source projects and use a myriad of open source products internally. This time we are going one step further than usual and open-sourcing a core Auth0 product. We’ll continue to offer [Auth0 FGA](https://fga.dev/) as a SaaS offering, but also strive to build the best open source implementation of a Zanzibar-style authorization system.

We’re doing this for several reasons:

* We believe there’s an opportunity to create a large ecosystem around a fine-grained authorization system, and that making our FGA offering open source will maximize the chances for this to happen. We expect OpenFGA integrations for authorization policies products like [OPA](https://www.openpolicyagent.org/), proxies like [Envoy](https://www.envoyproxy.io/), API gateways like [Kong](https://konghq.com/); identity providers ([Auth0](https://auth0.com/es), [Okta](https://www.okta.com/), [AzureAD](https://azure.microsoft.com/es-es/services/active-directory/)), SDKs for platforms and frameworks (Python, Java, [Spring](https://spring.io/), [Next.js](https://nextjs.org/)), etc. 
* We want to enable customers that require deploying in different cloud providers,  on-premise, in multiple regions, with FedRAMP compliance, or those that have a low tolerance to the risk of delegating authorization to a third party provider. From our experience with Auth0, we know those are difficult problems for a SaaS product.
* The industry will benefit by having a common way to manage Fine Grained Authorization. We believe Auth0/Okta is the company that can make this happen. It’s a leader in the Identity Access Management space, is trusted by thousands of customers, is cloud-agnostic, and has the financial capacity to invest in the product long-term.

## What Are We Open Sourcing?

We are open sourcing the engine that drives our SaaS product, and the SDKs that make it so easy to use. 

You can find all of these projects hosted in an [OpenFGA organization on Github.](https://github.com/openfga)

* [OpenFGA Server](https://github.com/openfga/openfga): the core FGA server which provides:
   * An expressive language to define your authorization model.
   * HTTP APIs for checking and granting permission, authoring models, query tuples.
   * A graph querying implementation inspired by Google Zanzibar
   * Pluggable storage adapters, with support for an in-memory database and PostgreSQL
   * OpenTelemetry tracing, metrics, and structured logging
* [Website and Docs](https://github.com/openfga/openfga.dev): The openfga.dev website, which includes our product documentation.
* [SDK Generator](https://github.com/openfga/sdk-generator): Tooling to generate SDKs based on OpenAPI definitions.
* [Go SDK](https://github.com/openfga/go-sdk), [.NET SDK](https://github.com/openfga/dotnet-sdk), [Javascript SDK](https://github.com/openfga/js-sdk): SDKs for different languages, with more to come soon!
* [Auth0’s FGA Playground](https://play.fga.dev/), which is not open source now but it will be in the following weeks.

## OpenFGA and the Cloud Native Computing Foundation

The Cloud Native Computing Foundation (CNCF) is an open-source software foundation that promotes the adoption of cloud-native computing. It hosts projects like Kubernetes, Envoy, and Open Policy Agent, along with a hundred others.

As we mentioned earlier, we believe there needs to be an open source version of a Zanzibar-inspired Fine Grained Authorization product. Creating such a product requires an initiative that early adopters can trust. To further accelerate this process, **we submitted OpenFGA to the Cloud Native Computing Foundation sandbox**. 

By joining the CNCF, the OpenFGA project will find a larger, vibrant community that will help this initiative to continue growing and attract more users and developers.

## Try It!

An open source project is only as good as its community, so we are extending a warm welcome to everyone that wants to get involved.

You can help by simply trying the product, providing feedback, and engaging with other OpenFGA users in [Discord](https://discord.gg/6xzMMuU8YR) / [Github Discussions](https://github.com/orgs/openfga/discussions), attending our bi-monthly office hours, or [contributing](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md) to the project. 

Find out more by visiting [openfga.dev](https://openfga.dev/), and learn how to use it in our [awesome documentation](http://openfga.dev/docs). Keep up to date with the latest news by following us on [Twitter](https://twitter.com/openfga).

Announcing OpenFGA - Auth0’s Open Source Fine Grained Authorization System

Damian Schenkelman

Damian was one of Auth0's earliest employees. He loves building products for developers and taking things from 0 to 1.
<br><br>
He played key roles in implementing product features and growing the engineering organization in the early stages, and later on defining Auth0's architecture for scale and creating new products. Today he helps shape Auth0's long term strategy and leads Auth0Lab, a small and amazing team doing research and development of forward-looking products.
<br><br>
He spends his spare time with family, and friends, exercising, and catching up on all things NBA.

VP R&D (Auth0Lab)

We are excited to announce the Developer Community Preview for Auth0 Fine Grained Authorization (FGA), our upcoming SaaS to solve authorization-at-scale for developers.

## What Is Fine Grained Authorization?

[Authentication is about who the user is. Authorization is about what they can do.](https://auth0.com/intro-to-iam/authentication-vs-authorization/)

Historically, software applications have, in general, handled [authorization](https://auth0.com/intro-to-iam/what-is-authorization/) in a coarse grained manner. A user has one or more roles in an application, which grants them permissions to perform certain actions across the application. This worked well for a while because users didn't create content in systems. As social and work collaboration applications become mainstream, a different kind of authorization became necessary: fine grained authorization.

An application implements fine grained authorization when it can determine a user's permission to perform actions on any object in the application, and users can create objects in the application and manage permissions to those objects.

This is "fine grained" because there is no lower limit to the granularity at which builders of the system can make authorization decisions. It is up to the builders of the system to determine how granular they want authorization to be, and up to the users of the system to determine who has specific permissions on objects.

## Why Is Fine Grained Authorization Important?

Fine grained authorization is increasingly becoming a critical element in software. For example:

*   **Collaboration and social** features are things users expect, such as the ‘Share’ button you see in so many applications. This applies to both business-related assets, such as documents and project boards, and personal assets like pictures and home IoT devices. Specifically sharing one of these objects with another user is a Fine Grained Authorization use case.
*   **Security, compliance, and privacy** are musts for any software application from day 1, and authorization is a big part of solving those concerns. In fact, the [TOP OWASP 2021 risk is broken access control](https://owasp.org/Top10/).

However, solving authorization in an application is not a trivial matter. We believe applications solve authorization correctly if their authorization solution has the following characteristics:

1.  **Reviewable:** It should be easy to determine "who can access what," essentially understand the rules used to enforce access control.
2.  **Easy to manage change:** Authorization related changes must be explicit and traceable. Change management control for authorization is important.
3.  **Auditable:** It should be possible to know what happened with regards to authorization, in essence "who tried to access what, and when?".
4.  **Reliable:** Authorization decisions are made as part of most flows/requests, so authorization components need to always be running and returning the expected results.
5.  **Fast:** Authorization decisions are made as part of most flows/requests, so they need to be fast. If authorization decisions are slow, then the end-user experience is slow as a whole.

Implementing all of the above is complex, even with expertise. So we looked at how we could solve authorization for our customers, and allow them to focus on their core business. This is what led us to create **Auth0 Fine Grained Authorization.**

## What Is Auth0 Fine Grained Authorization?

Auth0 Fine Grained Authorization (FGA) is a SaaS to solve **fine grained authorization at scale for developers**. It is inspired by [Google Zanzibar](http://zanzibar.academy), the [system Google uses to solve authorization](https://auth0.com/blog/auth0-introduces-zanzibar-academy/) across all their products, such as Google Drive, Youtube, Google Cloud, and others.

Auth0 FGA does not require you to be using Auth0 already. You can use Auth0 FGA with any identity provider: your own user database (e.g. MySQL, PostgreSQL), Auth0, Okta or anything else.

Auth0 FGA centralizes your authorization. It becomes your "authorization (micro)service" if you will. It's a single place for you to define your authorization model, store your authorization data and make your authorization decisions, across all your apps and products.

Centralizing your authorization logic and decisions into a single service that has the flexibility to handle use cases across your different products gives you distinct advantages:

*   **Simplify security auditing:** Explicit authorization rules are easier to audit by internal and external parties.
*   **Lower costs:** Standardizing how authorization is done across your company makes it easier for developers to switch teams.
*   **Deliver faster:** You’ll be able to ship features and products faster, as the system is easily extensible to new requirements.
*   **Security logging:** The Auth0 FGA service generates logs for all operations out-of-the-box, both reads and writes.
*   **Empower your users:** Allow users to take control of granting access to their data directly in your application.
*   **Fast and reliable at scale:** A centralized service dedicated to fine grained authorization should scale as your business and products grow. Since Auth0 FGA specializes in fine grained authorization and nothing else, it can be particularly optimized for access control patterns and use cases, improving the latency and reliability of your authorization approach.

<br>
Auth0 FGA supports granting access at an atomic object level in any system, easily enabling collaboration between users, going far beyond typical role-based access control (RBAC). It also supports building custom roles into any system, empowering your customers to define how to manage access. Auditing capabilities provide fundamental building blocks for security and compliance teams. The more we’ve spoken to customers about it, the more we’ve learned just how many use cases it can solve for.

![Auth0 FGA](https://images.ctfassets.net/23aumh6u8s0i/21LaMJQrrDSNHmIEP2oWhO/17fd5e2a825a937590557973d59678b3/Uploaded_from_Auth0_Fine_Grained_Authorization__Developer_Community_Preview_Release)

Organizations like [AirBNB](https://medium.com/airbnb-engineering/himeji-a-scalable-centralized-system-for-authorization-at-airbnb-341664924574) and [Carta](https://medium.com/building-carta/authz-cartas-highly-scalable-permissions-system-782a7f2c840f) have built [Zanzibar-like](https://zanzibar.academy/) systems to solve their authorization needs. We don’t think organizations should build the same authorization tooling, again and again, so we set out to build one version everyone can use. We developed Auth0 FGA as a service so you don't have to.

## How Do I Get Started?

To start using Auth0 FGA you need to do three things:

1.  Define your authorization model ([docs](https://docs.fga.dev/modeling))
2.  Write authorization data from your system to Auth0 FGA ([docs](https://docs.fga.dev/writing-data))
3.  Add authorization to your API by adding access control checks to your system ([docs](https://docs.fga.dev/integration))


<div class="alert alert-info alert-icon">
  <i class="icon-budicon-487"></i>
  <strong>Note:</strong><br> 
  <b>The Developer Community Preview is meant to help us learn how customers use the product. If you have feedback, reach out on our <a href="https://discord.gg/6jsgXhVBu6">Community Discord</a>.<br> 
</div>

From that point on, all authorization decisions are centralized and made by Auth0 FGA. You can think of it as your "authorization microservice."

![Auth0 FGA](https://images.ctfassets.net/23aumh6u8s0i/tROyM1vl5FzzqImS1xjNU/d6a4a8f07e6aca48aed81f4aafadd821/Uploaded_from_Auth0_Fine_Grained_Authorization__Developer_Community_Preview_Release)

### A brief example

Let's say you were to start from a Node.js API to manage projects. That API doesn't have authorization capabilities yet, but it does have authentication.

You have an endpoint that would return a particular project given its project ID. In that endpoint, you might have code like the one from the following snippet. The second line verifies the [JSON Web Token](https://jwt.io/) (JWT) sent as part of the request to perform [authentication](https://auth0.com/intro-to-iam/what-is-authentication/), using [express-jwt](https://www.npmjs.com/package/express-jwt).

```js
app.get('/project/:id',
    jwt({ secret: PUBLIC_KEY, algorithms: ['RS256'] }),
    // authorize access
    async function(req, res, next) {
        // your business logic
    }
);
```

Now we want to add [authorization](https://auth0.com/docs/authorization) so only users that can **read** a project can call this endpoint.

First, we would install and setup the Auth0 Fine Grained Authorization Node.js SDK. You would need to obtain some data from your Auth0 Fine Grained Authorization account, and follow [these steps](https://docs.fga.dev/integration/getting-your-api-keys) to get it.

```js
const { Auth0FgaApi } = require('@auth0/fga');

const auth0Fga = new Auth0FgaApi({
  environment: AUTH0_FGA_ENVIRONMENT,
  storeId: AUTH0_FGA_STORE_ID,
  clientId: AUTH0_FGA_CLIENT_ID,
  clientSecret: AUTH0_FGA_CLIENT_SECRET,
});

...

app.get('/project/:id',
    jwt({ secret: PUBLIC_KEY, algorithms: ['RS256'] }),
    function(req, res) {
        // your business logic
    }
);
```


You would then add a new middleware that calls Auth0 Fine Grained Authorization to perform authorization on every request, after authentication has taken place. You know who the user is (authentication), now you want to check what they can do (authorization):

```js
app.get('/project/:id',
    jwt({ secret: PUBLIC_KEY, algorithms: ['RS256'] }),
    async function(req, res, next) {
        try {
            const result = await auth0Fga.check({
              tuple_key: {
                user: req.user.sub,
                relation: 'read',
                object: `project:${req.params.id}`,
              },
            });

            if (!result || !result.allowed) {
                return res.status(403)
                	.send({ code: 'missing_permissions', message: `ForbiddenError: Not allowed to access object ${req.params.id}` });
            }

            next();
        }  catch (err) {
            // handle error
            return next(err);
        }
    },
    function(req, res) {
        // your business logic
    }
);
```

The key part of the new middleware is this one, where we call the Auth0 Fine Grained Authorization API:

```js
const result = await auth0Fga.check({
  tuple_key: {
    user: req.user.sub,
    relation: "read",
    object: `project:${req.params.id}`,
  },
});
```

We are conceptually asking the question **"can the {user} read project:{id}"?**:

*   The **user** identifier is obtained from the JWT [sub (subject) claim](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2), as the JWT validation middleware sets all claims for the JWT in the **req.user** object as properties. Whatever your existing authentication method is, you can easily integrate it with Auth0 FGA.
*   The **relation** is "read" because the endpoint is a **GET**, it allows the caller to "**read"** one project. For **PUT** or **PATCH** you would use **"write"**.
*   The **object** is made up of the object type (project) and the project ID. The **object** **ID** comes from the request parameters (the path). A full URL for the request might be GET {API\_URL}/projects/1234, so the **object** would be **project:1234**.

You can learn about **CHECK** requests in depth [here](https://docs.fga.dev/intro/auth0-fga-concepts#what-is-a-check-request).

The previous example is intentionally verbose to show you the inner workings of things. You can imagine having SDKs for any web framework, API Gateway, and even policy languages that easily allow you to configure authorization per endpoint. For example:

```js
app.get('/projects/:id',
    jwt({ secret: PUBLIC_KEY, algorithms: ['RS256'] }),
    authorize(req => ({
        user: req.user.sub,
        relation: 'read',
        object: `project:${req.params.id}`
    })),
    function(req, res) {
        // your business logic
    }
);
```

## What's in the Developer Community Preview?

The Auth0 FGA Developer Community Preview is completely free and includes the features below. This is a chance for you and your teams to try the product out, assess how you'd integrate it with your apps, and give us your feedback.


<div class="alert alert-info alert-icon">
  <i class="icon-budicon-487"></i>
  <strong>Note:</strong><br> 
  <b>The rate limits in the API are intentionally set low and there are no SLAs, as the Developer Community Preview is meant to help us learn how customers use the product. For additional inquires, please reach out on the <a href="https://discord.gg/6jsgXhVBu6">Community Discord</a>.<br> 
</div>

### Management dashboard

The management dashboard ([https://dashboard.fga.dev/](https://dashboard.fga.dev/)) allows you to create an account and a store. You can use the dashboard to define your authorization model, write authorization data, and perform authorization checks.

![Management dashboard](https://images.ctfassets.net/23aumh6u8s0i/3BFXmCWtMBx8Bqtrrj2sh0/91674dba44c3c779518b3421a2f16df1/02.jpg)

### Documentation

We have written extensive documentation ([https://docs.fga.dev/](https://docs.fga.dev/)) to help you learn the main concepts, get started, and explore advanced use cases.

![Documentation](https://images.ctfassets.net/23aumh6u8s0i/7wFQjqES9oqiEXTYOpshM1/aa3e08e49cdb20a80d6b24b9ca2639b0/01.jpg)

### HTTP API and SDKs

Auth0 FGA is a product built for developers. We’ve created an API for developers to integrate Auth0 FGA into their systems. Everything you can do with the dashboard you can also do with the API.

At launch, we are shipping with SDKs for [Javascript](https://github.com/auth0-lab/fga-js-sdk) and [Golang](https://github.com/auth0-lab/fga-go-sdk). If you'd like an SDK for another language let us know in [Discord](https://discord.gg/6jsgXhVBu6). We can easily generate it from our OpenAPI definitions.

![Auth0 FGA](https://images.ctfassets.net/23aumh6u8s0i/5Tdtrh6uySJPvMPsH2ms6/54517d4f5b1749909bce5f32c529a806/03.jpg)

## What's Next?

We are excited about the capabilities that Auth0 FGA will unlock for our customers. We want to make sure our roadmap items are driven by customer feedback and input. So if you’re interested in the product, please let us know your thoughts by joining our Auth0 Lab community [here](https://discord.gg/6jsgXhVBu6).

We are also looking forward to the future, especially the "better together" use cases that Auth0 Fine Grained Authorization will enable for both Auth0 and Okta customers.

We hope you'll join us on this journey and are eager to hear your thoughts on what we’ve built so far.

Take a look, try it out at [https://auth0.com/developers/lab/fine-grained-authorization](https://auth0.com/developers/lab/fine-grained-authorization), and let's learn together!

"fga"