Skip to main content

Conditions

Overview​

Conditions allow you to model more complex authorization modeling scenarios involving attributes and can be used to represent some Attribute-based Access Control (ABAC) policies. Take a look at the Conditions and Conditional Relationship Tuples concepts for a quick overview.

There are various use cases where Conditions can be helpful. These include, but are not limited to:

For more information and background context on why we added this feature, please see our blog post on Conditional Relationship Tuples for OpenFGA.

Defining conditions in models​

For this example we'll use the following authorization model to demonstrate a temporal based access policy. Namely, a user can view a document if and only if they have been granted the viewer relationship AND their non-expired grant policy is met.

model
  schema 1.1

type user

type document
  relations
    define viewer: [user with non_expired_grant]

condition non_expired_grant(current_time: timestamp, grant_time: timestamp, grant_duration: duration) {
  current_time < grant_time + grant_duration
}
note

The type restriction for document#viewer requires that any user of type user that is written in the relationship tuple must be accompanied by the non_expired_grant condition. This is denoted by the user with non_expired_grant specification.

Write the model to the FGA store:


const { authorization_model_id: id } = await fgaClient.writeAuthorizationModel({
  "schema_version": "1.1",
  "type_definitions": [
    {
      "type": "user"
    },
    {
      "type": "document",
      "relations": {
        "viewer": {
          "this": {}
        }
      },
      "metadata": {
        "relations": {
          "viewer": {
            "directly_related_user_types": [
              {
                "type": "user",
                "condition": "non_expired_grant"
              }
            ]
          }
        }
      }
    }
  ],
  "conditions": {
    "non_expired_grant": {
      "name": "non_expired_grant",
      "expression": "current_time < grant_time + grant_duration",
      "parameters": {
        "current_time": {
          "type_name": "TYPE_NAME_TIMESTAMP"
        },
        "grant_duration": {
          "type_name": "TYPE_NAME_DURATION"
        },
        "grant_time": {
          "type_name": "TYPE_NAME_TIMESTAMP"
        }
      }
    }
  }
});
// id = "01HVMMBCMGZNT3SED4Z17ECXCA"

Writing conditional relationship tuples​

Using the model above, when we Write relationship tuples to the OpenFGA store, then any document#viewer relationship with user objects must be accompanied by the condition non_expired_grant because the type restriction requires it.

For example, we can give user:anne viewer access to document:1 for 10 minutes by writing the following relationship tuple:


const options = {
  authorizationModelId: "01HVMMBCMGZNT3SED4Z17ECXCA",
};

await fgaClient.write({
  writes: [
      {"user":"user:anne","relation":"viewer","object":"document:1","condition":{"name":"non_expired_grant","context":{"grant_time":"2023-01-01T00:00:00Z","grant_duration":"10m"}}}
  ],
}, options);

Queries with condition context​

Now that we have written a Conditional Relationship Tuple, we can query OpenFGA using the Check API to see if user:anne has viewer access to document:1 under certain conditions/context. That is, user:anne should only have access if the current timestamp is less than the grant timestamp (e.g. the time which the tuple was written) plus the duration of the grant (10 minutes). If the current timestamp is less than, then you'll get a permissive decision. For example,


// Run a check
const { allowed } = await fgaClient.check({
    user: 'user:anne',
    relation: 'viewer',
    object: 'document:1',
    context: {"current_time":"2023-01-01T00:09:50Z"}