openfga / openfga.dev

OpenFGA website and documentation

OpenFGA Documentation

About OpenFGA

OpenFGA is an open source Fine-Grained Authorization solution based on Google's Zanzibar. It was created by the Okta FGA team and welcomes community contribution. OpenFGA is designed to make it easy for application builders to quickly add fine-grained authorization to their applications. It offers an HTTP API and has SDKs for programming languages including JavaScript, GoLang and .NET. More SDKs and integrations such as Rego are planned for the future. OpenFGA is designed and optimized for reliability and low latency at a high scale.

About OpenFGA docs

This website is built using Docusaurus, a modern static website generator.

Getting Started

Setup and Installation

Clone the repo locally

Run git clone https://github.com/openfga/openfga.dev.git to clone the repo to your machine.

Setup Git LFS (Large File Storage)

• Follow the instructions here to install git lfs on your system.
• If you haven't done so yet, run git lfs install to set up git lfs for your account.
• Run git lfs pull
• Run git lfs checkout

Currently mp4, webm and svg files are tracked. If you need to track more media formats, run: git lfs track "*.extension"

Install Dependencies

To run the docs locally you will need to first install dependencies:

npm install

Running in Development

You can then run

npm run dev

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Building for Production

To generate a production build

NPM

npm run build # Generated files will be in the ./build directory

To launch a server with the build files, run

npm run serve

You will then be able to browse the documentation at http://localhost:3000/

Docker

Build

To build in development mode

docker build --target development . -t fga-docs-dev

To run in development mode

docker run --init --rm -p 3000:3000 fga-docs-dev

The generated webpages will be available in http://localhost:3000.

Production

To build in production mode

docker build . -t fga-docs

Run

docker run --init --rm -p 3000:80 fga-docs

PR Preview

GitHub Action Deploy PR Preview allows previewing of proposed changes. The URL for the changes can be previewed via

https://openfga.dev/pr-preview/pr-[number]

For example, previewing changes on PR-589 for changes on docs/modeling/public-access is available via

https://openfga.dev/pr-preview/pr-589/docs/modeling/public-access

Contributing

Please review the Contributing Guidelines before sending a PR or opening an issue.

Issue Reporting

If you find a bug or inaccuracy in the documentation content, please report it in this repository's issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. Refer to the security policy for disclosing security issues.

Author

