OpenFGA Adoption Patterns and Best Practices Section (#972)

Co-authored-by: Daniel Yeam <daniel.yeam@okta.com>
Co-authored-by: Raghd Hamzeh <raghd.hamzeh@openfga.dev>

Author: 3 people

docs/content/best-practices/adoption-patterns.mdx

@@ -0,0 +1,202 @@
+---
+title: Adoption Patterns
+sidebar_position: 3
+slug: /best-practices/adoption-patterns
+description: Describe different ways FGA can be adopted in an organization
+---
+
+import {
+  ProductName,
+  ProductNameFormat,
+  RelatedSection,
+
+} from '@components/Docs';
+
+# <ProductName format={ProductNameFormat.ShortForm}/> Adoption Patterns
+
+This document outlines key implementation patterns for adopting  <ProductName format={ProductNameFormat.ShortForm}/> in your organization.
+
+## Starting with coarse-grained access control
+
+When evaluating this solution, many companies start by replicating their existing permissions structure before moving to more granular controls. For example, if you're using Role-Based Access Control (RBAC) in a B2B scenario, you might start with a simple model:
+
+```dsl.openfga
+model 
+  schema 1.1
+
+  type user
+  type organization
+    relations
+      define admin : [user]
+      define member : [user]
+      # .. add additional organization roles
+
+      # map permissions to organization roles 
+      define can_add_member : admin
+      define can_delete_member : admin
+      define can_view_member : admin or member
+      define can_add_resource : admin or member
+
+```
+
+You can define any number of roles for the organization type and then define the permissions based on those roles. You can then check if users have a specific permission at the organization level by calling the Check API on the organization object: 
+
+```
+Check(user: "user:anne", relation: "can_add_member", object: "organization:acme") 
+```
+
+A better implementation is to define the application's resource types in the model (e.g. documents, projects, insurance policies, bank accounts, etc):
+
+
+```dsl.openfga
+model 
+  schema 1.1
+
+  type user
+  type organization
+    relations
+      define admin : [user]
+      define member : [user]
+
+      define can_add_member : admin
+      define can_delete_member : admin
+      define can_view_member : admin or member
+      define can_add_resource : admin or member
+
+
+   type resource
+     relations
+       define organization : [organization]
+
+      # map resource permissions to organization roles
+       define can_delete_resource : admin from organization or member from organization
+       define can_view_resource : admin from organization or member from organization      
+
+```
+
+In this case, you'll need to write tuples that establish the relationship between resource instances and organizations, or use Contextual Tuples to specify them, e.g:
+
+```
+user: organization:acme
+relation: organization
+object: resource:root
+```
+
+In this case, the Check() call will be at the resource level, for example:
+
+```
+Check(user: "user:anne", relation: "can_view_resource", object: "resource:root") 
+```
+
+The main advantage of this approach is that your APIs will be checking permissions at the proper level. If you later want to evolve your authorization model to be more fine grained, you won't need to change your app. For example, you can add fine grained access permissions at the resource level, and your authorization check won't change:
+
+```
+   type resource
+     relations
+       define organization : [organization]
+       define owner: [user]
+       define viewer : [user]
+
+      # map resource permissions to organization roles
+       define can_delete_resource : admin from organization or member from organization or owner
+       define can_view_resource : admin from organization or member from organization or owner or viewer
+```
+
+## Provide request-level data
+
+One of the advantages of the Zanzibar/<ProductName format={ProductNameFormat.ShortForm}/> approach is that all the data you need to make authorization decisions is stored in a centralized database. That greatly simplifies how application implement access control. Applications do not need to retrieve al the required data before invoking an authorization service.
+
+However, writing the data to the centralized store adds implementation complexity. You need to implement a data pipeline that makes sure the data is always up to date.
+
+<ProductName format={ProductNameFormat.ShortForm}/> provides a feature called [Contextual Tuples](../interacting/contextual-tuples.mdx) that allows sending the required data as part of each authorization request instead of storing it on the <ProductName format={ProductNameFormat.ShortForm}/> database. Overusing this feature has many drawbacks, as you are now adding additional complexity and latency around collecting the data, and you are not benefiting from using <ProductName format={ProductNameFormat.ShortForm}/> as intended. However, implementing a hybrid approach can make sense in many scenarios and can also be a helpful tool at the start when you are transitioning into a more OpenFGA tailored approach.
+
+When the data is already available to the calling API, sending it as a contextual tuple is very simple. A common use case is you have data in [your access tokens](../modeling/token-claims-contextual-tuples.mdx) (for example, roles/groups claims). Instead of synchronizing groups/roles relations to <ProductName format={ProductNameFormat.ShortForm}/>, you can send those as contextual tuples.
+
+When the data is not already, you will need to retrieve it. This is what you need to do if you are implementing pure Attribute Access Control. You'd retrieve the data and send it to the authorization policy engine. You can do the same with <ProductName format={ProductNameFormat.ShortForm}/> using Contextual Tuples.
+
+You'll need to make the trade-off between writing the data to <ProductName format={ProductNameFormat.ShortForm}/> so it's always available for any authorization request, or requesting it before making an authorization check.
+
+We've seen companies successfully following a hybrid approach, starting by synchronizing the data that's easy first and providing the rest as contextual tuples. As their implementation matures, they implement more synchronization processes and stop sending the contextual tuples.
+
+## Use <ProductName format={ProductNameFormat.ShortForm}/> to enrich JWTs
+
+Once you have your authorization model and data set up, you can start making authorization checks from your application. The preferred way is to perform a [Check()](../getting-started/perform-check.mdx) call.
+
+However, you might have a large set of APIs that are already making authorization checks using JWTs. Changing those applications can be a significant investment. Even if JWTs have several drawbacks compared to making FGA API calls, it can be reasonable to first start by using <ProductName format={ProductNameFormat.ShortForm}/> to generate the claims that are stored in JWTs, while the applications keep using those claims to make authorization decisions.
+
+Over time, you'll migrate the applications and APIs to use authorization check instead.
+
+Authentication services usually provide a way to enrich access tokens during the authorization flow. You can see an example on how to do it with Auth0 [here](https://auth0.com/blog/adding-custom-claims-to-id-token-with-auth0-actions/).
+
+
+For example, if you want to include in the access token the organizations that a user can log-in to, based on the following model:
+
+```
+  type user
+  type organization
+    relations
+      define member : [user]
+```
+
+You can call `ListObjects(type:"organization", relation:"member", user: "user:xxx")` and include those.
+
+## Promoting Organization-Wide Adoption
+
+To introduce <ProductName format={ProductNameFormat.ShortForm}/> in a large company, it's recommended that you identify a problem where the additional enables quickly delivering business value to customers. It can be a new project, a new module, a new feature. Using <ProductName format={ProductNameFormat.ShortForm}/> for such a project can be an easier decision. Once an implementation is successful, you can try influencing the rest of the organization to adopt it.
+
+However, influencing the decision makers of a large organization can be hard. Each team has their own internal roadmaps and not all of the teams will see value in implementing a new authorization system. Migration can be seen as a tech-debt project instead of a business-value-driven one. 
+
+The can take advantage of the following capabilities to simplify adoption by multiple teams:
+
+- [Modular Models](../modeling/modular-models.mdx) enable each team to independently evolve their authorization policies without relying on a central team.
+- [Access Control](../getting-started/setup-openfga/access-control.mdx) allows you to issue different credentials for each application, with permissions that ensure that each credential can only write data to the types defined in the Modules they own.
+
+## Domain-Specific Authorization Server
+
+Some companies decide to wrap <ProductName format={ProductNameFormat.ShortForm}/> with their own authorization service. They decide to do this for multiple reasons:
+
+- Sometimes they already have a centralized service, and it's easy to replace it with another without changing the calling applications.
+- It can simplify internal adoption by providing domain-specific APIs. Instead of calling `write` or `check`, applications can call a `/share-document` endpoint or a `/can-view-document` one. Each team does not need to learn the <ProductName format={ProductNameFormat.ShortForm}/> API.
+- If they are using Contextual Tuples, they can keep the logic to retrieve additional data to send to <ProductName format={ProductNameFormat.ShortForm}/> in a single service.
+- They only need to provide <ProductName format={ProductNameFormat.ShortForm}/> configuration data like Store ID and Model ID in a single service.
+
+On the other hand, adding another service increases latency, adds additional complexity and would make the teams less likely to find help from existing public OpenFGA documentation and resources.
+
+## Shadowing the <ProductName format={ProductNameFormat.ShortForm}/> API
+
+When migrating from an existing authorization system to <ProductName format={ProductNameFormat.ShortForm}/>, it's recommended to first run both systems in parallel, with <ProductName format={ProductNameFormat.ShortForm}/> in "shadow mode". This means that while the existing system continues to make the actual authorization decisions, you also make calls to <ProductName format={ProductNameFormat.ShortForm}/> asynchornously and compare the results.
+
+This approach has several benefits:
+
+- You can validate that your authorization model and relationship tuples are correctly configured before switching to <ProductName format={ProductNameFormat.ShortForm}/>.
+- You can measure the performance impact of adding <ProductName format={ProductNameFormat.ShortForm}/> calls to your application.
+- You can identify edge cases where the <ProductName format={ProductNameFormat.ShortForm}/> results differ from your existing system.
+- You can gradually build confidence in the <ProductName format={ProductNameFormat.ShortForm}/> implementation.
+
+To implement shadow mode:
+
+1. Configure your application to make authorization checks against both systems
+2. Log any discrepancies between the two systems
+3. Analyze the logs to identify and fix any issues
+4. Once confident in the results, switch to using <ProductName format={ProductNameFormat.ShortForm}/> as the source of truth. The same approach of shallow checks when [migrating between models](../getting-started/immutable-models.mdx#potential-use-cases).
+
+This pattern is particularly useful for critical systems where authorization errors could have significant impact.
+
+## Related Sections
+
+<RelatedSection
+  description="Check out these related resources for more information about adopting OpenFGA"
+  relatedLinks={[
+    {
+      title: 'Production Best Practices',
+      description: 'Learn about best practices for running OpenFGA in production environments.',
+      link: './../getting-started/running-in-production',
+    },
+    {
+      title: 'Modular Authorization Models',
+      description: 'Learn how to break down your authorization model into modules.',
+      link: './../modeling/modular-models',
+    }
+  ]}
+/>
+

docs/sidebars.js

@@ -385,6 +385,24 @@ const sidebars = {
         },
       ],
     },
+
+    {
+      type: 'category',
+      label: 'Best Practices',
+      collapsible: true,
+      collapsed: true,
+      link: {
+        type: 'doc',
+        id: 'content/best-practices/adoption-patterns',
+      },
+      items: [
+        {
+          type: 'doc',
+          label: 'Adoption Patterns',
+          id: 'content/best-practices/adoption-patterns',
+        }
+      ],
+    },
   ],
 };