Direct Relationships

In this guide you’ll learn how to model relationships that may or may not be assigned directly to individual users.

Before you start

To better understand this guide, you should be familiar with some Auth0 FGA Concepts and know how to develop the things listed below.

What are direct relationships?

Direct relationships are relationships where a user has a relationship to an object that is not dependent on any other relationship they have with that object. When checking for a relationship, a direct relationship exists if a relationship tuple is present in the system with the exact same object and relation that were in the query and where the user is one of:

the same user ID as that in the query
type bound public access (<type>:*)
a set of users that contains the user ID present in the query

Enable or disable direct relationships

Direct relationships can be enabled for a specific relation on an object type by adding direct relationship type restrictions from that relation’s definition. Likewise, they can be disabled by removing the direct relationship type restrictions.

The authorization model describes two object types: document and team.The document type definition has two relations, editor and viewer. Both relations allow a direct relationship; viewer also allows an indirect relationship through editor.In the team type definition, there is a single member relation that only allows direct relationships.

How it affects your system

To illustrate the effect enabling or disabling direct relationships on a specific relation has, we’ll investigate several situations.

1. With direct relationships enabled

Let us start with the authorization model we had above: Now choose the type of relation to see how it affects your system:

Direct User
Type Bound Public Access
Userset
Indirect Relationship

Assume you have a tuple that states that Anne is a viewer of document:planning

[
  {
    "user": "user:anne",
    "relation": "viewer",
    "object": "document:planning"
  }
]

Now if we do a check request to see if Anne can view the planning document, we will get a response of {"allowed": true}.This is because:

There is a relationship tuple specifying that Anne has a viewer relationship with document:planning.
Direct relationships are allowed in the viewer relation definition in the document type definition.

Assume you have a type bound public access tuple where everyone of type user is a viewer of document:planning (In other words, the document is public)

[
  {
    "user": "user:*",
    "relation": "viewer",
    "object": "document:planning"
  }
]

Now if we do a check request to see if Beth can view the planning document, we will get a response of {"allowed": true}.This is because:

There is a relationship tuple specifying that everyone of type user has a viewer relationship with document:planning.
Direct relationships are allowed in the viewer relation definition in the document type definition.

Note: Even though the relationship tuple stored in the system does not specify the user (beth), this is still considered a direct relationship.

Usersets are the third way direct relationships apply, we will see how in this section.Assume you have two relationship tuples:

Charlie is a member of the product team.
Members of the product team are viewers of the planning document.

[
  {
    "user": "user:charlie",
    "relation": "member",
    "object": "team:product"
  },
  {
    "user": "team:product#member",
    "relation": "viewer",
    "object": "document:planning"
  }
]

Note that these two relationship tuples are specifying that:

user:charlie is a member of team:product.
any member of team:product is a viewer of document:planning.
- Note that this second relationship tuple is specifying that the members of the team have viewer access, and not the team object itself.

Now if we do a check request to see if charlie can view the planning document, we will get a response of {"allowed": true}.This is because:

Charlie is a member of the product team.
There is a relationship tuple specifying that all members of the product team have a viewer relationship with document:planning.
Direct relationships are allowed in the viewer relation definition in the document type definition.

Note that this is still considered a direct relationship no matter how many resolutions occur on the usersets until the user is found.For example, if our relationship tuples were the following relationship tuples:

Dany is a member of the product leads team.
Members of the product leads team are members of the product team.
Members of the product team are members of the contoso team.
Members of the contoso team are viewers of the planning document.

[
  {
    "user": "user:dany",
    "relation": "member",
    "object": "team:product-leads"
  },
  {
    "user": "team:product-leads#member",
    "relation": "member",
    "object": "team:product"
  },
  {
    "user": "team:product#member",
    "relation": "member",
    "object": "team:contoso"
  },
  {
    "user": "team:contoso#member",
    "relation": "viewer",
    "object": "document:planning"
  }
]

