Configuration Language

OpenFGA’s Configuration Language builds a representation of a system’s authorization model, which informs OpenFGA’s API on the object types in the system and how they relate to each other. The Configuration Language describes the relations possible for an object of a given type and lists the conditions under which one is related to that object. The Configuration Language can be presented in DSL or JSON syntax. The JSON syntax is accepted by the API and closely tracks the language in the Zanzibar paper. The DSL adds syntactic sugar on top of JSON for ease of use, but compiles down to JSON before being sent to OpenFGA’s API. JSON syntax is used to call API directly or through the SDKs, while DSL is used to interact with OpenFGA in the Playground, the CLI, and the IDE extensions for Visual Studio Code and IntelliJ. They can be switched between throughout this documentation. Please familiarize yourself with basic OpenFGA Concepts and How to get started on modeling before starting this guide.

What Does The Configuration Language Look Like?

Below is a sample authorization model. The next sections discuss the basics of the OpenFGA configuration language.

The authorization model describes four types of objects: user, domain, folder and document.The domain type definition has a single relation called member that only allows direct relationships.The folder and document type definitions each have five relations: parent_folder, owner, writer, viewer and can_share.

Direct Relationship Type Restrictions

When used at the beginning of a relation definition, [<string>, <string>, ...] allows direct relationships by the objects of these specified types, for example, [user, user:*, team#member]. The strings can be in one of three formats:

<type>: indicates that tuples relating objects of those types as users can be written. For example, group:marketing can be related if group is in the type restrictions.
<type:*>: indicates that a tuple relating all objects of that type can be written. For example, user:* can be added if user:* is in the type restrictions.
<type>#<relation>: indicates tuples with sets of users related to an object of that type by that particular relation. For example, group:marketing#member can be added if group#member is in the type restrictions.

If no direct relationship type restrictions are specified, direct relationships are disallowed and tuples cannot be written relating other objects of this particular relation with objects of this type.

[<type1>, <type2>, ...] in the OpenFGA DSL translates to this in the OpenFGA API syntax.

For example, below is a snippet of the team type: The team type definition above defines all the relations that users can have with an object of type team. In this example, the relation is member. Because of the [user, team#member] direct relationship type restrictions used, a user in the system can have a direct relationship with the team type as a member for objects of:

type user
the user type bound public access (user:*)
usersets that have a team type and a member relation (e.g. team:product#member)

In the type definition snippet above, anne is a member of team:product if any of the following relationship tuple sets exist:

Anne is directly related to the product team as a member

[{
  "user": "user:anne",
  "relation": "member",
  "object": "team:product"
}]

Everyone (*) is directly related to the product team as a member

[{
  "user": "user:*",
  "relation": "member",
  "object": "team:product"
}]

Members of the contoso team are members of the product team Anne is a member of the contoso team

[{
  "user": "team:contoso#member",
  "relation": "member",
  "object": "team:product"
}, {
  "user": "user:anne",
  "relation": "member",
  "object": "team:contoso"
}]

For more examples, see Modeling Building Blocks: Direct Relationships.

Referencing Other Relations On The Same Object

The same object can also reference other relations. Below is a simplified document type definition: Above, document type definition defines all the relations that users can have with an object of type document. In this case, the relations are editor, viewer and can_rename. The viewer and can_rename relation definitions both reference editor, which is another relation of the same type.

can_rename does not reference the direct relationship type restrictions, which means a user cannot be directly assigned this relation and it must be inherited when the editor relation is assigned. Conversely, the viewer relation allows both direct and indirect relationships using the Union Operator.

In the type definition snippet above, anne is a viewer of document:new-roadmap if any one of the following relationship tuple sets exists:

anne is an editor of document:new-roadmap Anne is an editor of the new-roadmap document

[{
  "user": "user:anne",
  "relation": "editor",
  "object": "document:new-roadmap"
}]

anne is a viewer of document:new-roadmap Anne is a viewer of the new-roadmap document

[{
  "user": "user:anne",
  "relation": "viewer",
  "object": "document:new-roadmap"
}]

anne has a can_rename relationship with document:new-roadmap only if anne has an editor relationship with the document:

anne is an editor of document:new-roadmap Anne is an editor of thew new-roadmap document

[{
  "user": "user:anne",
  "relation": "editor",
  "object": "document:new-roadmap"
}]

For more examples, see Modeling Building Blocks: Concentric Relationships, Modeling: Roles and Permissions and Advanced Modeling: Google Drive. Another set of indirect relationships are made possible by referencing relations to other objects. The syntax is X from Y and requires that:

the other object is related to the current object as Y
the user is related to another object as X

See the authorization model below. The snippet below (taken from the authorization model above) states that viewers of a document are both (a) all users directly assigned the viewer relation and (b) all users who can view the document’s parent folder. In the authorization model above, user:anne is a viewer of document:new-roadmap if any one of the following relationship tuples sets exists:

Anne is a viewer of the parent folder of the new-roadmap document

planning folder is the parent folder of the new-roadmap document
anne is a viewer of the planning folder

[{
  "user": "folder:planning",
  "relation": "parent_folder",
  "object": "document:new-roadmap"
}, {
  "user": "user:anne",
  "relation": "viewer",
  "object": "folder:planning"
}]

Anne is a viewer of the new-roadmap document (direct relationship) anne is a viewer of the new-roadmap document
[{ "user": "user:anne", "relation": "viewer", "object": "document:new-roadmap" }]

Referencing relations on related objects defines transitive implied relationship. If User A is related to Object B as a viewer, and Object B is related to Object C as parent, then User A is related to Object C as viewer. This can indicate that viewers of a folders are viewers of all documents in that folder.

OpenFGA does not allow the referenced relation (the word after from, also called the tupleset) to reference another relation and does not allow non-concrete types (type bound public access (<object_type>:*) or usersets (<object_type>#<relation>)) in its type restrictions; adding them throws a validation error when calling WriteAuthorizationModel.

For more examples, see Modeling: Parent-Child Objects, Advanced Modeling: Google Drive, Advanced Modeling: GitHub, and Advanced Modeling: Entitlements.

The Union Operator

The union operator (or in the DSL, union in the JSON syntax) indicates that a relationship exists if the user is in any of the sets of users (union). In the type definition snippet above, user:anne is a viewer of document:new-roadmap if any of the following conditions are satisfied:

there exists a direct relationship with anne as editor of document:new-roadmap

[{
  "user": "user:anne",
  "relation": "editor",
  "object": "document:new-roadmap"
}]

anne is a viewer of document:new-roadmap

[{
  "user": "user:anne",
  "relation": "viewer",
  "object": "document:new-roadmap"
}]

The above authorization model indicates that a user is related as a viewer if they are in any of the following:

the userset of all users related to the object as “viewer”, indicating that a user can be assigned a direct viewer relation
the userset of all users related to the object as “editor”, indicating that a user who is an editor is also implicitly a viewer

If anne is in at least one of those usersets, meaning anne is either an editor or a viewer, the check on {"user": "user:anne", "relation": "viewer", "object": "document:new-roadmap"} returns {"allowed": true}.

For more examples, see Modeling Building Blocks: Concentric Relationships, Modeling Roles and Permissions and Advanced Modeling: Modeling for IoT.

The Intersection Operator

The intersection operator (and in the DSL, intersection in the JSON syntax) indicates that a relationship exists if the user is in all the sets of users. In the type definition snippet above, user:anne is a viewer of document:new-roadmap if all of the following conditions are satisfied:

anne is an editor of document:new-roadmap

[{
  "user": "user:anne",
  "relation": "editor",
  "object": "document:new-roadmap"
}]

AND

anne is an authorized_user of document:new-roadmap:

[{
  "user": "user:anne",
  "relation": "authorized_user",
  "object": "document:new-roadmap"
}]

The above authorization model indicates that a user is related as a viewer if they are in all of the following:

the userset of all users related to the object as authorized_user
the userset of all users related to the object as editor

anne must be in the intersection of the usersets (meaning both an editor AND an authorized_user) for the check on {"user": "user:anne", "relation": "viewer", "object": "document:new-roadmap"} to return {"allowed": true}.anne is not a viewer for document:new-roadmap if either of the following is true:

anne is not an editor to document:new-roadmap: no relationship tuple of {"user": "user:anne", "relation": "editor", "object": "document:new-roadmap"}
anne is not an authorized_user on the document:new-roadmap: no relationship tuple of {"user": "user:anne", "relation": "authorized_user", "object": "document:new-roadmap"}

For more examples, see Modeling with Multiple Restrictions.

The Exclusion Operator

The exclusion operator (but not in the DSL, difference in the JSON syntax) indicates that a relationship exists if the user is in the base userset but not in the excluded userset. This operator is particularly useful when modeling exclusion or block lists. In the type definition snippet above, user:anne is a viewer of document:new-roadmap if and only if:

anne has a direct relationship as viewer to document:new-roadmap

[{
  "user": "user:anne",
  "relation": "viewer",
  "object": "document:new-roadmap"
}]

AND

anne is not blocked from document:new-roadmap (i.e., the following relationship tuple must not exist):

[{
  "user": "user:anne",
  "relation": "blocked",
  "object": "document:new-roadmap"
}]

For more information, see Modeling: Blocklists.

The authorization model above indicates that a user is related as a viewer if they are in:

the userset of all users related to the object as viewer

but not in:

the userset of all users related to the object as blocked

anne must be both a viewer and not blocked for the check on {"user": "user:anne", "relation": "viewer", "object": "document:new-roadmap"} to return {"allowed": true}.anne is not a viewer for document:new-roadmap if either of the following is true:

anne is not assigned direct relationship as viewer to document:new-roadmap: no relationship tuple of {"user": "user:anne", "relation": "viewer", "object": "document:new-roadmap"}
anne is blocked on the document:new-roadmap {"user": "user:anne", "relation": "blocked", "object": "document:new-roadmap"}

Grouping and nesting operators

You can define complex conditions by using parentheses to group and nest operators. Note that direct relationships can be included in an expression with parentheses.

Conditional relationships

OpenFGA supports conditional relationships, which are only considered if a specific condition is met. You can learn more about Conditional Relationships in the Modeling: Conditional Relationships guide.

Equivalent Zanzibar Concepts

The JSON syntax accepted by the OpenFGA API closely mirrors the syntax represented in the Zanzibar paper. The major modifications are a slight flattening and conversion of keys from snake_case to camelCase.

Zanzibar	OpenFGA JSON	OpenFGA DSL
`this`	`this`	`[<type1>,<type2>]`
`union`	`union`	`or`
`intersection`	`intersection`	`and`
`exclusion`	`difference`	`but not`
`tuple_to_userset`	`tupleToUserset`	`x from y`

The Zanzibar paper presents this example:

name: "doc"
relation { name: "owner" }
relation {
  name: "editor"
  userset_rewrite {
    union {
      child { _this {} }
      child { computed_userset { relation: "owner" } }
}}}
relation {
 name: "viewer"
 userset_rewrite {
  union {
    child { _this {} }
    child { computed_userset { relation: "editor" } }
    child { tuple_to_userset {
      tupleset { relation: "parent" }
      computed_userset {
        object: $TUPLE_USERSET_OBJECT  # parent folder
        relation: "viewer" }}}
}}}

In the OpenFGA DSL, it becomes: In the OpenFGA JSON, it becomes: The following snippet: Results in the following outcome:

The users with a viewer relationship to a certain doc are any of:
- the set of users who are directly related with this doc as viewer
- the set of users who are related to this doc as editor
- the set of users who are related to any object OBJ_1 as viewer, where object OBJ_1 is any object related to this doc as parent (e.g. viewers of this doc’s parent folder, where the parent folder is OBJ_1)

Learn more about Zanzibar at the Zanzibar Academy. Check the following sections for more on how to use the configuration language in modeling authorization.

OpenFGA Concepts

Learn about the OpenFGA Concepts.

Modeling: Getting Started

Learn about how to get started with modeling your permission system in OpenFGA.

Direct Access

Learn about modeling user access to an object.

Getting Started

Modeling Guides

Authorization for Agents

Interacting with the API

Best Practices

Industries

Use Cases

Adopters

Learn

Configuration Language

What Does The Configuration Language Look Like?

Direct Relationship Type Restrictions

Referencing Other Relations On The Same Object

The Union Operator

The Intersection Operator

The Exclusion Operator

Grouping and nesting operators

Conditional relationships

Equivalent Zanzibar Concepts

OpenFGA Concepts

Modeling: Getting Started

Direct Access

​What Does The Configuration Language Look Like?

​Direct Relationship Type Restrictions

​Referencing Other Relations On The Same Object

​Referencing Relations On Related Objects

​The Union Operator

​The Intersection Operator

​The Exclusion Operator

​Grouping and nesting operators

​Conditional relationships

​Equivalent Zanzibar Concepts

​Related Sections

OpenFGA Concepts

Modeling: Getting Started

Direct Access

What Does The Configuration Language Look Like?

Direct Relationship Type Restrictions

Referencing Other Relations On The Same Object

Referencing Relations On Related Objects

The Union Operator

The Intersection Operator

The Exclusion Operator

Grouping and nesting operators

Conditional relationships

Equivalent Zanzibar Concepts

Related Sections