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 and Python.  

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. 

Staff Developer Advocate

Carla Urrea Stabile

In this blog post you’ll learn about different API Gateways: Zuplo, Kong, and Apache APISIX, and how each one could work best for a service that uses Fine-Grained Authorization.

Using an API Gateway with Fine-Grained Authorization

rishav-mishra

Product Manager, Auth0

Rishav Mishra

Discover the new Auth0 Fine-Grained Authorization (FGA) Logging API. Programmatically retrieve a complete audit trail of authorization logs to debug access issues, monitor threats, and ensure compliance.

Auth0 FGA Logging API: A Complete Audit Trail for Authorization

andrea-chiarelli

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

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

Principal Developer Advocate

Andrea Chiarelli

Learn how to implement fine-grained, relationship-based authorization in an ASP.NET Core minimal API using Auth0 FGA.

Fine-Grained Authorization in ASP.NET Core with Auth0 FGA

Learn about the history of AI agents, the risks they introduce and how to prevent them with a focus on fine-grained access control.


AI Agents are autonomous systems capable of executing complex tasks, making API calls, and maybe even modifying a production database on your behalf. This evolution introduces a new security challenge and attack vector as these AI agents can introduce a level of unpredictability that some access control systems are not ready to handle.

In this blog post, you’ll learn about the history of AI agents, the risks they introduce and how to prevent them with a focus on fine-grained access control. 

## A Brief History of AI Agents

In the last few years, LLMs have evolved to become the mainstream place for questions, and more recently, they have been increasingly used to call APIs on the user’s behalf, delegate work to other models, etc.

We went from simple chatbots to multi-agent collaboration in a matter of a few years, and they all cover different capabilities: 

* **Chatbot**: Can handle written questions and return text and usually operates in a browser communicating through an API endpoint, everything happens within the application.  
* **Assistants**: Can interpret a request and invoke external tools and services to fulfill it.   
* **Agentic** **System**: Chains several tools in a plan it composed on the fly. They operate by communicating the LLM with multiple other services   
* **Multi**\-**Agentic** **System**: Negotiates tasks with other agents, they operate on an agent-to-agent basis. 

## Access-Control Models Under Stress

Security teams usually reach for Role-Based Access Control (RBAC), Attribute-Based Access Control (ABAC), Permission or Policy-Based Access Control (PBAC), or Relationship-Based Access Control (ReBAC). Each shines in well-structured enterprise software; each shows strain when pointed at AI systems.

* **RBAC** is familiar and easy to audit. Unfortunately, an agent’s “role” can change from moment to moment. A request that begins as read-only can evolve into a code-generation exercise that needs write rights. Constant role hopping either floods your logs or drives teams to grant one oversized role that covers every possible combination.

* **ABAC/PBAC** add context: user tier, branch, time of day, tenant ID. They work well when the agent runtime can surface reliable attributes. The catch is that modern LLM stacks often rely on ephemeral containers or serverless functions where ambient context vanishes with each invocation. Persisting trustworthy attributes across the chain demands extra engineering that many proof-of-concept projects skip.

* **ReBAC** models complex resource graphs elegantly, perfect for mapping “Alice may comment on Bob’s ticket if they share a project.”. When the agent makes dozens of micro-tool calls per prompt, those lookups must complete in tens of milliseconds or users will notice a lag so your ReBAC systems must be fast

<include src="SignupCTA" text="Start building now, " linkText="Sign Up to Auth0!" />

## How Authorization Mitigates Top AI Security Risks (OWASP LLM Top 10)

