Merge branch 'main' into dependabot/npm_and_yarn/http-proxy-middlewar…

…e-2.0.7

blog/authors.yml

@@ -15,3 +15,4 @@ hello-caleb:
   name: Caleb Hunter
   title: Community Engagement
   url: https://github.com/hello-caleb
+  image_url: /img/blog/authors/caleb.jpg

blog/fine-grained-news-2024-10.md

@@ -0,0 +1,65 @@
+---
+title: Fine Grained News - October 2024
+description: Fine Grained News
+slug: fine-grained-news-2024-10
+date: 2024-10-30
+authors: hello-caleb
+tags: [newsletter]
+image: https://openfga.dev/img/og-rich-embed.png
+hide_table_of_contents: false
+---
+# Fine Grained News - October 2024
+
+Welcome to the October edition of Fine Grained News! As we approach the end of the year, we're excited to bring you the latest updates, improvements, and community contributions shaping the future of OpenFGA.
+
+As always, if you’re finding the OpenFGA project to be a valuable resource, we would greatly appreciate if you would [star our repo](https://github.com/openfga/openfga) on GitHub to show your support!⭐
+
+## Just Shipped
+
+* **OpenFGA v1.7.0:** In our latest release, we’ve introduced Access Control. This experimental feature allows you to control access to your OpenFGA server, and of course, we built it using OpenFGA! We’ve updated our Docs to show you [how to enable this feature](https://openfga.dev/docs/getting-started/setup-openfga/access-control); please share your feedback in the [GitHub Discussions](https://github.com/orgs/openfga/discussions/382)! 
+
+* This month, we’ve also added documentation of our [OpenFGA release process](https://github.com/openfga/openfga/pull/1923). 
+
+* We’ve [improved performance for checks involving nested tuple-to-userset relations](https://github.com/openfga/openfga/pull/2025). This is commonly used when implementing nested groups. Users can enable this with the experimental flag `enable-check-optimizations`.
+
+* Following last month’s launch of OpenFGA SDK support for telemetry data using OpenTelemetry, we’ve also [updated our Docs](https://openfga.dev/docs/getting-started/configure-telemetry) to guide users through configuration to collect tracing data and metrics.
+
+## In Progress
+
+**Batch Check API Endpoint:** We’re close to releasing a [new feature](https://github.com/orgs/openfga/projects/1/views/1?pane=issue&itemId=28481432&issue=openfga%7Croadmap%7C35) to enable sending multiple check operations in a single network request.
+
+Check out our roadmap to see what’s in the works. Feature requests and ideas can be shared in [GitHub Discussions](https://github.com/orgs/openfga/discussions).
+
+## Community Highlights
+
+* **OpenFGA at Open Source Strategy Forum 2024:** [Kiah Imani](https://www.linkedin.com/in/kiah-tolliver/) presented “Role-Based Access Is So Yesterday: Revolutionizing Authorization with OpenFGA” at the OSSF 2024 earlier this month. The presentation is now [available in Youtube](https://www.youtube.com/watch?v=uHKeE4DAHpE)
+![Kiah Imani](../static/img/blog/fgn-2024-10-kiah-imani.jpeg)
+
+* **OpenFGA at KubeCon:** [Andres Aguiar](https://www.linkedin.com/in/aaguiar/) will participate in KubeCon/CloudNativeCon in November! OpenFGA will have a Kiosk in the Project Pavilion. He'll present a [lightning talk on OpenFGA](https://kccncna2024.sched.com/event/1iWA6/openfga-the-cloud-native-way-to-implement-fine-grained-authorization-project-lightning-talk) and participate in [The Policy Engines Showdown](https://kccncna2024.sched.com/event/1i7qp/the-policy-engines-showdown-gabriel-l-manor-permitio-andres-aguiar-okta-omri-gazitt-aserto-anders-eknert-styra-sarah-cecchetti-aws?iframe=no).  
+  ![Andres Aguiar](../static/img/blog/fgn-2024-10-andres-aguiar.jpg)
+
+* **OpenFGA in Italy:** [Andrea Chiarelli](https://www.linkedin.com/in/andreachiarelli) will present [Authorize in the Cloud with OpenFGA](https://www.cloudday.it/e/sessione/3533/Autorizzare-nel-cloud-con-OpenFGA) at [Cloud Day 2024](https://www.cloudday.it/e/3486/Cloud-Day-2024) in Milan on November 20, 2024.   
+  ![Andrea Chiarelli](../static/img/blog/fgn-2024-10-andrea-chiarelli.jpeg)
+
+* **New Demp Flask App Added:** To complement our OpenFGA examples and guides, we have published an [example app demonstrating the integration of OpenFGA](https://github.com/openfga/flask-demo). This app utilizes several FGA features to provide a multi-user system for folder and text file sharing. Thanks to @[ryanpq](https://github.com/openfga/flask-demo/commits?author=ryanpq) for your contribution!  
+  ![Ryan Quinn](../static/img/blog/fgn-2024-10-ryanpq.jpg)
+
+* **Monthly Community Meeting:** Join us for our monthly [Community Meetings](https://github.com/openfga/community/blob/main/community-meetings.md#:~:text=OpenFGA%20Community%20Meetings), held on the second Thursday of every month at [11 AM Eastern Time (US)](https://www.worldtimebuddy.com/?qm=1&lid=12,100,5,6,8&h=5&sln=11-12&hf=1). Our next meeting is on Thursday, November 14, 2024. Our community meetings are a great way to stay updated with the latest developments, ask questions, and engage with the OpenFGA community. If you can’t join the meetings live, our [latest month's video](https://youtu.be/LITUfwqpNIo?si=ze7dhGG46rhatWBN) will always be posted on our [YouTube channel](https://www.youtube.com/@OpenFGA)! 
+
+    As always, we welcome community members to demo their use cases. If you want to demo your implementation of OpenFGA, please contact any of the OpenFGA team on our community channels linked below.
+
+## New Adopters
+
+* This month, we welcome [Gillion](https://www.gilion.com/) and [Flex](https://flex.team/) as OpenFGA adopters! If you or your company have implemented OpenFGA, we would love to hear about it! Please add your name as an adopter by updating the [ADOPTERS.md](https://github.com/openfga/community/blob/main/ADOPTERS.md#companiesprojects-using-openfga-in-production) file and sending us a PR.
+
+* If you or your company provides implementation services for OpenFGA, we invite you to share your information with the community in our [Implementation Services](https://github.com/openfga/community/blob/main/ADOPTERS.md#companies-offering-openfga-implementation-services) section of the ADOPTERS.md file by sending us a PR! However, please note that the OpenFGA project has not evaluated or endorsed the individuals and companies listed, and inclusion does not imply endorsement.
+
+## Announcements
+
+* **Hacktoberfest Highlights:** This Hacktoberfest, we welcomed 13 new contributors making their first commit to OpenFGA! Thanks to the incredible community participation, we saw a 28% increase in pull requests compared to September and a remarkable 260% increase in PRs on the SDK Generator. A huge thanks to this community for your continued participation and contributions! 
+
+* **OpenFGA Community Meeting Updates:** We are adding chapters to our [YouTube channel](https://www.youtube.com/@OpenFGA) videos to simplify content navigation. We’ve begun with the most recent videos and will add chapters as time goes on. We have also begun releasing [demos](https://www.youtube.com/playlist?list=PLUR5l-oTFZqXYaB3W_OEEsUhI4l8iLYNe) as individual videos for easier content consumption. You can catch this month’s demos on [Modular Authorization](https://www.youtube.com/watch?v=ws9BjricJu4) and  [Client-Side Caching](https://www.youtube.com/watch?v=sst9PyvPHSk), with Materialize Integration coming soon!
+
+## See you Next Month
+
+Fine Grained News is published every month. If you have any feedback, want to share your OpenFGA story, or have a noteworthy update, please let us know on any of our [community channels](https://openfga.dev/community) or at [[email protected]](mailto:[email protected]).

docs/content/concepts.mdx

@@ -624,7 +624,7 @@ For example, the following returns all the users of type `user` that have the `v
   }}
 />
 
-For more information, see the the [ListUsers API Reference](/api/service#Relationship%20Queries/ListUsers).
+For more information, see the [ListUsers API Reference](/api/service#Relationship%20Queries/ListUsers).
 
 </details>
 <details>

docs/content/getting-started/configure-telemetry.mdx

@@ -291,3 +291,42 @@ The <ProductName format={ProductNameFormat.ShortForm}/> SDK Client can collect t
 | `url.scheme`                   | string | Yes                | HTTP scheme of the request (`http`/`https`)                                       |
 | `url.full`                     | string | Yes                | Full URL of the request                                                           |
 | `user_agent.original`          | string | Yes                | User Agent used in the query                                                      |
+
+## Tracing
+
+OpenFGA [supports](./setup-openfga/configure-openfga.mdx) tracing with OpenTelemetry.
+
+If your application uses OpenTelemetry tracing, traces will be propagated to OpenFGA, provided the traces are exported to the same address.
+This can be useful to help diagnose any suspected performance issues when using OpenFGA.
+
+If your application does not already use tracing, OpenTelemetry offers [zero-code instrumentation](https://opentelemetry.io/docs/zero-code/) for several languages.
+For example, a TypeScript application can be configured with tracing by using one of the [OpenTelemetry JavaScript Instrumentation Libraries](https://opentelemetry.io/docs/languages/js/libraries/):
+
+```bash
+npm install --save @opentelemetry/auto-instrumentations-node
+```
+
+Create an initialization file to configure tracing:
+
+```javascript
+// tracing.ts
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter(),
+  // registers all instrumentation packages, you may wish to change this
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+```
+
+Run the application with the appropriate OTEL environment variables:
+
+```bash
+OTEL_SERVICE_NAME='YOUR-SERVICE-NAME' ts-node -r ./tracing.ts YOUR-APP.ts
+```
+
+See the [OpenTelemetry documentation](https://opentelemetry.io/docs/) for additional information to configure your application for tracing.

docs/content/getting-started/immutable-models.mdx

@@ -17,31 +17,43 @@ import {
 
 Authorization Models in <ProductName format={ProductNameFormat.ShortForm}/> are immutable, they are created once and then can no longer be deleted or modified. Each time you write an authorization model, a new version is created.
 
-### Viewing all the authorization models
+## Viewing all the authorization models
 
 You can list all the authorization models for a store using the [ReadAuthorizationModels](/api/service#/Authorization%20Models/ReadAuthorizationModels) API. This endpoint returns the results sorted in reverse chronological order, as in the first model in the list is the latest model. By default, only the last 50 models are returned, but you can paginate across by passing in the appropriate `continuation_token`.
 
-### How to target a particular model
+## How to target a particular model
 
 Some endpoints relating to tuples ([Check](/api/service#/Relationship%20Queries/Check), [ListObjects](/api/service#/Relationship%20Queries/ListObjects), [ListUsers](/api/service#/Relationship%20Queries/ListUsers), [Expand](/api/service#/Relationship%20Queries/Expand), [Write](/api/service#/Relationship%20Tuples/Write)) accept an `authorization_model_id`, which we strongly recommend passing, especially in production.
 
 In practice, you would pin the authorization model ID alongside the store ID in your configuration management system. Your services would read this value and use it in their requests to FGA. This helps you ensure that your services are using the same consistent ID across all your applications, and that rollouts can be seamless.
 
-### Benefits of passing in an authorization model ID
+## Benefits of passing in an authorization model ID
 
 Targeting a specific model ID would ensure that you don't accidentally break your authorization checks in production because a mistake was made when updating the authorization model. It would also slightly improve the latency on your check requests.
 
 If that field is passed, evaluation and validation will happen for that particular authorization model ID. If this field is not passed, <ProductName format={ProductNameFormat.ShortForm}/> will use the last created Authorization Model for that store.
 
-### Potential use-cases
+## Potential use-cases
+
+### Complex model migrations
+
+Certain model changes require adapting your application code and migrating tuples before rolling it out. For example, if you rename a relation, you need to change the application and copy the existing tuples to use the new relation name. This scenario requires the following steps:
+
+- Update the authorization model with the renamed relation. A new model ID will be generated but it won't be used in production yet.
+- Update the application to use the new relation name.
+- Copy existing tuples to use the new relation name.
+- Deploy the new application targeting the new model ID.
+
+You can learn more about model migrations [here](../modeling/migrating/overview.mdx).
+
+### Progresivelly rollout changes
 
 Being able to target multiple versions of the authorization model enables you to progressively roll out model changes, which is something you should consider doing if the changes are significant. You could:
 
 - Do shadow checks where you would perform checks against both your existing model and the new upcoming model you are hoping to replace it with.This will help you detect and resolve any accidental discrepancies you may be introducing, and ensure that your new model is at least as good as your old one.
 
 - When you are confident with your model, you could implement gradual rollouts that would allow you to monitor and check if any users are having access issues before you go ahead and increase the rollout to 100% of your user base.
 
-
 :::info Getting an Authorization Model's Creation Date
 The Authorization Model ID is a [ULID](https://github.com/ulid/spec) which includes the date created. You can extract the creation date using a library for your particular language.
 

docs/content/getting-started/perform-check.mdx

@@ -9,6 +9,7 @@ import {
   SupportedLanguage,
   languageLabelMap,
   CheckRequestViewer,
+  BatchCheckRequestViewer,
   DocumentationNotice,
   ProductConcept,
   ProductName,
@@ -140,13 +141,13 @@ To obtain the [access token](https://auth0.com/docs/get-started/authentication-a
 </TabItem>
 </Tabs>
 
-### 02. Calling check API
+### 02. Calling Check API
 
-To check whether user `user:anne` has relationship `reader` with object `document:Z`
+To check whether user `user:anne` has relationship `can_view` with object `document:Z`
 
 <CheckRequestViewer
   user={'user:anne'}
-  relation={'reader'}
+  relation={'can_view'}
   object={'document:Z'}
   allowed={true}
   skipSetup={true}
@@ -163,6 +164,49 @@ To check whether user `user:anne` has relationship `reader` with object `documen
 
 The result's `allowed` field will return `true` if the relationship exists and `false` if the relationship does not exist.
 
+### 03. Calling Batch Check API
+
+If you want to check multiple user-object-relationship combinations in a single request, you can use the [Batch Check](/api/service#Relationship%20Queries/BatchCheck) API endpoint. Batching authorization checks together in a single request significantly reduces overall network latency.    
+
+The Batch Check endpoint requires a `correlation_id` parameter for each check. The `correlation_id` is used to "correlate" the check responses with the checks sent in the request, since `tuple_keys` and `contextual_tuples` are not returned in the response on purpose to reduce data transfer to improve network latency. A `correlation_id` can be composed of any string of alphanumeric characters or dashes between 1-36 characters in length. 
+This means you can use:
+- simple iterating integers `1,2,3,etc`
+- UUID `e5fe049b-f252-40b3-b795-fe485d588279`
+- ULID `01JBMD9YG0XH3B4GVA8A9D2PSN`
+- or some other unique string
+
+But each `correlation_id` within a request must be unique.
+
+*Note*: If you are using one of our SDKs, the `correlation_id` is inserted for you by default and automatically correlates the `allowed` response with the proper `tuple_key`.
+
+To check whether user `user:anne` has multiple relationships `writer` and `reader` with object `document:Z`
+
+<BatchCheckRequestViewer
+  checks={[
+    {
+      user: 'user:anne',
+      relation: 'writer',
+      object: 'document:Z',
+      correlation_id: '886224f6-04ae-4b13-bd8e-559c7d3754e1',
+      allowed: false
+    },
+    {
+      user: 'user:anne',
+      relation: 'reader',
+      object: 'document:Z',
+      correlation_id: 'da452239-a4e0-4791-b5d1-fb3d451ac078',
+      allowed: true
+    }
+  ]}
+
+  skipSetup={true}
+  allowedLanguages={[
+    SupportedLanguage.CURL,
+  ]}
+/>
+
+The result will include an `allowed` field for each authorization check that will return `true` if the relationship exists and `false` if the relationship does not exist.
+
 ## Related Sections
 
 <RelatedSection
@@ -173,5 +217,10 @@ The result's `allowed` field will return `true` if the relationship exists and `
       description: 'Read the Check API documentation and see how it works.',
       link: '/api/service#Relationship%20Queries/Check',
     },
+    {
+      title: '{ProductName} Batch Check API',
+      description: 'Read the Batch Check API documentation and see how it works.',
+      link: '/api/service#Relationship%20Queries/BatchCheck',
+    },
   ]}
 />

docs/content/getting-started/perform-list-users.mdx

@@ -213,7 +213,7 @@ With the tuples:
 | ------------------------ | -------- | ------------------------ |
 | group:engineering#member | viewer   | document:1               |
 | group:product#member     | viewer   | document:1               |
-| user:will                | member   | group:engineering#member |
+| user:will                | member   | group:engineering        |
 
 Then calling the List Users API for `document:1` with relation `viewer` of type `group#member` will yield the below response. Note that the `user:will` is not returned, despite being a member of `group:engineering#member` because the `user_filters` does not target the `user` type.
 

docs/content/getting-started/production-best-practices.mdx

@@ -29,7 +29,7 @@ The following list outlines best practices for running OpenFGA in a production e
 
 We recommend:
 
-1. Turn on caching via the flag `--check-query-cache-enabled`. This will reduce latency of requests, but it will increase the staleness of OpenFGA's responses. (The TTL is configurable).
+1. Turn on in-memory caching in Check API via flags. This will reduce latency of requests, but it will increase the staleness of OpenFGA's responses. Please see [Cache Expiration](../interacting/consistency.mdx#cache-expiration) for details on the flags.
 2. Prefer having a small pool of servers with high capacity (memory and CPU cores) instead of a big pool of servers, to increase cache hit ratios and simplify pool management.
 3. Turn on metrics collection via the flags `--metrics-enabled` and `--datastore-metrics-enabled`. This will allow you to debug issues.
 4. Turn on tracing via the flag `--trace-enabled`, but set sampling ratio to a low value, for example `--trace-sample-ratio=0.3`. This will allow you to debug issues without overwhelming the tracing server. However, keep in mind that enabling tracing comes with a slight performance cost.