How to integrate permission checks to your application
In this guide you will learn how Ory Permissions fits into your architecture and how to integrate it into your application. Whether you're building a new application from scratch or adding access control to an existing one, Ory Permissions can help you manage your permissions.
Understand Ory Permissions
In Ory Permissions, relationships and permissions are two key concepts that allow you to manage access control and permissions in your application.
Relationships are facts about entities stored in Ory Permissions. A relationship consists of three elements: an object entity, a relation string, and a subject entity. Relationships represent real relationships between different entities in your application. For example, you might define a relationship between a user and a file to show that the user owns the file.
Permissions are defined in the Ory Permission Language, which is a subset of TypeScript. Permissions are essentially TypeScript functions that return a boolean value based on the relationships in Ory Permissions. These functions allow you to define the access control policies for your application. Permissions can be used to create very fine-grained permissions that can be tailored to the specific needs of your application.
By combining relationships and permissions, you can define complex access control policies that allow you to manage access to resources and data in your application. Ory Permissions allows you to build flexible permission models that can be customized to fit any application need. This means you can create access control policies that are as simple or as complex as you need them to be, while still ensuring that your application remains secure and protected.
Ory Permissions provides features to help manage relationships and permissions in your application. For example, you can define namespaces to organize your entities, and use the Ory Permissions API to create and manage relationships and permissions programmatically.
In the next section, we'll provide an example of how to use relationships and permissions in Ory Permissions to manage access control in your application.
Synchronous authorization flow
It's crucial that all permission checks are performed using Ory Permissions. This means that before any action is taken, the required permission should be checked to ensure that the action is allowed. For instance, when returning the content of a file, the request subject's read permission on the file should be checked first.
Authentication isn't part of the permission check API, but it's a prerequisite for any permission check to be meaningful. One way to implement authentication is to use Ory Identities, which provide a secure and robust authentication system for your application.
Once you authenticated the subject, you can perform permission checks by calling the check method of the OryPermissions client. The check method takes the subject, permission, and object as parameters and returns a boolean value indicating whether the permission is granted or not.
It's up to your permission model what permissions are available and need to be checked. This example assumes that there is a
read permission on the resource's namespace and you created relationships to show whether a user has that read permission.
Please head over to the Permission Model Guide to learn how to create relationships.
Best practices
By following these best practices, you can ensure that your application is secure and that users have access to the resources they need.
Don't cache permission checks
Ory Network provides a low-latency, globally distributed system with appropriate caching, cache invalidation, and other optimizations. You don't need to worry about caching the permission checks in your application. Incorrect caching can lead to security vulnerabilities, so it's best to avoid it altogether.
Perform permission checks in every critical path of the application
Anytime an action is taken that requires a permission check, make sure to perform that check using Ory Permissions. This includes creating, reading, updating, and deleting resources.
Use fine-grained permissions
Ory Permissions allows you to define fine-grained permissions, which can help you enforce the principle of least privilege. This means that you can give users the permissions they need, and nothing more.
Audit permissions
It's important to review and audit permissions to ensure that users just have the access they need. Use Ory Permissions' powerful query capabilities to find and fix any permissions that are no longer necessary.