The [OWASP Top 10 for Large Language Model Applications 2025](https://genai.owasp.org/llm-top-10/) explains the most critical risks for AI software and how to mitigate them. Let’s dig into it with a focus on access control. 

**LLM01 Prompt Injection**  
Attackers craft prompts that overwrite system instructions and steer the model toward harmful outcomes. A way to mitigate it is by implementing Input validation, adversarial testing and prompt isolation. In this context, Fine-Grained Access Control could block any tool call that is not explicitly scoped on the agent's permissions, so even a successful injection cannot reach sensitive operations.

**LLM02 Sensitive Information Disclosure**  
Large models sometimes expose secrets from training data or leak confidential context provided at runtime. Some of the ways to mitigate this is by encrypting secrets, removing them from prompts and adding output filtering. Implementing least-privilege scopes is also a good way to mitigate, for example let’s say you want to get data from patient records, your agent would simply lack permission to perform the request, so disclosure stops at the policy level. 

**LLM03 Supply-Chain Compromise**  
It is very common to use third-party models for agent implementations, which could be poisoned or have plugins introducing backdoors and bias. A way to mitigate this is to sign every artifact, verify checksums, and keep a software bill of materials. Assign each external component its own low-privilege identity.

**LLM04 Data and Model Poisoning**  
Attackers could add malicious examples into training or retrieval stores to change the model behaviour. One good way to mitigate this is by running rigorous data provenance checks and trusted-source allow lists help. In the context of access control, attribute-based rules can mark unvetted data as “not-usable,” preventing the agent from loading it until reviewers clear it. 

**LLM05 Improper Output Handling**  
When you give a response, you need to make sure it is validated and sanitized before passing it downstream to the user. It is important to always treat model output as untrusted, apply sanitization, and replay the action through the same access-control filter a human request would face. 

**LLM06 Excessive Agency**  
This risk is the vulnerability that enables damaging actions to be performed in response to unexpected, ambiguous or manipulated outputs from an LLM, for example giving an agent broad autonomy could end in unintended deletions, commits and payments. A way to mitigate this is by starting with read-only scopes, requiring user approval and implementing authorization in downstream systems rather than relying on an LLM to decide if an action is allowed or not, for example by using fine-grained authorization.

**LLM07 System Prompt Leakage**  
This risk refers to when the system prompts or instructions used to steer the behavior of the model can also contain sensitive information that was not intended to be discovered. Internal instructions may reveal credentials or allowed APIs. Store prompts server-side, rotate them often and scrub sensitive content, you can also make sure that security controls are enforced independently from the LLM and as OWASP says, *“in cases where an agent is performing tasks, if those tasks require different levels of access, then multiple agents should be used, each configured with the least privileges needed to perform the desired tasks.”*

**LLM08 Vector and Embedding Weaknesses**  
Weaknesses in how vectors and embeddings are generated, stored, or retrieved can be exploited by malicious actions to inject harmful content, manipulate model outputs, or access sensitive information. A way to mitigate this is to implement fine-grained access controls and permission-aware vector and embedding stores, as well as data validation and source authentication. 

**LLM09 Misinformation**  
Misinformation occurs when LLMs produce false or misleading information that appears credible. This vulnerability can lead to security breaches, reputational damage, and legal liability. A way to mitigate with retrieval-augmented generation to retrieve verified information from trusted sources, fact-checking APIs, and human review for high-risk tasks. Access control adds a guardrail by, for example, demanding a second verified source before an important write or financial transaction proceeds. 

**LLM10 Unbounded Resource Consumption**  
Unlimited requests drain budgets or become denial-of-service vectors. To mitigate this risk, you can implement strong access controls, including role-based access control (RBAC) and the principle of least privilege, to limit unauthorized access to LLM model repositories and training environments. You could also implement watermarking to detect unauthorized use of the LLM output. 

## How Fine-Grained Authorization Controls AI Agents

1. **Least-Privilege Identities**  
   Give every agent or plugin its own low-privilege credentials and start each session in read-only mode. Grant extra verbs, such as *write invoice* or *delete file*, only after an explicit, audited elevation step.

2. **Policy Checks on Every Call and Result**  
   Route every tool invocation and any generated SQL, code, or HTTP request through an external authorization service. The LLM can propose an action, but the policy, not the model, decides whether it runs.

3. **Label and Quarantine Data Sources**  
   Tag incoming documents, datasets, and embeddings with trust levels like *unknown*, *partner*, or *verified*. Access rules block agents from training on or retrieving content until reviewers promote its label.

4. **Protect System Prompts and Internal Configs**  
    Store prompts on the server side, remove secrets, and rotate them often. Even if a prompt leaks it reveals little, because the agent’s credentials unlock only the narrow slice of resources it truly needs.

5. **Guardrails for Impact and Scale**  
    Require deterministic or human confirmation for payments, refunds, and code deploys, and apply per-identity rate limits and cost budgets. These measures blunt both hallucinated high-risk actions and runaway resource use.

## Conclusion

AI agents amplify productivity, but without the right access control rules, they also amplify risk. It’s important to treat every agent and plugin as its own low-privilege client, check every request with an external policy engine, and enforce strict boundaries around data and costly actions.

Learn more about how [Fine-Grained Authorization](https://fga.dev) works and how you can use it to [secure your AI Agents](https://a0.to/ai-content) for example by [securing a RAG application with Auth0 FGA.](https://auth0.com/ai/docs/intro/authorization-for-rag) 



Access Control in the Era of AI Agents 

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 Principal Developer Advocate at Okta. He is also an international speaker and a published author.

Deepu K Sasidharan

Learn how to implement fine-grained authorization in Java RAG systems using LangChain4j and Auth0 FGA to secure your AI applications.

Artificial Intelligence is evolving at a breathtaking speed. AI agents will soon become the standard for building applications, and they are going to be the new Web 2.0. With all that comes the critical need for robust security measures and checks. Retrieval-Augmented Generation (RAG) systems have become a cornerstone in building AI agents and applications. Agents that can access and utilize domain-specific knowledge are more accurate and more useful. However, as these systems become more prevalent, ensuring they only access and expose authorized information has become a critical challenge.

[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 Large Language Model (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) or Relationship-Based Access Control (ReBAC) shines as an Authorization solution for RAG.

## The Security Challenge in RAG Systems

RAG systems present some unique security challenges that traditional Role-Based Access Control (RBAC) systems struggle to address:

1. **Dynamic Context**: RAG systems need to make real-time decisions about which documents and tools can be used for context enhancement.
2. **Complex Relationships**: Documents often have intricate relationships with users, teams, and projects, forming a complex graph that simple role-based systems can't model effectively.
3. **Granular Control**: Different parts of documents may have different sensitivity levels requiring fine-grained control.
4. **Performance Requirements**: Authorization checks must be fast to maintain the AI system's responsiveness.

This is where FGA shines, it allows us to:

- Model complex relationships between users, groups, and documents
- Handle hierarchical and transitive permissions naturally
- Scale authorization rules efficiently

Let's look at some real-world scenarios where sensitive data could be at risk:

- A knowledge base assistant exposing confidential documents to employees
- A support AI revealing sensitive user information
- An AI assistant leaking proprietary information about a company
- A chatbot exposing private data to unauthorized users

## Why Auth0 FGA?

[Auth0 FGA](https://fga.dev/) is the SaaS version of [OpenFGA](https://openfga.dev/). OpenFGA is an open-source Fine-Grained Authorization system, created by Auth0, that allows you to manage access control in your applications. It's currently a CNCF Sandbox Project. OpenFGA is a powerful tool that allows you to define complex access control policies and enforce them in your application. It is a great choice for securing RAG applications as it solves most of the security challenges in RAG systems, including the ones mentioned above.

If you're new to RAG and access control, I recommend checking out this introductory 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"
/>

## Why Java and LangChain4j?

Java isn't far behind when it comes to building AI applications. It has a large developer community and a rich ecosystem of open-source frameworks, and enterprises are adopting these frameworks.

[LangChain4j](https://github.com/langchain4j/langchain4j) is one of the popular Java AI frameworks. It is a powerful open-source framework that provides capabilities similar to LangChain and LlamaIndex used in the Python/JS ecosystem. It is becoming the Spring Boot of the Java AI ecosystem. The framework offers a comprehensive set of features for building AI applications. Some of the key features include:

- Easy integration with major commercial and open-source LLMs
- Unified API for different model providers
- Tools like prompt templating, chat memory management, and function calls.
- High-level patterns, abstractions, and implementations for building Agents and RAG applications

## Building a Secure RAG System

LangChain4j makes it simple to get started with the "Easy RAG" feature while providing advanced capabilities for complex use cases. Hence, in this guide, we will look at a secure Java RAG system using LangChain4j and Auth0 FGA. We'll focus on Relationship-Based Access Control (ReBAC), which prevents unauthorized access to sensitive information while maintaining the flexibility and power of RAG systems.

### Prerequisites

> **This guide was created with the following tools and services**:
> 
> - [Java 21](https://adoptium.net/)
> - [Gradle 8.12](https://gradle.org/)
> - An FGA instance ([Create an Auth0 FGA store](https://dashboard.fga.dev) or self-hosted OpenFGA)
> - An [OpenAI API key](https://platform.openai.com) or a local [Ollama](https://ollama.com/) instance

### Setting up the project

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/langchain4j-java
```

The application uses Gradle as the build system and is structured as follows:

- `src/main/java/rag/RagApplication.java`: The main entry point of the application that defines the RAG pipeline.
- `src/main/java/rag/FGARetriever.java`: The FGA-aware retriever that retrieves documents from the vector store based on the user's permissions.
- `src/main/java/rag/FGAInit.java`: Script to create the FGA store and models.
- `src/main/resources/docs/*.md`: Sample markdown documents that will be used as context for the LLM. We have public and private documents for demonstration purposes.
- `build.gradle`: The Gradle build file that defines the dependencies and tasks.

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

### RAG pipeline

The RAG pipeline configures the underlying LLM and defines the retrievers for data. The pipeline is defined as follows:

```java
/** src/main/java/rag/RagApplication.java **/
final ChatLanguageModel CHAT_MODEL_OPENAI = OpenAiChatModel
               .builder()
               .apiKey(System.getProperty("OPENAI_API_KEY"))
               .modelName(GPT_4_O_MINI)
               .build();

var user = "user2";
// 1. Read and load documents from the assets folder
var documents = FileSystemDocumentLoader
                 .loadDocuments("src/main/resources/docs");
// 2. Create an in-memory vector store from the documents.
InMemoryEmbeddingStore<TextSegment> embeddingStore = new InMemoryEmbeddingStore<>();
EmbeddingStoreIngestor.ingest(documents, embeddingStore);
// 3. Create a base retriever
ContentRetriever baseRetriever = EmbeddingStoreContentRetriever.from(embeddingStore);
// 4. Create the FGA retriever that wraps the base retriever
ContentRetriever fgaRetriever = FGARetriever.create(
       baseRetriever,
       // FGA tuple to query for the user's permissions
       content -> new ClientBatchCheckItem()
               .user("user:" + user)
               .relation("viewer")
               ._object(
                 "doc:" +
                 content.textSegment().metadata()
                 .getString("file_name").split("\\.")[0]
               )
       );
// 5. Create an assistant with the FGA retriever
var assistant = AiServices.builder(Assistant.class)
       .chatLanguageModel(CHAT_MODEL_OPENAI)
       .chatMemory(MessageWindowChatMemory.withMaxMessages(10))
       .contentRetriever(fgaRetriever)
       .build();
// 6. Query the retrieval chain with a prompt
var query = "Show me forecast for ZEKO?";
var answer = assistant.chat(query);
```

> If you want to use Ollama running locally, uncomment the `CHAT_MODEL_OLLAMA` variable and comment out the `CHAT_MODEL_OPENAI` line. Be sure to update the base URL and model name to match your local Ollama instance.

Here is a visual representation of the RAG architecture

![LangChain4j RAG architecture](https://images.ctfassets.net/23aumh6u8s0i/1X37t9DnD6btkPzE6pwGOg/68a80ce358980bc6a2ac9e0f13c08fb1/image1.jpg)

### FGA retriever

The `FGARetriever` class implements `ContentRetriever` and filters documents based on the authorization model defined in the FGA store. 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 has already narrowed 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.

Here is the important part of the `FGARetriever` class simplified for readability:

```java
/** src/main/java/rag/FGARetriever.java **/
// Create a client to interact with the FGA store
new OpenFgaClient(new ClientConfiguration()
       .apiUrl(/*...*/)
       .storeId(/*...*/)
       // credentials only required if using Auth0 FGA,
       // comment out for local OpenFGA
       .credentials(/*...*/)
)

// Check permissions for the user and object
private Map<String, Boolean> checkPermissions(List<ClientBatchCheckItem> checks) {
   var options = //...
   var request = //...
   var response = fgaClient.batchCheck(request, options).get();

   Map<String, Boolean> permissionMap = new HashMap<>();
   for (var result : response.getResult()) {
       var checkKey = getCheckKey(result.getRequest());
       permissionMap.put(checkKey, result.isAllowed());
   }
   return permissionMap;
}

// retrieve the documents and filter them using checkPermissions function
public List<Content> retrieve(Query query) {
   // First, get relevant documents from the base retriever
   List<Content> relevantContent = baseRetriever.retrieve(query);

   // Create data structures to track checks and document mappings
   // var checks, documentToObject, seenChecks = ...

   // Process each document to build checks
   for (Content doc : relevantContent) {
       ClientBatchCheckItem check = buildQuery.apply(doc);
       var checkKey = getCheckKey(check);
       documentToObject.put(doc, checkKey);

       // Skip duplicate checks for same user, object, and relation
       if (!seenChecks.contains(checkKey)) {
           /*...*/
       }
   }

   var permissionsMap = checkPermissions(checks);
   // filter based on permission
   return relevantContent.stream()
           .filter(doc -> permissionsMap.get(documentToObject.get(doc)))
           .collect(Collectors.toList());
}
```

## Set up An FGA Instance

Visit 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**. Once your client is created, you’ll see a modal containing Store ID, Client ID, and Client Secret. Click **Continue** to see the `FGA_API_URL` and `FGA_API_AUDIENCE`.

> To run OpenFGA locally with Docker, use the following command:
>
> ```bash
> docker pull openfga/openfga && \
> docker run -p 8080:8080 -p 8081:8081 -p 3000:3000 openfga/openfga run
> ```

Add `.env` file with the following content to the root of the project.

```sh
# OpenAI key. Not required if using Ollama
OPENAI_API_KEY=<your-openai-api-key>

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

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

### Create the FGA models and tuples

We will use a simple model that defines just an owner and viewer relation for docs:

```sh
model
 schema 1.1

type user

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

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

Now, to have access to the public information, we will need the following tuple on FGA.

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

Now, to have access to the private information, we will need the following tuple on FGA.

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

The store, models, and tuples can be created programmatically using the [OpenFGA Java SDK](https://github.com/openfga/java-sdk). This is defined in `src/main/java/rag/FGAInit.java` and can be run using the following command:

```bash
./gradlew runFGAInit
```

Once done, copy the store ID from the console and update the `.env` file with the store ID.

> You can also use the Auth0 FGA dashboard to create the store, models, and tuples. Navigate to **Model Explorer**. You’ll need to update the model information with the above schema.
> Next, navigate to the **Tuple Management** section and click **+ Add Tuple**, fill in the details for both tuples detailed above.

## 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
./gradlew run
```

The application will start with the query, `Show me forecast for ZEKO?` Since this information is in a private document, and `user2` does not have 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.

```bash
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 change the user to `user1` and run the application again:

```bash
./gradlew run
```

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

Congratulations! You have run a simple RAG application using LangChain4j and secured it using OpenFGA.

## Implementation Patterns for Securing RAG Systems

Here are some common patterns for securing RAG systems using FGA:

1.  **Pre-filtering Pattern**: Check permissions before searching the vector database. This can be done using the [OpenFGA list objects request](https://openfga.dev/docs/getting-started/perform-list-objects) and metadata filtering feature of supported vector databases.
2.  **Post-filtering Pattern**: Perform a vector database search first and then filter the results by permissions. This can be done using the [OpenFGA batch check request](https://openfga.dev/docs/getting-started/perform-check#03-calling-batch-check-api) and custom retrievers or re-rankers. This is what we just did in the example above.
3.  **Hybrid Pattern**: Combine pre-filtering and post-filtering patterns to achieve the best of both worlds.

## Learn More About Auth0 for AI Agents, Auth0 FGA and GenAI

In this post, you learned how to secure a LangChain4j-based RAG application using [OpenFGA](https://fga.dev/). We invite you to check out the [OpenFGA code on GitHub](https://a0.to/fga_repo). Visit [Auth0 for AI Agents](https://a0.to/ai-content) to learn more about how Auth0 can help you secure your GenAI applications.

> [Sign up for Auth0 for AI Agents](https://a0.to/ai-content) in Developer Preview.

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 users' 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.

Secure Java AI Agents: Authorization for RAG Using LangChain4j and Auth0 FGA

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

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

Ryan Quinn

Community Support and Engagement Specialist (FGA)

In this post, we will focus on adding fine-grained authorization to your Python Flask application using OpenFGA.

Fine-grained authorization (FGA) refers to the capability of granting individual users permission to perform particular actions on specific resources. Effective FGA systems enable the management of permissions for a large number of objects and users. These permissions can undergo frequent changes as the system dynamically adds objects and adjusts access permissions for its users.

[OpenFGA](https://openfga.dev/) is an open-source Relationship-Based Access Control (ReBAC) system designed by Okta for developers and adopted by the Cloud Native Computing Foundation (CNCF). It offers scalability and flexibility and supports the implementation of RBAC and ABAC authorization models. By moving authorization logic outside the application code, OpenFGA makes it simpler to evolve authorization policies as complexity grows.

[Flask](https://flask.palletsprojects.com/en/3.0.x/) provides a simple framework for rapidly creating web applications in Python. Using add-ons like [SQLAlchemy](https://www.sqlalchemy.org/) and authentication with Auth0, you can save development time and focus your efforts on your application’s core functionality.

In this guide, we will build a simple application that shows how to incorporate OpenFGA, allowing you to leverage the benefits of fine-grained authorization with Flask.

## Prerequisites

Before we start, let's be sure you have the following installed on your development machine:

- **Python 3.x**
- **Flask**
- **SQLAlchemy**
- **authlib**
- **requests**
- **[OpenFGA SDK for Python](https://github.com/openfga/python-sdk)**

Once you have Python installed, you can install the necessary packages using `pip3`.

> On some systems, the command `pip` may be used in place of `pip3`:

```bash
pip3 install Flask Flask-SQLAlchemy python-dotenv requests openfga_sdk authlib
```

You’ll also need an OpenFGA server instance running. You can use a managed instance like [OktaFGA](https://www.okta.com/products/fine-grained-authorization/) or set up a local instance with Docker with:

```bash
docker run -p 8080:8080 openfga/openfga run
```

## Project Setup

Let's set up the project structure:

```
flask_openfga_tutorial/
├── app/
│   ├── __init__.py
│   ├── models.py
│   ├── routes.py
│   ├── templates/
│   │   ├── base.html
│   │   ├── index.html
│   │   ├── resource.html
├── config.py
├── model.fga
├── run.py
└── requirements.txt
```

- `app/`: This directory contains our Flask application code, including our database model, our route handlers, and our functions that interact with OpenFGA.
- `templates/`: Contains HTML (jinja2) templates for our web interface.
- `config.py`: Configuration settings for Flask and OpenFGA.
- `model.fga`: Our OpenFGA authorization model.
- `run.py`: The entry point for our Flask application.
- `requirements.txt`: Lists our project dependencies.

## Configuring Flask, SQLAlchemy, and AuthLib

### config.py

In our `config.py`, we will define the configuration for our Flask application. We will read sensitive values using `os.getenv()`, which allows us to use a `.env` file in our project directory or from environment variables.

```python
# config.py

import os
from dotenv import load_dotenv

load_dotenv()

class Config:
    SECRET_KEY = os.getenv('SECRET_KEY')
    SQLALCHEMY_DATABASE_URI = os.getenv('DATABASE_URL', 'sqlite:///db.sqlite3')
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    FGA_API_URL = os.getenv('FGA_API_URL', 'http://localhost:8080')
    FGA_STORE_ID = os.getenv('FGA_STORE_ID')
    FGA_MODEL_ID = os.getenv('FGA_MODEL_ID')
    AUTH0_CLIENT_ID = os.getenv('AUTH0_CLIENT_ID')
    AUTH0_CLIENT_SECRET = os.getenv('AUTH0_CLIENT_SECRET')
    AUTH0_DOMAIN = os.getenv('AUTH0_DOMAIN')
```

### app/__init__.py

Next, we will initialize Flask, SQLAlchemy, OAuth, and our OpenFGA Client in `app/__init__.py`:

```python
# app/__init__.py

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from authlib.integrations.flask_client import OAuth
from openfga_sdk.client import ClientConfiguration
from openfga_sdk.sync import OpenFgaClient
from config import Config
import os


db = SQLAlchemy()
oauth = OAuth()

def create_app():
    app = Flask(__name__)
    app.config.from_object(Config)

    db.init_app(app)
    oauth.init_app(app)

    # Configure and initialize the Auth0 Client
    oauth.register(
        "auth0",
        client_id=app.config["AUTH0_CLIENT_ID"],
        client_secret=app.config["AUTH0_CLIENT_SECRET"],
        client_kwargs={
            "scope":"openid profile email",
        },
        server_metadata_url=f'https://{app.config["AUTH0_DOMAIN"]}/.well-known/openid-configuration'
    )
    
    #Configure and initialize the OpenFGA Client
    configuration = ClientConfiguration(
        api_url=app.config['FGA_API_URL'],
        store_id=app.config['FGA_STORE_ID'],
        authorization_model_id=app.config['FGA_MODEL_ID'],
    )

    app.fga_client = OpenFgaClient(configuration)
    app.fga_client.read_authorization_models()

    from .routes import main as main_blueprint
    app.register_blueprint(main_blueprint)

    with app.app_context():
        db.create_all()

    return app

```

## Creating Our Launch Script

### run.py

Our `run.py`, in the root directory of our project, is the script we will call in order to run our Flask application:

```python
# run.py

from app import create_app

app = create_app()

if __name__ == '__main__':
    app.run(debug=True)

```

## Defining the Database Models

### app/models.py

We will define the `Resource` model in `app/models.py` to keep track of the resources users create.

```python
# app/models.py

from . import db
import uuid

class Resource(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    uuid = db.Column(db.String(36), unique=True, nullable=False, default=lambda: str(uuid.uuid4()))
    name = db.Column(db.String(120), nullable=False)
    owner = db.Column(db.String(255), nullable=False)

```

## Setting Up the OpenFGA Model

Next, we will create our authorization model in the file `model.fga`. This model will define the types of relationships that can exist between our users and objects:

```plaintext
model
  schema 1.1

type user
  relations
    define owner: [user]

type resource
  relations
    define owner: [user]
    define viewer: owner

```

This model defines two types, `user` and `resource`, and establishes an `owner` relationship. The `viewer` relation is defined to be the same as the `owner`, meaning only owners can view the resource.

### Writing the Model to OpenFGA

We will use the OpenFGA CLI to write our new model for our OpenFGA store. Check the OpenFGA docs to learn [how to use the CLI to create a store](https://openfga.dev/docs/getting-started/cli) where you can write your model. Remember, models, are immutable, so anytime you make changes; you need to write the updated model and update the model ID used in your application.

First, we will create a store where we'll write our model:

```
fga store create --name "FGA Flask Demo Store"
```

The result of that command will include our `store id`, which we will use in our next command to write the model.

```bash
fga model write --store-id <store_id> --file model.fga
```
## Configuring Authentication
This app uses Auth0 for authentication, so to get started, we will need to configure our application to enable authentication.

### Create an Auth0 Account
If you do not have an Auth0 account, create one [here for free](https://auth0.com/signup). 

### Configure an application
Use the interactive selector to create a new Auth0 application.

- Application Type
For Application Type, select "Single Page Application."

- Allowed Callback URLs
Enter `http://localhost:3000/callback` in "Allowed Callback URLs"

- Allowed Logout URLs
Enter `http://localhost:3000/` in "Allowed Logout URLs"

- Allowed Web Origins
Enter `http://localhost:3000` in "Allowed Web Origins"

By default, your app will have two "Connections" enabled to provide user authentication data.

- google-oauth2 - This option allows users to log in with Google. There is no need to configure user accounts with this option
- Username-Password-Authentication - This option allows you to create user accounts in the Auth0 dashboard by specifying usernames and passwords

### Collect required credentials
From your application's page in the Auth0 Dashboard, copy your app's `Domain`, `Client ID`, and `Client Secret`, which we will use later when we configure our application.

## Implementing Routes with AUTH0 and Openfga

### app/routes.py

Next, create the application routes in `app/routes.py`:

```python
# app/routes.py

from flask import Blueprint, request, render_template, redirect, url_for, flash, session, current_app
from .models import Resource, db
from urllib.parse import quote_plus, urlencode
from openfga_sdk.client.models import ClientTuple, ClientWriteRequest, ClientCheckRequest
from app import oauth
import uuid
from functools import wraps

main = Blueprint('main', __name__)

def login_required(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        # This decorated function can be applied to route handers and will ensure that a valid user session is active.
        # If the requestor is not logged in it will redirect their browser to the home page
        if 'user_info' not in session:
            return redirect(url_for('main.login'))
        return f(*args, **kwargs)
    return decorated_function

@main.route("/login")
def login():
    # Login function redirects to the Auth0 login page for our app
    return oauth.auth0.authorize_redirect(
        redirect_uri=url_for("main.callback", _external=True)
    )

@main.route("/callback", methods=["GET", "POST"])
def callback():
    # The callback function that Auth0 will redirect users to after authentication
    try:
        token = oauth.auth0.authorize_access_token()
        session["user_info"] = token['userinfo']    
        session['user_email'] = token['userinfo']['email']
    except Exception as e:
        return redirect(url_for("main.index"))
    return redirect(url_for("main.index"))
    
    

@main.route("/logout")
def logout():
    # Log a user out of the app, clear the session and redirect them to the Auth0 logout url for our app
    session.clear()
    return redirect(
        "https://" + current_app.config["AUTH0_DOMAIN"]
        + "/v2/logout?"
        + urlencode(
            {
                "returnTo": url_for("main.index", _external=True),
                "client_id": current_app.config["AUTH0_CLIENT_ID"],
            },
            quote_via=quote_plus,
        )
    )

@main.route('/')
@login_required
def index():
    resources = Resource.query.all()
    return render_template('index.html', resources=resources, user_info=session.get['user_info'])

@main.route('/create_resource', methods=['POST'])
@login_required
def create_resource():
    resource_name = request.form.get('name')

    resource = Resource(name=resource_name, owner=session.get['user_email'])
    db.session.add(resource)
    db.session.commit()

    # Create a tuple in OpenFGA
    fga_client = current_app.fga_client
    write_request = ClientWriteRequest(
        writes=[
            ClientTuple(
                user=f"user:{session.get['user_email']}",
                relation="owner",
                object=f"resource:{resource.uuid}",
            ),
        ],
    )
    fga_client.write(write_request)

    return redirect(url_for('main.resource', resource_uuid=resource.uuid))

@main.route('/resource/<resource_uuid>')
@login_required
def resource(resource_uuid):
    resource = Resource.query.filter_by(uuid=resource_uuid).first()
    if not resource:
        flash('Resource not found.')
        return redirect(url_for('main.index'))

    # Check permission using OpenFGA
    fga_client = current_app.fga_client
    check_request = ClientCheckRequest(
        user=f"user:{session.get['user_email']}",
        relation="viewer",
        object=f"resource:{resource.uuid}",
    )
    response = fga_client.check(check_request)

    if not response.allowed:
        flash('You do not have permission to view this resource.')
        return redirect(url_for('main.index'))

    return render_template('resource.html', resource=resource)
```

- **User Login**: Users can register or log in using Auth0 via the `login` route.
- **Resource Creation**: Users can create resources, and ownership is established by writing a tuple to OpenFGA.
- **Resource Viewing**: Access to resources is controlled by checking permissions with OpenFGA.

## Creating our Web Templates

### Base Template: `templates/base.html`

Create a base template for consistent layout, our other templates will inherit their top level layout from this template.

```html


<!doctype html>
<html lang="en">
<head>
    <title>{% block title %}OpenFGA Tutorial{% endblock %}</title>
</head>
<body>
    {% with messages = get_flashed_messages() %}
      {% if messages %}
        <ul>
        {% for message in messages %}
          <li>{{ message }}</li>
        {% endfor %}
        </ul>
      {% endif %}
    {% endwith %}
    {% block content %}{% endblock %}
    <a href="/logout">Log Out</a>
</body>
</html>
```

### Index template: `templates/index.html`

This page extends our base template and provides the UI elements for the main page of our application.

```html


{% extends "base.html" %}
{% block title %}Home{% endblock %}
{% block content %}
<h2>Welcome, {{ user_info.name }}!</h2>

<h3>Create a Resource</h3>
<form method="POST" action="{{ url_for('main.create_resource') }}">
    <input type="text" name="name" placeholder="Resource Name" required>
    <button type="submit">Create</button>
</form>

<h3>Resources</h3>
<ul>
    {% for resource in resources %}
        <li><a href="{{ url_for('main.resource', resource_uuid=resource.uuid) }}">{{ resource.name }}</a></li>
    {% else %}
        <li>No resources available.</li>
    {% endfor %}
</ul>
{% endblock %}
```

### Resource template: `templates/resource.html`

This page extends our base template and displays a list of resources a user has access to.

```html


{% extends "base.html" %}
{% block title %}Resource Details{% endblock %}
{% block content %}
<h2>Resource: {{ resource.name }}</h2>
<p>Owned by: {{ resource.owner }}</p>
<a href="{{ url_for('main.index') }}">Back to Home</a>
{% endblock %}
```

## Testing the Application

### Configuration variables

Our application expects several variables to be set as environment variables or in a .env file in our project directory. For this example, we will create a .env file with the following content, including the model and store we created earlier and our Auth0 application details:

```plaintext
SECRET_KEY="your_secret_key"
DATABASE_URL="sqlite:///db.sqlite3"
FGA_API_URL="http://localhost:8080"
AUTH0_CLIENT_ID=""
AUTH0_CLIENT_SECRET=""
AUTH0_DOMAIN=""
FGA_STORE_ID="your fga store id"
FGA_MODEL_ID="your fga model id"
```

- `SECRET_KEY`: A unique value used internally to secure session data in Flask.
- `DATABSE_URL`: In our example, we are using SQLite, but you can also use a MySQL or PostgreSQL connection string.
- `FGA_API_URL`: The URL to connect to your OpenFGA instance. The example above assumes you are running OpenFGA in Docker locally using the command provided earlier.
- `AUTH0_CLIENT_ID`:  The client ID from our application page in the Auth0 Dashboard.
- `AUTH0_CLIENT_SECRET`: The client secret from our application page in the Auth0 Dashboard.
- `AUTH0_DOMAIN`: The domain from our application page in the Auth0 Dashboard.
- `FGA_STORE_ID`: This is the store ID that was returned when you created a store in your OpenFGA instance.
- `FGA_MODEL_ID`:  This is the model ID that was returned when you ran `fga write` to write your model.

### Run the Flask App

Start the application:

```bash
python run.py
```

### Get Started

- Open your browser and navigate to `http://127.0.0.1:5000/`.
- You will be redirected via our login route handler to log in via Auth0. You can log in via one of the OAuth providers you selected or with user accounts created in the Auth0 Dashboard.

### Create a Resource

- After logging in, create a resource by entering a name and clicking "Create".
- The resource will be added to the database, and an ownership tuple will be written to OpenFGA.

### View the Resource

- Click on the resource name to view its details.
- OpenFGA checks whether you have permission to view the resource based on the `viewer` relation.

### Test Access Control

- Log out and create a new user either by logging in with a different OAuth account or by adding another set of login credentials in the Auth0 dashboard.
- Try to access the resource created by the first user by entering its URL directly.
- You should receive a message stating you do not have permission to view the resource.

## Next Steps

This guide presented a basic example of how OpenFGA can be used within a Python Flask application to manage authorization and access to resources. You can find a more detailed example application that implements a web application allowing users to share text files and folders and covers topics including parent-child relationships and sharing resources with others [in this project](https://github.com/openfga/flask-demo).

OpenFGA for Python Flask Applications

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

OpenFGA for Spring Boot Applications

Sam4-square

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

Sam Bellen

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

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!

"fine-grained"