> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fga.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Modeling User Groups

> Adding users to groups and granting group members access to an object

To add users to groups and grant groups access to an [object](https://docs.fga.dev/fga-concepts.md#what-is-an-object) using [Auth0 FGA](https://docs.fga.dev/fga.md).

**When to use**

Relationship tuples can specify that an entire group has a relation to an object, which is helpful when you want to encompass a set of users with the same relation to an object. For example:

* Grant `viewer` access to a group of `engineers` in `roadmap.doc`
* Create a `block_list` of `members` who can't access a `document`
* Sharing a `document` with a `team`
* Granting `viewer` access to a `photo` to `followers` only
* Making a `file` viewable for all `users` within an `organization`
* Restricting access from or to `users` in a certain `locale`

## Before you start

Familiarize yourself with the [Auth0 FGA Concepts](https://docs.fga.dev/fga-concepts.md).

<details>
  <summary>Assume you have the following [authorization model](https://docs.fga.dev/fga-concepts.md#what-is-an-authorization-model).\
  : you have an *[object](https://docs.fga.dev/fga-concepts.md#what-is-an-object)* called `document` that users can relate to as an `editor`.</summary>

  ***

  In addition, you will need to know the following:

  ### Direct Access

  You need to know how to create an authorization model and a relationship tuple to grant a user access to an object. To learn more, see [direct access](https://docs.fga.dev/modeling/basics/modeling-basics.md).

  ### Auth0 FGA Concepts

  * A [Type](https://docs.fga.dev/fga-concepts.md#what-is-a-type): a class of objects that have similar characteristics.
  * A [User](https://docs.fga.dev/fga-concepts.md#what-is-a-user): an entity in the system that can be related to an object.
  * A [Relation](https://docs.fga.dev/fga-concepts.md#what-is-a-relation): a string defined in the type definition of an authorization model that defines the possibility of a relationship between an object of the same type as the type definition and a user in the system.
  * An [Object](https://docs.fga.dev/fga-concepts.md#what-is-an-object): represents an entity in the system. Users' relationships to it can be defined with relationship tuples and the authorization model.
  * A [Relationship Tuple](https://docs.fga.dev/fga-concepts.md#what-is-a-relationship-tuple): a grouping consisting of a user, a relation and an object stored in Auth0 FGA.
</details>

[The Playground
Try this guide out on the Auth0 FGA Playground](https://play.fga.dev/)

## Step By Step

There are possible use cases where a group of users have a certain role on or permission to an object. For example, `members` of a certain `team` could have an `editor` relation to a certain `document`.

To represent this in Auth0 FGA:

1. Introduce the concept of a `team` to the authorization model. [→](#step-1)
2. Add users as `members` to the `team`. [→](#step-2)
3. Assign the `team` members a relation to an object. [→](#step-3)
4. Check an individual member's access to the object. [→](#step-4)

### 01. Introduce the concept of a team to the authorization model

First, define the *[object](https://docs.fga.dev/fga-concepts.md#what-is-an-object)* `team` in your authorization model. In this use case, a `team` can have `member`s, so you make the following changes to the authorization model:

### 02. Add users as members to the team

You can now assign *[users](https://docs.fga.dev/fga-concepts.md#what-is-a-user)* as `member`s of `team`s. Create a new *[relationship tuple](https://docs.fga.dev/fga-concepts.md#what-is-a-relationship-tuple)* that states `user:alice` is a member of `team:writers`.

### 03. Assign the team members a relation to an object

To represent groups, use the `type:object_id#relation` format, which represents the set of users related to the `type:object_id` as a certain relation. For example, `team:writers#members` represents the set of users related to the `team:writers` object as `member`s.

In order to assign `member`s of a `team` a relation to a `document`, create the following relationship tuple stating that members of `team:writers` are editors of `document:meeting_notes.doc`.

### 04. Check an individual member's access to an object

Now that you have:

* a relationship tuple indicating that `alice` is a `member` of `team:writers`
* a relationship tuple indicating that `members` of `team:writers` are editors of `document:meeting_notes.doc`

The \*[check](https://docs.fga.dev/fga-concepts.md#what-is-a-check-request)\ `is alice an editor of document:meeting_notes.doc` returns the following:

The chain of resolution is:

* `alice` is `member` of `team:writers`
* `member`s of `team:writers` are `editor`s of `document:meeting_notes`
* therefore, `alice` is `editor` of `document:meeting_notes`

> [!WARNING]
>
> **Note:** When creating relationship tuples for Auth0 FGA,  use unique ids for each object and user in your application domain. This example uses first names and simple ids as a suggested example.

## Related Sections

Check the following sections for more information on user groups.

[Managing Group Membership
Learn how to add and remove users from groups](https://docs.fga.dev/writing-data/managing-group-membership.md)

[Modeling Google Drive
See how User Groups can be used to share documents within a domain in the Google Drive use-case.](https://docs.fga.dev/modeling/advanced/use-cases/gdrive.md#02-organization-permissions)

[Modeling GitHub
Granting teams permissions to a repo in the GitHub use-case.](https://docs.fga.dev/modeling/advanced/use-cases/github.md#02-permissions-for-teams-in-an-org)