OpenFGA [email protected] (https://openfga.dev)

License

Please refer to https://github.com/openfga/rfcs/blob/main/LICENSE for license information.

openfga.dev's Issues

Update landing page's resource section

For landing page's resource section, we should update the links

1. Instead of Spotify - Authorization in Software → and Apple - Authorization in Software →, use https://authorizationinsoftware.auth0.com/
2. Add in link for Auth0 FGA playground

Swap to the correct openfga swagger file

Currently, we use a temporary swagger file as place holder. We need to update docusaurus.config.js to point to the correct swagger file.

Note that the new swagger file's tag is different. This means we will need to update the swagger file + call to /api/service for the correct API.

Logomark trademark on homepage is cut off

Current:

🕵️ 🕵️ 🕵️

🕵️ 🕵️ 🕵️

This is probably my fault in some way, I'll fix it.

Delete endpoint in API page has old styles

👀

These endpoints should have the same styling as the others, at least, for consistency's sake.

object is not highlighted in getting started

In https://openfga.dev/docs/modeling/getting-started#02-list-the-object-types, the objects are not highlighted in blue. It is displayed as normal text instead.

fix the landing page's "Getting Started" command

The command curl -O https://openfga.com/docker-compose.yml needs to be changed to curl -O https://openfga.dev/docker-compose.yaml.

In iPhone SE, search bar covers part of the logo

For iPhone SE (375x667), the search bar covers part of the logo

See image below:

Add design document for immutable authorization models

Cleanup log during `npm run build` [H]

Prism log such as

PROISM <ref *1> {
  util: {
    encode: [Function: encode],
    type: [Function: type],
    objId: [Function: objId],
    clone: [Function: deepClone],
    getLanguage: [Function: getLanguage],
    setLanguage: [Function: setLanguage],
    isActive: [Function: isActive]
  },
...

is spawned during npm run build. Root cause is https://github.com/openfga/openfga.dev/blob/main/src/utils/prism-openfga-dsl.js#L20

Update definition of `store`

It is possible to have more than 1 store. Thus, the definition of store as defined in https://openfga.dev/docs/concepts#what-is-a-store is incorrect.

Playground banner not including playground name for introduction section

If playground banner is specified, the playground name is not included in the introduction section.

Search boxes resize in mobile browser

In mobile browser (happened with both iPhone 12 and Samsung s20), the search bar resizes when clicking on it initially. This happens on both landing page as well as docs page search bar.

See following video capture:

Screen.Recording.2022-06-17.at.10.22.56.AM.mov

Remove analytics from website

There should be no analytics enabled.

Raster image for metadata

As discussed in #58 (comment), we need to create raster image for metadata.

I looked deeper into the standard to refresh my memory, and it looks like [only raster images are supported](https://indieweb.org/The-Open-Graph-protocol#Does_not_support_SVG_images).

Maybe we should make another task for this, and I'll

make an image
place image in the right folder
add the appropriate og:image tag

Styling and color for "Get involved" in landing page's feature section

The styling and color (green) for "Get Involved" heading suggests that it is a clickable link. Either update color or add a proper link to it.

broken link in getting-started#02-list-the-object-types

Bad link for OpenFGA Configuration Language. Should point to /docs/configuration-language.

Screen.Recording.2022-06-16.at.11.40.05.AM.mov

Update docusaurus config and build script for custom domain

Since we are using custom domain instead of hosting page off https://openfga.github.io/, the baseURL will now be / instead of /openfga.dev/. We need to update build script to reflect this.

Search bar is not styled for mobile

🕵️ 😬

Configuration language page's equivalent zanzibar concepts section to only show DSL

This is left over from previous review.
Currently, configuration language page's equivalent zanzibar concepts section has a line
In the OpenFGA DSL, it would become:

However, the authorization model viewer below shows both DSL and JSON.
It will be better if we extend authorization model to allow specifying to show only either DSL or JSON.

Style a 404 page for broken routes

While we might want to put some thought into the overall design eventually, as a first step we could pad the Page Not Found message so that the error page feels like it follows the same conventions as the rest of the site's content.

Fix meta description so that embeds are properly formatted

Currently we have a placeholder description that will show up if someone copy/pastes the URL into Discord (and likely also in Twitter, Slack, etc).

We should audit this and craft the right meta data so that the project logo and description show up correctly.

Side note: the title is also repeating needlessly on the homepage.

Remove playground pages

The playground pages should be removed. Instead, references should link directly to the playground pages.

Add pattern animation with fallback to the Hero Header

We currently use a basic SVG for the OpenFGA pattern, but have an animated video available.

Add in the video in the correct format/implementation with a fallback to the svg

DSL should be syntax highlighted

As a user reading snippets of the OpenFGA domain specific language, I want syntax highlighting to help me learn and differentiate between system words (type/relations/define/self/as/from/and/or/but/not) and user words.

Current state:

Style codeblocks in expandable sections in docs

Some expandable sections in the docs that have isolated codeblocks appear to have extra padding above and below the codeblocks. These might look better if they have consistent padding (eg, 1rem on all sides).

Viewport scale is not set

We probably need to add something like:

<meta name="viewport" content="width=device-width, initial-scale=1">

Update Link to "Join us on Github" in introduction

The following link in landing page should point to https://github.com/openfga

Update landing page's link to Public Roadmap

Should link to https://github.com/orgs/openfga/projects/1 instead of https://github.com/orgs/openfga/projects

fix: http & grpc configuration

Fix documentation for the openfga configuration changed here: https://github.com/openfga/openfga/pull/75/files

Reorganize page so that breadcrumb will work properly

Currently, clicking on breadcrumb will not lead you to the section. Root cause is that the overview file exists as a separate page instead of embedded them in the category.

Table of Contents links have conflict between hover and active states

The links in the doc's section's table of contents component have a conflicting style between '*--active' styling classes and ':hover' rules. This leads to a flash of white (the intended hover colour) before the link turns grey again.

While they might appear to be working properly at a glance, hovering your cursor for more than a few moments reveals the issue.

Unable to click menu button for browser window dimension 360x670

In mobile browser of dimension 360x670, clicking the menu button shows a dark screen with no text.

See screen capture below:

Screen.Recording.2022-06-15.at.7.03.26.PM.mov

Add page for creating authorization model with SDK

This page should be before after "Create a Store" and before "Update the Relationship Tuples".

Make sure it has the same model (i.e., with "reader", "writer" and "owner") as the "Update relationship tuples", "Perform a Check" and "Integrate within a Framework" pages.

Update button link to github.com/openfga

Previously, it is pointing to github.com/openfga/openfga

Update landing page's quick start image's docker instruction [H]

Should be

docker pull openfga/openfga
docker run -p 8080:8080 openfga/openfga run

to match with the changes in openfga's README

feat: update documentation on configuration to point to dynamically generated file

Currently, the table in https://openfga.dev/docs/getting-started/setup-openfga#configuring-the-server is coded statically. Ideally, this should be generated dynamically from the artifacts of https://github.com/openfga/openfga so that there is no mistmatch between the two.

/api/service page API does not scale well in mobile browser

Page https://openfga.dev/api/service does not scale well in mobile browser.

See following image for details.

Create redirect from '/docs' to 'intro/authorization-and-openfga'

As a reader, I should be to have an easy remember address that link to the docs directly.

Update authorization model's syntax transformer component to use openfga one

Use the published npm from https://github.com/openfga/syntax-transformer instead of doing our own transformation. This also involves updating the syntax name to a cleaner name.

Overshooting when clicking on heading

Clicking on heading will overshot and skip over the heading line. See below:

Screen.Recording.2022-06-09.at.3.29.38.PM.mov

github check action not running external pull request

Pull request from non openfga repo did not trigger github check action. Consequently, Run Checks, markdown-link-check and markdown-link-check-md did not run and is stale.

Missing styling from details and summary section

The "Details" and "Summary" section seems to have incorrect stying

FIx quickstart image to correct 'hardcoded' url

As a user, I want the url provided to resolve to the correct docker-compose file that will allow me to install OpenFGA

Current image:

Fix jank when clicking through Tabbed Viewers

The viewport bounces around when clicking through the tabbed code views:

Screen.Recording.2022-06-14.at.11.40.28.AM.mov

Remove unused import in FeaturesSection

See the following check

Typo in Entitlement page

The section "03-updating-the-authorization-model" has typo.
It should read plan:y instead of play:y.

Visited links show as green in the right table of content

Table of content in the right sidebar has incorrect styling.
The visited link, instead of current section, show as green color.

setup-openfga page's table does not fit into page width

The page setup-openfga has a table that does not fit into page width. Ideally, this should fit into page width

Screen.Recording.2022-06-08.at.5.56.35.PM.mov

Github page's CNAME is lost when github page is deployed

Currently, after each push to main, the github page's CNAME is lost and require manual re-add.

Double slash in URL name lead to page not found

The link https://openfga.dev// shows 404 page not found error.
Note that this may require a higher level fix than in Docusaurus as https://docusaurus.io// also fails.