A subsequent check request to see if Dany can view the planning document will still return a response of {"allowed": true}.

Note: Even though the relationship tuple stored in the system does not specify the user (charlie or dany), this is still considered a direct relationship.

Here we will cover one example of an indirect relationship in order to see how they differ from direct relationships.With the same authorization model we have above, assume there is a relationship tuple that specifies that Emily is an editor of document:planning.

[
  {
    "user": "user:emily",
    "relation": "editor",
    "object": "document:planning"
  }
]

A subsequent check request to see if emily can view the planning document will still return a response of {"allowed": true}.This is because:

Emily is an editor of the planning document.
The authorization model specified that anyone who is an editor on a document is also a viewer on that document.

In this case, there is NO direct viewer relationship between Emily and the planning document. The only viewer relationship that exists is implied because Emily is an editor and the authorization model specified that any document’s editor is that document’s viewer.

2. With direct relationships disabled

In this section, we will investigate the effect of disabling direct relationships on the document’s viewer relation.

Notice that in this updated authorization model, the direct relationship keyword has been removed from the document’s viewer relation definition.

Now choose the type of relation to see how it affects your system:

Direct User
Everyone
Userset
Indirect Relationship

Assume you have a tuple that states that Fred is a viewer of document:planning

[
  {
    "user": "user:fred",
    "relation": "viewer",
    "object": "document:planning"
  }
]

Now if we do a check request to see if Fred can view the planning document, we will get a response of {"allowed": false}.This is because:

Even though there is a relationship tuple specifying that Fred has a viewer relationship with document:planning.
Direct relationships are NOT allowed in the viewer relation definition in the document type definition.

You will see the same behaviour with a relationship tuple specifying everyone of type user as the user.Assume you have a tuple that states that everyone of type user is a viewer of document:planning.

[
  {
    "user": "user:*",
    "relation": "viewer",
    "object": "document:planning"
  }
]

Now if we do a check request to see if Gabriel can view the planning document, we will get a response of {"allowed": false}.This is because:

Even though there is a relationship tuple specifying that everyone has a viewer relationship with document:planning.
Direct relationships are NOT allowed in the viewer relation definition in the document type definition.

The same logic applies to usersets.Assume you have two relationship tuples:

Henry is a member of the product team.
Members of the product team are viewers of the planning document.

[
  {
    "user": "user:henry",
    "relation": "member",
    "object": "team:product"
  },
  {
    "user": "team:product#member",
    "relation": "viewer",
    "object": "document:planning"
  }
]

Now if we do a check request to see if Henry can view the planning document, we will get a response of {"allowed": false}.This is because although:

Henry is a member of the product team.
There is a relationship tuple specifying that all members of the product team have a viewer relationship with document:planning.

Direct relationships are NOT allowed in the viewer relation definition in the document type definition.

Indirect relationships are not affected by disabling a direct relationship on a certain relation.Assume there is a relationship tuple that specifies that Ingred is an editor of document:planning.

[
  {
    "user": "user:ingred",
    "relation": "editor",
    "object": "document:planning"
  }
]

A subsequent check request to see if Ingred can view the planning document will still return a response of {"allowed": true}.

Introduction to Auth0 FGA

Permissions Index

FGA Dashboard

Define your authorization model

Write Your Authorization Data

Add Authorization To Your API

Auth0 Relationship Sync

Advanced Modeling

Deprecation Notices & Migrations

Before you start

What are direct relationships?

Enable or disable direct relationships

How it affects your system

1. With direct relationships enabled

2. With direct relationships disabled

​Before you start

​What are direct relationships?

​Enable or disable direct relationships

​How it affects your system

​1. With direct relationships enabled

​2. With direct relationships disabled

​Related Sections

Before you start

What are direct relationships?

Enable or disable direct relationships

How it affects your system

1. With direct relationships enabled

2. With direct relationships disabled

Related Sections