Contextual Tuples
Contextual tuples are special relationship tuples that exist temporarily within a specific API request. Unlike regular relationship tuples stored in the database, contextual tuples are provided when making authorization queries and are valid only for that particular request.
How Contextual Tuples Work
When making requests to Check, BatchCheck, ListObjects, ListUsers and Expand you can include contextual tuples in the request. These tuples are treated as if they were actual stored tuples during the evaluation of that request but are not persisted to the database and will not affect other requests.
Common Use Cases
There are three main use cases for contextual tuples:
-
When you want to avoid synchronizing data to OpenFGA. This is a powerful use case, as it allows using OpenFGA in a hybrid mode, with some data written to the database and other data obtained before making an authorization query. A good example is using user group memberships from an identity token issued by an identity provider. Note that while it's possible to provide all data using contextual tuples without storing any data, this approach wouldn't leverage the main benefit of the Zanzibar approach: avoiding the need to look up all data required for authorization decisions.
-
When a user has multiple relationships with the same object, and you want to specify which relationship to consider. For example, if a user belongs to multiple organizations but is logged into only one of them, you can use contextual tuples to specify which organization to consider.
-
When using information that's only available at runtime, such as the current time or the user's location. This scenario is better served with Conditional Relationships.
Important Considerations
- Contextual tuples are ephemeral and exist only for the duration of the request.
- When a contextual tuple is sent, and a tuple with the same user, relation and object is in the database - the one in context takes precedence and the one in the DB is ignored.
- Contextual tuples are validated using the same authorization model rules as stored tuples.
- There is currently a limit of 100 contextual tuples per request.
- While token claims can be used for contextual tuples, access will continue until token expiration even if the underlying claims (like group membership) change.