细粒度授权（Permit）

快速摘要

本页面解释了如何使用 @permitio/permit-prisma 扩展在 Prisma ORM 应用程序中实现细粒度授权 (FGA)。它介绍了 Permit.io 支持的不同访问控制模型——RBAC、ABAC 和 ReBAC，并指导您选择正确的模型来保护您的数据库操作，提供精确、可编程的权限。

数据库操作通常需要仔细控制谁可以访问或修改哪些数据。虽然 Prisma ORM 在数据建模和数据库访问方面表现出色，但它不包含内置的授权功能。本指南将展示如何使用 @permitio/permit-prisma 扩展在 Prisma 应用程序中实现细粒度授权。

细粒度授权 (FGA) 在粒度级别上对用户可以访问或修改的数据提供详细而精确的控制。如果没有适当的授权，您的应用程序可能会暴露敏感数据或允许未经授权的修改，从而造成安全漏洞。

访问控制模型

此扩展支持 Permit.io 的三种访问控制模型

基于角色的访问控制 (RBAC)

它是什么：用户被分配角色（管理员、编辑者、查看者），这些角色具有预定义的权限，可以在资源类型上执行操作。

示例：“编辑者”角色可以更新系统中的任何文档。

最适合：访问权限由工作职能或用户级别决定的简单权限结构。

基于属性的访问控制 (ABAC)

它是什么：基于用户、资源或环境属性的访问决策。

示例:

• 如果 user.department == document.department 则允许访问
• 如果 document.status == "DRAFT" 则允许更新

它如何与扩展配合使用：当 enableAttributeSync 开启时，资源属性会自动同步到 Permit.io 进行策略评估。

最适合：依赖上下文或数据属性的动态规则。

基于关系的访问控制 (ReBAC)

它是什么：基于用户与特定资源实例之间关系的权限。

示例：用户是 document-123 的“所有者”，但只是 document-456 的“查看者”。

它如何与扩展配合使用:

• 资源实例同步到 Permit.io（通过 enableResourceSync: true）
• 权限检查包括特定的资源实例 ID

最适合：协作应用程序，其中用户需要对相同资源类型的不同实例具有不同的权限。

选择正确的模型

• RBAC：当您需要简单的、基于角色的访问控制时
• ABAC：当决策依赖于数据属性或上下文信息时
• ReBAC：当用户需要对不同实例具有不同权限时

用法

先决条件

在 Prisma 中实现细粒度授权之前，请确保您已具备

• 具有现有模型和查询的 Prisma 应用程序
• 对授权概念的基本理解
• 已安装 Node.js 和 npm

安装

与 Prisma Client 一起安装扩展

npm install @permitio/permit-prisma @prisma/client

您还需要注册一个 Permit 帐户 来定义您的授权策略。

注意
确保 Permit PDP 容器正在运行。建议使用 Docker 运行它，以获得更好的性能、安全性和可用性。有关说明，请参阅 Permit 文档：将 Permit 部署到生产环境 和 PDP 概述。

基本设置

首先，使用 Permit 扩展来扩展您的 Prisma Client

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: "https://:7766",       // PDP address (local or cloud)
    },
    enableAutomaticChecks: true           // Automatically enforce permissions
  })
);

实现 RBAC（基于角色的访问控制）

RBAC 使用角色来确定访问权限。例如，“管理员”角色可以执行所有操作，而“查看者”角色只能读取数据。

1. 在 Permit.io 面板中定义资源和操作:
   • 创建与您的 Prisma 模型匹配的资源（例如，“document”）
   • 定义操作（例如，“创建”、“读取”、“更新”、“删除”）
   • 创建具有权限集的角色（例如，“admin”、“editor”、“viewer”）
2. 在您的代码中设置活动用户:

// 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();

实现 ABAC（基于属性的访问控制）

ABAC 通过考虑用户属性、资源属性和上下文来扩展访问控制。

1. 为 ABAC 配置扩展:

const prisma = new PrismaClient().$extends(
  createPermitClientExtension({
    permitConfig: { token: process.env.PERMIT_API_KEY, pdp: "https://:7766" },
    enableAutomaticChecks: true,
  })
);

2. 设置具有属性的用户

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" }
});

实现 ReBAC（基于关系的访问控制）

ReBAC 根据用户与特定资源实例之间的关系来建模权限。

1. 为 ReBAC 配置扩展:

const prisma = new PrismaClient().$extends(
  createPermitClientExtension({
    permitConfig: { token: process.env.PERMIT_API_KEY, pdp: "https://:7766" },
    accessControlModel: "rebac",
    enableAutomaticChecks: true,
    enableResourceSync: true, // Sync resource instances with Permit.io
    enableDataFiltering: true  // Filter queries by permissions
  })
);

2. 访问实例特定资源：

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" }
});

手动权限检查

为了进行更多控制，您可以执行显式权限检查

// 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" }
);

常见用例

以下是细粒度授权的一些常见有价值的场景

• 多租户应用程序：隔离不同客户之间的数据
• 医疗保健应用程序：确保患者数据只能由授权人员访问
• 协作平台：对共享资源授予不同的权限
• 内容管理系统：控制谁可以发布、编辑或查看内容

总结

通过将 @permitio/permit-prisma 扩展与您的 Prisma ORM 应用程序集成，您可以实施复杂的授权策略，保护您的数据并确保用户只能访问他们被允许查看的内容。该扩展支持所有主要的授权模型（RBAC、ABAC、ReBAC），并提供自动和手动权限执行。

后续步骤

• 创建免费的 Permit.io 帐户
• 查看完整的扩展文档