From bd694734558a402ccf0c6e78ac9d186813a9693c Mon Sep 17 00:00:00 2001 From: Nikolas Burk Date: Tue, 20 May 2025 08:56:45 +0200 Subject: [PATCH 1/3] add page for permit client extension --- .../140-shared-extesions/100-permit-rbac.mdx | 8 ++++++++ .../index.mdx} | 1 + 2 files changed, 9 insertions(+) create mode 100644 content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/100-permit-rbac.mdx rename content/200-orm/200-prisma-client/300-client-extensions/{140-shared-extensions.mdx => 140-shared-extesions/index.mdx} (99%) diff --git a/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/100-permit-rbac.mdx b/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/100-permit-rbac.mdx new file mode 100644 index 0000000000..a1a9317b25 --- /dev/null +++ b/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/100-permit-rbac.mdx @@ -0,0 +1,8 @@ +--- +title: 'RBAC (Permit)' +metaTitle: '' +metaDescription: '' +toc_max_heading_level: 4 +--- + +_add content about the Permit Client extension here_ \ No newline at end of file diff --git a/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extensions.mdx b/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/index.mdx similarity index 99% rename from content/200-orm/200-prisma-client/300-client-extensions/140-shared-extensions.mdx rename to content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/index.mdx index 88922a36dc..a8f577ad98 100644 --- a/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extensions.mdx +++ b/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/index.mdx @@ -151,3 +151,4 @@ export default Prisma.defineExtension((client) => { ### Advanced type safety: type utilities for defining generic extensions You can improve the type-safety of your shared extensions using [type utilities](/orm/prisma-client/client-extensions/type-utilities). +, \ No newline at end of file From 336f1aaa4231144f65c468835906e264d7daf0fa Mon Sep 17 00:00:00 2001 From: Nikolas Date: Mon, 26 May 2025 10:51:08 +0200 Subject: [PATCH 2/3] Update content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/index.mdx Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> --- .../300-client-extensions/140-shared-extesions/index.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/index.mdx b/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/index.mdx index a8f577ad98..a895239ff5 100644 --- a/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/index.mdx +++ b/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/index.mdx @@ -150,5 +150,4 @@ export default Prisma.defineExtension((client) => { ### Advanced type safety: type utilities for defining generic extensions -You can improve the type-safety of your shared extensions using [type utilities](/orm/prisma-client/client-extensions/type-utilities). -, \ No newline at end of file +You can improve the type-safety of your shared extensions using [type utilities](/orm/prisma-client/client-extensions/type-utilities). \ No newline at end of file From a0691e3da2f4964e61ee8884742cb5fb91c13cc5 Mon Sep 17 00:00:00 2001 From: Gabriel Manor Date: Tue, 24 Jun 2025 10:59:02 +0300 Subject: [PATCH 3/3] Permit.io Docs (#6962) * Initial Version * Update content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/100-permit-rbac.mdx * Update content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/100-permit-rbac.mdx --------- Co-authored-by: Nikolas --- .../140-shared-extesions/100-permit-rbac.mdx | 211 +++++++++++++++++- 1 file changed, 208 insertions(+), 3 deletions(-) diff --git a/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/100-permit-rbac.mdx b/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/100-permit-rbac.mdx index a1a9317b25..3c5501d9d4 100644 --- a/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/100-permit-rbac.mdx +++ b/content/200-orm/200-prisma-client/300-client-extensions/140-shared-extesions/100-permit-rbac.mdx @@ -1,8 +1,213 @@ --- -title: 'RBAC (Permit)' +title: 'Fine-Grained Authorization (Permit)' metaTitle: '' -metaDescription: '' +metaDescription: 'Learn how to implement RBAC, ABAC, and ReBAC authorization in your Prisma applications' toc_max_heading_level: 4 --- -_add content about the Permit Client extension here_ \ No newline at end of file + + +Database operations often require careful control over who can access or modify which data. While Prisma ORM excels at data modeling and database access, it doesn't include built-in authorization capabilities. This guide shows how to implement fine-grained authorization in your Prisma applications using the `@permitio/permit-prisma` extension. + +Fine-grained authorization (FGA) provides detailed and precise control over what data users can access or modify at a granular level. Without proper authorization, your application might expose sensitive data or allow unauthorized modifications, creating security vulnerabilities. + +## Access control models + +This extension supports three access control models from Permit.io: + +### Role-based Access Control (RBAC) + +**What it is**: Users are assigned roles (Admin, Editor, Viewer) with predefined permissions to perform actions on resource types. + +**Example**: An "Editor" role can update any document in the system. + +**Best for**: Simple permission structures where access is determined by job function or user level. + +### Attribute-Based Access Control (ABAC) + +**What it is**: Access decisions based on attributes of users, resources, or environment. + +**Examples**: + +- Allow access if `user.department == document.department` +- Allow updates if `document.status == "DRAFT"` + +**How it works with the extension**: When `enableAttributeSync` is on, resource attributes are automatically synced to Permit.io for policy evaluation. + +**Best for**: Dynamic rules that depend on context or data properties. + +### Relationship-Based Access Control (ReBAC) + +**What it is**: Permissions based on relationships between users and specific resource instances. + +**Example**: A user is an "Owner" of document-123 but just a "Viewer" of document-456. + +**How it works with the extension**: + +- Resource instances are synced to Permit.io (with `enableResourceSync: true`) +- Permission checks include the specific resource instance ID + +**Best for**: Collaborative applications where users need different permissions on different instances of the same resource type. + +### Choosing the right model + +- **RBAC**: When you need simple, role-based access control +- **ABAC**: When decisions depend on data properties or contextual information +- **ReBAC**: When users need different permissions on different instances + +## Usage + +### Prerequisites + +Before implementing fine-grained authorization with Prisma, make sure you have: + +- A Prisma application with existing models and queries +- Basic understanding of authorization concepts +- Node.js and npm installed + +### Installation + +Install the extension alongside Prisma Client: + +```terminal +npm install @permitio/permit-prisma @prisma/client +``` + +You'll also need to sign up for a [Permit account](https://app.permit.io) to define your authorization policies. + +> **Note:** +> Ensure that the Permit PDP container is running. It is recommended to run it using Docker for better performance, security, and availability. For instructions, refer to the Permit documentation: [Deploy Permit to Production](https://docs.permit.io/how-to/deploy/deploy-to-production/) and [PDP Overview](https://docs.permit.io/concepts/pdp/overview/). + +## Basic setup + +First, extend your Prisma Client with the Permit extension: + +```typescript +import { PrismaClient } from "@prisma/client"; +import { createPermitClientExtension } from "@permitio/permit-prisma"; + +const prisma = new PrismaClient().$extends( + createPermitClientExtension({ + permitConfig: { + token: process.env.PERMIT_API_KEY, // Your Permit API key + pdp: "http://localhost:7766", // PDP address (local or cloud) + }, + enableAutomaticChecks: true // Automatically enforce permissions + }) +); +``` + +## Implementing RBAC (Role-Based Access Control) + +RBAC uses roles to determine access permissions. For example, "Admin" roles can perform all actions while "Viewer" roles can only read data. + +1. **Define resources and actions in Permit.io dashboard**: + - Create resources matching your Prisma models (e.g., "document") + - Define actions (e.g., "create", "read", "update", "delete") + - Create roles with permission sets (e.g., "admin", "editor", "viewer") +2. **Set the active user in your code**: + ```typescript + // Set the current user context before performing operations + prisma.$permit.setUser("john@example.com"); + + // All subsequent operations will be checked against this user's permissions + const documents = await prisma.document.findMany(); + ``` + +## Implementing ABAC (Attribute-Based Access Control) + +ABAC extends access control by considering user attributes, resource attributes, and context. + +1. **Configure the extension for ABAC**: + ```typescript + const prisma = new PrismaClient().$extends( + createPermitClientExtension({ + permitConfig: { token: process.env.PERMIT_API_KEY, pdp: "http://localhost:7766" }, + enableAutomaticChecks: true, + }) + ); + ``` +2. **Set user with attributes:** + ```typescript + prisma.$permit.setUser({ + key: "doctor@hospital.com", + attributes: { department: "cardiology" } + }); + + // Will succeed only if user department matches record department (per policy) + const records = await prisma.medicalRecord.findMany({ + where: { department: "cardiology" } + }); + ``` + +## Implementing ReBAC (Relationship-Based Access Control) + +ReBAC models permissions based on relationships between users and specific resource instances. + +1. **Configure the extension for ReBAC**: + ```typescript + const prisma = new PrismaClient().$extends( + createPermitClientExtension({ + permitConfig: { token: process.env.PERMIT_API_KEY, pdp: "http://localhost:7766" }, + accessControlModel: "rebac", + enableAutomaticChecks: true, + enableResourceSync: true, // Sync resource instances with Permit.io + enableDataFiltering: true // Filter queries by permissions + }) + ); + ``` + +2. ** Access instance-specific resources:** + ```typescript + prisma.$permit.setUser("owner@example.com"); + + // Will only succeed if the user has permission on this specific file + const file = await prisma.file.findUnique({ + where: { id: "file-123" } + }); + ``` + +## Manual permission checks + +For more control, you can perform explicit permission checks: + +```typescript +// Check if user can update a document +const canUpdate = await prisma.$permit.check( + "john@example.com", // user + "update", // action + "document" // resource +); + +if (canUpdate) { + await prisma.document.update({ + where: { id: "doc-123" }, + data: { title: "Updated Title" } + }); +} + +// Or enforce permissions (throws if denied) +await prisma.$permit.enforceCheck( + "john@example.com", + "delete", + { type: "document", key: "doc-123" } +); +``` + +## Common use cases + +Here are some common scenarios where fine-grained authorization is valuable: + +- **Multi-tenant applications**: Isolate data between different customers +- **Healthcare applications**: Ensure patient data is only accessible to authorized staff +- **Collaborative platforms**: Grant different permissions on shared resources +- **Content management systems**: Control who can publish, edit, or view content + +## Summary + +By integrating the `@permitio/permit-prisma` extension with your Prisma ORM application, you can implement sophisticated authorization policies that protect your data and ensure users only access what they're permitted to see. The extension supports all major authorization models (RBAC, ABAC, ReBAC) and provides both automatic and manual permission enforcement. + +## Next steps + +- [Create a free Permit.io account](https://app.permit.io) +- [View the full extension documentation](https://github.com/permitio/permit-prisma)