> ## 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.

# Use Token Claims As Contextual Tuples

> Using identity token claims to define contextual relations

Contextual Tuples allow authorization checks that depend on dynamic or contextual relationships that have not been written to the Auth0 FGA store, enabling some Attribute Based Access Control (ABAC) use cases.

To enable more ABAC use-cases that rely on specific attributes and conditions, you can also use Auth0 FGA\`s [conditions](https://docs.fga.dev/modeling/basics/conditions.md).

## Before You Start

To follow this guide, familiarize yourself with the following [Auth0 FGA Concepts](https://docs.fga.dev/fga-concepts.md):

* A [Relation](https://docs.fga.dev/fga-concepts.md#what-is-a-relation): is 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.
* A [Check Request](https://docs.fga.dev/fga-concepts.md#what-is-a-check-request): is a call to the Auth0 FGA check endpoint that returns whether the user has a certain relationship with an object.
* 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

## User Directories, Identity Tokens, And Relationships

User directories store user information that's accessed when making authorization decisions, like the group the user belongs to, their roles, or their department. The natural way to use those relationships in a Relationship-Based Access Control system like Auth0 FGA is to create tuples for each relation. However, implementing a synchronization mechanism to keep the user directory data up to date with tuples in the store can be challenging.

When applications implement authentication using an OIDC authorization service, they receive an ID Token or an Access token, with certain claims that can be customized based on the application's needs. Instead of writing tuples to the Auth0 FGA, you can use the content of the token in Contextual Tuples to make authorization checks, understanding that, if those relationships change while the token has not expired, users will still get access to the resources the content of the token entitled them to.

## Example

In this example, the application uses the following authorization model, in which documents can be viewed by members of a group:

When a group is added as a viewer of a document, the application writes tuples like those below:

Let's assume that the Access Token the application receives has a list of the groups the user belongs to:

```json theme={null}
{
  "iss": "https://id.company.com",
  "sub": "6b0b14af-59dc-4ff3-a46f-ad351f428726",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1516239022,
  "azp" : "yz54KAoW1KGFAUU982CEUqZgxGIdrpgg",
  "groups": ["marketing", "everyone"]
}
```

When making a authorization check, the application uses the `groups` claim in the token and adds contextual tuple for each group, indicating that the user is a member of that group:

The authorization check returns `allowed = true`, as there's a stored tuple saying that members of the `marketing` group are viewers of the `product-launch` document, and there's a contextual tuple indicating that the user is a member of the `marketing` group.

> [!WARNING]
>
> **Warning**
>
> Contextual tuples:
>
> * Do not persist in the store.
>
> * Are only supported on the [Check API endpoint](https://docs.fga.dev/api/service/relationship-queries/check.md), [ListObjects API endpoint](https://docs.fga.dev/api/service/relationship-queries/list-objects.md) and [ListUsers API endpoint](https://docs.fga.dev/api/service/relationship-queries/list-users.md). They are not supported on read, expand, or other endpoints.
>
> * If you use the [Read Changes API endpoint](https://docs.fga.dev/api/service/relationship-tuples/read-changes.md) to build a permission aware search index, it may be difficult to account for contextual tuples.

## Related Sections

Check the following sections for more on how user contextual tuples can be used.

[Contextual and Time-Based Authorization
Learn how to authorize access that depends on dynamic or contextual criteria.](https://docs.fga.dev/modeling/basics/contextual-time-based-authorization.md)

[Authorization Through Organization Context
Learn to model and authorize when a user belongs to multiple organizations.](https://docs.fga.dev/modeling/basics/organization-context-authorization.md)

[Conditions
Learn to model requring dynamic attributes.](https://docs.fga.dev/modeling/basics/conditions.md)

[Auth0 FGA API
Details on the Check API in the Auth0 FGA reference guide.](https://docs.fga.dev/api/service/relationship-queries/check.md)