Subjects

In Ory Keto subjects are a recursive polymorphic datatype. They refer to specific subjects by an identifier defined by the application, for example users, or to sets of subjects.

Subject IDs

A subject ID can be any string. The application must map its resources to a constant, unique identifiers. We recommend using UUIDs as they provide a high entropy and therefore are unique identifiers. However, you can also use URLs or opaque tokens as identifiers. Subjects are considered equal when their string representation is equal.

Subject sets

A subject set is the set of all subjects that have a specific relation on an object. They empower Ory Permissions to be as flexible as you need it by defining indirections. They can be used to realize for example RBAC or inheritance of relations. Subject sets themselves can again indirect to subject sets. As a special case, subject sets can also refer to an object by using the empty relation. Effectively, this is interpreted as "any relation, even a non-existent one".

Subject sets also represent all intermediary nodes in the graph of relations.

Basic example

In a basic setup, an application uses the same subject identifiers as it uses internally, for example a constant, unique username like zepatrik or preferably UUIDv4 like 480158d4-0031-4412-9453-1bb0cdf76104.

tip

See this in a real-life example.

Advanced example

Since Ory Permissions can use arbitrary strings as objects, you can encode application data within the object. We strongly discourage this practice. Instead, use a UUID to map application data to Ory Permissions objects.

This is required to ensure:

1. A single source of truth and easy data updates
2. Free choice of encoding (Ory Permissions doesn't allow the : # @ characters)
3. Unlimited data size

For example, this can be used to implement a crude ABAC system by mapping attributes to a subject ID. The application can then define relationships that reflect permissions depending on the value of attributes. It will have to map each request to the subject representing the attributes.

Let's assume the application knows the following mapping between attributes and UUIDs:

c5b6454f-f79c-4a6d-9e1b-b44e04b56009:
  subnet: 192.168.0.0/24
  office_hours: true

Ory Permissions understands the following relationship:

// Allow access to TCP port 22 when the request originates from a specific subnet during office hours
tcp/22#access@c5b6454f-f79c-4a6d-9e1b-b44e04b56009

The application must map every incoming request to a subject string that represents the attributes of the request. Ory Permissions replies with a positive check response depending on the string equality of the requested subject representing the attributes with the known relationships. Ory Permissions doesn't know how to interpret any information stored in relationships. The application must pre-process and map the value to the corresponding UUID.