The Ory Permission Language is a language that allows to configure scalable authorization rules for Ory Network and Ory Open Source.
How Apple broke "Sign in with Apple" with an unannounced and silent redirect
The Ory Permission Language is a language that allows configuring Ory Keto.
Before September 2022 Ory Keto - which powers
Ory Permissions - only supported storing and
checking direct relationships between subjects and objects. As an example,
consider a basic file-sharing service. To track ownership of a file, it stores a
relationship patrik is owner of file secrets.txt. In this domain, it is common
that owners have read and write permissions, but Keto does not know that. The
Ory Permission Language allows one to define such global rules.
Permission checks (e.g., can patrik read secrets.txt) are then answered based
on the stored relationships (e.g., patrik is owner of file secrets.txt) and
the rules defined through the OPL
(e.g.,any owner of a document can also read it).
First, we defined the requirements and scope for the new Ory Permission Language.
Powerful, yet easy to understand and maintain.
The cost of long-term maintenance was the decisive factor because a custom language is the most expressive but requires specialized domain knowledge.
A language that you configure as you grow, and that grows with you.
This includes that new people don't need workshops to understand what is going on, and no refreshment course is needed to change permissions months after you last touched the system.
Excellent editor support as well as an automated way to test changes.
As always the development experience is front & center when new features are designed. If you have any feedback that could help with your work as developer, feel free to share it with the Ory community.
Not Turing complete.
This minimizes room for errors and makes it impossible to generate a code path that exhausts time or space constraints, in line with the Ory software architecture guidelines.
The next step was to come up with proposals and analyze other solutions. Ory Keto is the first open-source implementation of Google Zanzibar but is not the only one. Because the Zanzibar paper is vague in parts, and the system was driven by Google's internal requirements, everyone has a different idea of how to implement the concept of graph-based access control. The concept of global rules was described in the paper, and adopted by all implementations in one way or the other. Therefore we came up with several proposals, including competitors' permission languages, and compared all of them during user interviews.
Being the first open-source Zanzibar implementation, Ory Keto has a vibrant user community. To make sure that we arrive at a user-friendly permission language we had many interviews with community members. During the interviews, we proposed four different permission languages and tasked the interviewees with understanding and extending the rules in each language.
The four languages all described access to documents such that users can be an
owner, editor, or viewer of a document. An owner is also an editor of
a document, and an editor is also a viewer of a document. Furthermore,
documents can be arranged in a hierarchy: if a user is a viewer of a parent
document, they can also view that document.
The original syntax from the Zanzibar paper, which is just the internal abstract syntax tree (AST) presented as Protobuf text format. We included this language as a baseline, and all interviewees found the syntax verbose and confusing.
name: "document"
relation { name: "owner" }
relation {
name: "editor"
userset_rewrite {
union {
child { _this {} }
child { computed_userset { relation: "owner" } }
}
}
}
relation {
name: "viewer"
userset_rewrite {
union {
child { _this {} }
child { computed_userset { relation: "editor" } }
child { tuple_to_userset {
tupleset { relation: "parent" }
computed_userset {
object: $TUPLE_USERSET_OBJECT # parent folder
relation: "viewer"
} }
}
}
}
}
As a second alternative, we used the DSL version of the
Auth0 FGA configuration language.
The language somewhat resembles Python with its concise and
whitespace-significant syntax. In our interviews, we found that people were
confused by missing type annotations and as self syntax (similar to
child { _this {} } from the Zanzibar AST).
type document
relations
define parent as self
define owner as self
define editor as self or owner
define viewer as self or editor or viewer from parent
Next, we introduced a language that uses first-order logic to express permission rules and types to restrict relationships. Our takeaways were that while the types are useful, the logical component was polarizing. Some people struggled with the logical implications, while others loved them.
type user {}
type document {
relation owner, editor, viewer: user
relation parent: document
}
for all document:d, user:u {
u is owner of d => u is editor of d
u is editor of d => u is viewer of d
}
for all document:d, document:p, user:u {
p is parent of d & u is viewer of p => u is viewer of d
}
For the final language, we used the
AuthZed schema language. It
features a type system as well as a declarative syntax. While the interviewees
liked the types, they had trouble grasping the concepts and failed at writing
transitive rules. An example of a transitive rule is parent->viewer, meaning
that you can view a document if you are a viewer of the parent.
definition user {}
definition document {
relation viewer: user
relation editor: user
relation owner: user
relation parent: document
permission view = owner or editor or viewer or parent->viewer
permission edit = owner or editor
permission own = owner
}
From the user interviews and our original requirements, we gathered that our permission language should be self-explanatory and familiar, with good editor support. Linters and unit test frameworks would help the users modify the permission rules with high confidence.
Therefore, we based the Ory Permission Language on TypeScript (more precisely, a non-Turing-complete subset of TypeScript, see the spec of the Ory Permission Language). TypeScript and JavaScript are widely used programming languages that most programmers probably have come in contact with. Further, there is out-of-the-box syntax highlighting, and auto-completion through type declarations in a wide variety of editors and IDEs. This also opens the possibility to unit-test the permission rules with a test runner such as Jest.
Let's look at the example from above written in the Ory Permission Language:
import { Namespace, SubjectSet, Context } from "@ory/permission-namespace-types"
// Namespaces are declared as classes that implement the `Namespace` interface.
class User implements Namespace {
related: { manager: User[] }
}
class Group implements Namespace {
related: {
// The relation types are declared in the TypeScript syntax:
members: (User | Group)[]
}
}
class Folder implements Namespace {
related: {
parents: Folder[]
// SubjectSet<T, "r"> refers to the relation r of namespace T.
viewers: SubjectSet<Group, "members">[]
}
// Permissions are declared separately from relations as functions that take a
// context (containing the subject of a permission check) and that defer the
// decision to either another permission or relation.
permits = {
view: (ctx: Context): boolean =>
this.related.viewers.includes(ctx.subject) ||
this.related.parents.traverse((p) => p.permits.view(ctx)),
}
}
class File implements Namespace {
related: {
parents: (File | Folder)[]
viewers: (User | SubjectSet<Group, "members">)[]
owners: (User | SubjectSet<Group, "members">)[]
}
permits = {
view: (ctx: Context): boolean =>
this.related.viewers.includes(ctx.subject) ||
this.related.parents.traverse((p) => p.permits.view(ctx)) ||
this.related.owners.includes(ctx.subject),
edit: (ctx: Context) => this.related.owners.includes(ctx.subject),
}
}
We carefully defined the Ory Permission Language as a subset of TypeScript that is not Turing-complete and maps well to the original Zanzibar AST. This allows us to re-use all caching and optimization improvements from the Zanzibar paper.
For our implementation, we wrote a custom parser in Go that only accepts the subset that we can handle. You can check out the lexer and parser on GitHub. We also have an extensive suite of tests and a fuzzer to check the correctness and robustness of the parser.
The Ory Permission Language is now part of Ory Keto as well as built into the Ory Network. The best way to get started is to use our guide to defining global permission rules using the Ory Permission Language in combination with the Ory Console, all in your browser.
If you want to chat, be sure to say hi in our community Slack channel and share your experiences with us.