OPA SQL 数据过滤实战：用部分求值把 Rego 授权策略编译成 WHERE 子句

后端认证鉴权云原生【免费下载链接】opaOpen Policy Agent (OPA) is an open source, general-purpose policy engine.项目地址https://gitcode.com/gh_mirrors/op/opa点击查看免费下载导读本教程基于 Open Policy AgentOPA的 Data Filtering 能力围绕一个具体的权限问题——总监Director能看到哪些员工的薪资——完整演示如何编写可编译的 Rego 授权策略、借助部分求值Partial Evaluation让 OPA 动态推导出 SQLWHERE子句并把该过滤器应用到真实的 sqlite3 数据库查询中。读完本文你将掌握opa run --server/v1/compile的完整调用链路、compile元数据注解的写法、Accept头对输出目标SQL/UCAST/多目标的控制以及如何正确处理“无条件放行/无条件拒绝”三种结果形态。前置条件动手实践前请确认环境满足以下要求已下载并安装 OPA本文所用服务器模式通过opa run --server启动已安装sqlite3命令行工具macOS 与大多数 Linux 发行版已预装详见 sqlite.org已安装curl与jq用于向 OPA 发送 HTTP 请求并解析 JSON 响应。第一步创建并填充示例数据库本教程使用如下员工薪资数据集namedepartmentrolesalaryAliceengineeringdirector130000Bobengineeringengineer90000Carolengineeringengineer85000Davemarketingdirector120000Evemarketingmanager95000把下面的 SQL 保存为employees.sqlCREATE TABLE employees (name TEXT, department TEXT, role TEXT, salary INTEGER); INSERT INTO employees VALUES (Alice, engineering, director, 130000); INSERT INTO employees VALUES (Bob, engineering, engineer, 90000); INSERT INTO employees VALUES (Carol, engineering, engineer, 85000); INSERT INTO employees VALUES (Dave, marketing, director, 120000); INSERT INTO employees VALUES (Eve, marketing, manager, 95000);然后加载该文件创建数据库sqlite3 company.db employees.sql第二步编写可编译为 SQL 过滤器的策略业务规则是总监只能查看本部门员工的薪资。在 Rego 中把这一规则表达为filters包下的include规则# METADATA # scope: package # compile: # unknowns: [input.employees] package filters include if { input.user.role director input.employees.department input.user.department }这里有两个关键概念需要理解input.employees被声明为“未知”unknown——它代表 OPA 尚未看到的数据库行。OPA 在部分求值时不会去解析它而是把它保留为剩余条件residual condition最终翻译成 SQL 列引用。input.user是查询时“已知”known的值——它携带当前登录用户上下文部分求值时会被具体值替换substitute。元数据注解的作用机制在源码中有明确印证服务器在收到请求后若请求体未显式提供unknowns会通过compile.ExtractUnknownsFromAnnotations从注解集中提取unknowns列表参见 internal/compile/compile.go该函数只接受以input或data前缀开头的引用其余路径会报错。第三步以服务器模式启动 OPAopa run --server policy.rego启动成功后 OPA 在http://localhost:8181上监听 HTTP API。本文使用的正是 Data Filtering 的核心端点POST /v1/compile/{path:.}其中{path}是待编译的过滤规则路径例如要编译data.filters.include规则就请求/v1/compile/filters/include该端点的完整说明见 rest-api.md。第四步向 OPA 请求 SQL 过滤器另开一个终端把当前登录用户作为输入调用 compile 端点。Alice 是工程部总监curl -s -X POST http://localhost:8181/v1/compile/filters/include \ -H Content-Type: application/json \ -H Accept: application/vnd.opa.sql.sqlitejson \ -d {input: {user: {name: alice, role: director, department: engineering}}}OPA 对策略进行部分求值其推导过程如下input.user.role director——等式两边均为已知值条件为真该表达式被“消费”consumed不出现在输出中input.employees.department input.user.department——左侧未知、右侧已知已知的engineering被代入从而生成 SQL 条件。响应{ result: { query: WHERE employees.department engineering } }关于Accept头需要补充说明OPA 通过Accept头选择输出目标格式详见 rest-api.mdAccept值响应结构说明application/vnd.opa.multitargetjsonresult.{ucast,sqlserver,mysql,postgresql,sqlite}多目标输出需配合请求体options.targetDialects指定目标组合application/vnd.opa.ucast.alljson/.minimaljson/.linqjson/.prismajsonresult.queryUCAST 条件 JSON 对象application/vnd.opa.sql.sqlserverjson/.mysqljson/.postgresqljson/.sqlitejsonresult.query目标方言的 SQL 条件字符串在服务端源码 v1/server/compile_handler.go 中可以看到这些 MIME 类型常量sanitizeHeader会校验Accept头必须且只能是受支持的值之一targetDialect则据此决定编译目标与方言。本教程使用的 sqlite 方言对应sql sqlite。第五步把过滤器应用到真实数据库查询用jq从响应中提取过滤器并拼接进 SQL 查询FILTER$(curl -s -X POST http://localhost:8181/v1/compile/filters/include \ -H Content-Type: application/json \ -H Accept: application/vnd.opa.sql.sqlitejson \ -d {input: {user: {name: alice, role: director, department: engineering}}} \ | jq -r .result.query) sqlite3 company.db SELECT name, salary FROM employees $FILTER;输出——Alice 能看到工程部全部员工的薪资namesalaryAlice130000Bob90000Carol85000Dave 是市场部总监同一份策略会为他生成不同的过滤器FILTER$(curl -s -X POST http://localhost:8181/v1/compile/filters/include \ -H Content-Type: application/json \ -H Accept: application/vnd.opa.sql.sqlitejson \ -d {input: {user: {name: dave, role: director, department: marketing}}} \ | jq -r .result.query) sqlite3 company.db SELECT name, salary FROM employees $FILTER;输出——Dave 能看到市场部全部员工的薪资namesalaryDave120000Eve95000第六步非总监用户被无条件拒绝Bob 是工程师而非总监。input.user.role director这一已知条件为假任何规则体都不可能被满足策略无条件拒绝curl -s -X POST http://localhost:8181/v1/compile/filters/include \ -H Content-Type: application/json \ -H Accept: application/vnd.opa.sql.sqlitejson \ -d {input: {user: {name: bob, role: engineer, department: engineering}}}响应——result中缺少query键{}query缺失即表示无条件拒绝。应用程序此时应直接返回零行数据完全不必发起数据库查询。:::warning 务必保证安全默认值 OPA 只负责生成过滤器并不负责强制执行它——把过滤器用对是应用层的责任。在本例中若用户不是总监没有任何规则体可被满足OPA 返回无条件拒绝表现为结果中query键缺失应用层应当安全地返回零行绝不能把空查询当作“全部可见”处理。 :::部分求值到底做了什么回顾整个流程OPA 在input.user完全已知的情况下对策略求值。只涉及已知值的表达式如input.user.role director被完整求值并消费不会出现在输出中只有涉及未知input.employees的表达式作为剩余条件保留下来再由 OPA 翻译成 SQL。翻译链路的实现路径为/v1/compile处理器v1/server/compile_handler.go将请求封装进rego_compile的Prepare对每个目标调用filters.For(target, dialect)取出结果而 SQL 的最终生成发生在 internal/compile/compile.go 的QueriesToSQL——先把部分求值得到的一组组条件体bodies转成 UCAST再调用AsSQL(dialect)输出对应方言的 SQL 字符串。每种目标/方言还受到 internal/compile/constraints.go 中NewConstraints定义的约束SQL 目标支持not、field-ref、existence-ref等特性值得留意的是 sqlite 方言不支持startswith/endswith/contains内建函数见 constraints.go写策略时需注意目标方言的能力差异。应用层全程无需知道策略内部“如何”决定哪些薪资可见。它只需发送用户上下文然后接收一个 SQL 过滤器或一个拒绝信号去执行。处理无条件结果OPA 响应含义应用层动作{ query: WHERE ... }条件放行把过滤器拼接到 SQL 查询{ query: }无条件放行直接查询不带WHERE{}无条件拒绝返回零行跳过查询其中“无条件放行”形态对应部分求值后没有任何剩余条件的场景——所有条件都已知且为真此时QueriesToSQL中的 UCAST 为nilSQL 保持为空字符串。而“无条件拒绝”则在服务器端通过“结果中不含query键”来表达参见 rest-api.md两种形态应用层都必须正确处理尤其是无条件拒绝时绝不能回退成“查全表”。进阶表名/列名映射与更多目标如果 unknown 与数据库表/列名并非一一对应可以通过请求体options.targetSQLTableMappings显式映射。例如把fruits表映射为实际表fruit、列name映射为display_name、price映射为price_tag策略即可翻译成WHERE fruit.display_name Epineapple AND fruit.price_tag Efree对于多目标请求还可以按方言分别配置替换规则示例见 rest-api.md。此外请求体中的options.disableInlining、options.maskRule、options.targetDialects以及顶层unknowns字段都可覆盖或补充策略注解完整字段说明见 rest-api.md。清理环境在运行 OPA 的终端按CtrlC停止服务器然后删除教程产生的文件rm employees.sql policy.rego company.db延伸阅读Evaluating a Data Filter Policy——逐步走查部分求值的过程帮助你理解每条表达式如何被消费、保留或抛弃Writing valid Data Filtering Policies——哪些 Rego 构造可以作为过滤条件支持比较运算符、部分内建函数、not表达式等以及every、default规则等限制Data Filtering with OPA——数据过滤问题的整体介绍与“求值 vs 搜索”的范式对比生产环境中建议使用语言 SDKGo、Java、Python、JavaScript 等调用本教程所用的 compile API而非裸curlSDK 能提供类型化的客户端封装。赞分享后端认证鉴权云原生【免费下载链接】opaOpen Policy Agent (OPA) is an open source, general-purpose policy engine.项目地址https://gitcode.com/gh_mirrors/op/opa点击查看免费下载相关推荐5个理由告诉你为什么Windhawk是Windows程序定制的最佳选择5个理由告诉你为什么Windhawk是Windows程序定制的最佳选择 在Windows程序定制领域Windhawk正以其创新的模块化设计改变着用户个性化体后端认证鉴权云原生Docker-Flask-Example开发实战前端资产管理与esbuild、TailwindCSS配置终极指南Docker Flask Example开发实战前端资产管理与esbuild、TailwindCSS配置终极指南 在现代化的Web应用开发中高效的前端资产管后端认证鉴权云原生Apache APISIX opa 插件实战集成 Open Policy Agent 实现外部化授权策略Apache APISIX opa 插件实战集成 Open Policy Agent 实现外部化授权策略 导读 本文将深入讲解 Apache APISIX 的后端微服务云原生上一篇awesome-hyper社区访谈核心维护者分享项目心得下一篇如何快速掌握Python-OSC构建纯Python的Open Sound Control通信系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考