Warrants

   tenant:stark-industries  #  admin  @  user:tony-stark
              |                  |              |
           Resource           Relation       Subject

Each warrant is composed of three core attributes and an optional policy (more on this later):

• Resource – This is the resource the warrant specifies a relationship on. The resource is broken down into a resource_type and a resource_id. The resource_type must refer to a valid resource type defined for the application. The resource_id must be a unique identifier used by the application to identify the resource.
• Relation – This is the relationship the warrant specifies between the resource and the subject. The relation must be one of the defined relations on the referenced resource_type. It is often used to specify an action the warrant will grant the subject the ability to perform on the resource (e.g. editor, viewer, etc.).
• Subject – This is the resource being granted the specified relation. Like the resource, the subject is broken down into a resource_type, and a resource_id, and optionally a relation (to specify a group of subjects). A subject’s resource_type must refer to a valid resource type defined for the application, and its resource_id must be a unique identifier used by the application to identify the resource. While the subject will often times be an individual user or resource, the subject can also specify a group of resources (e.g. in group warrants).
• Policy (optional) – The policy specifies an additional boolean expression to be evaluated at the time of each check/query request. The provided expression can reference arbitrary variables which can be provided in check or query requests as context. Given some context at check/query time, a warrant’s policy must evaluate to true in order for the warrant to be considered a match for the check/query. If a warrant’s resource, relation, and subject attributes do not match the requested check/query or the policy expression evaluates to false, the warrant will not be matched during evaluation of the check/query. The policy attribute can be used to implement a form of attribute-based access control (ABAC).

Here is an example warrant specifying that the subject user:ABC has the relation editor on resource item:123:

{
  "resource_type": "item",
  "resource_id": "123",
  "relation": "editor",
  "subject": {
    "resource_type": "user",
    "resource_id": "ABC"
  }
}

A direct warrant represents a relationship between a resource and a specific subject. For example, we can define a warrant specifying that [user:1] is a [member] of [role:admin]:

{
  "resource_type": "role",
  "resource_id": "admin",
  "relation": "member",
  "subject": {
    "resource_type": "user",
    "resource_id": "1"
  }
}

In some cases, we might need to specify a relationship between a resource and a group of subjects (e.g. [member]s of [role:admin], [manager]s of [tenant:acme], etc). Group warrants are warrants that include the optional relation attribute on the subject. They specify that all resources matching the subject’s resource_type, resource_id, and relation will have the specified relation on the resource. For example, we can define a group warrant specifying that [member]s of [role:admin] are [editor]s of [report:1]:

{
  "resource_type": "report",
  "resource_id": "1",
  "relation": "editor",
  "subject": {
    "resource_type": "role",
    "resource_id": "admin",
    "relation": "member"
  }
}

It’s important to note that resource inheritance rules achieve the same thing as group warrants, but group warrants are a data-first approach. Group warrants are typically used as an exception for certain resources that might have different sets of requirements than the schema. We typically recommend using resource inheritance rules over group warrants because it is easier to manage a single schema than a set of group warrants defined on several different resources.

While FGA is designed to model fine-grained authorization, some use-cases call for more coarse-grained access to individual resources. For example, publicly sharing read privileges on a particular document with all users. Scenarios like this can be modeled using wildcard warrants. A wildcard warrant is a warrant that specifies a wildcard (*) for the subject_id attribute. This means the warrant applies to all subjects of the specified subject_type. Note that group warrants cannot specify a wildcard as the subject_id. Here is an example of a wildcard warrant that grants all users viewer access to document:doc_123:

{
  "resource_type": "document",
  "resource_id": "doc_123",
  "relation": "viewer",
  "subject": {
    "resource_type": "user",
    "resource_id": "*"
  }
}

Warrants can be created directly in the FGA dashboard or programmatically via API. Refer to the Warrants API Reference to learn more about managing Warrants via API.