Spree Admin API Key 权限范围Scopes机制详解从设计提案到源码实现【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spreeSpree 的 Admin API 支持两种认证方式——服务端集成的 Secret API Key 和管理员会话的 JWT而二者的授权模型截然不同。本文基于仓库中的设计文档 docs/plans/5.5-admin-api-key-scopes.md完整讲解 Admin API Key 的 scope 授权体系scope 词汇表、存储设计、强制执行的控制器机制、与 CanCanCan 的协作方式以及配套的防提权保护读完后你可以理解 Spree 如何为非用户主体集成应用实现资源粒度的最小权限控制并能对照 源码实现 自行扩展或审查相关功能。一、背景为什么 API Key 需要 ScopesAdmin API 的认证有两条路径通过X-Spree-Api-Key头传入的Secret API Keysk_前缀用于服务端对服务端集成以及通过Authorization: Bearer传入的JWT用于管理员 SPA / 交互会话。原设计提案指出核心矛盾Spree 的传统授权依赖 CanCanCan而 CanCanCan 从current_user解析 ability——这对 JWT 认证的管理员用户完全适用但对 API Key 却不合身因为Key 代表的是集成/应用不是用户。因此该方案给Spree::ApiKey引入 scopes让每个密钥自带权限、独立于任何用户存在这一思路借鉴了 Shopify access scopes 与 Saleor app permissions 的行业做法仅名称提及不在本文给出外部链接。设计文档明确的状态是Implemented in 5.5且 6.0 的 RBAC 重构对其部分决策进行了扩展见 docs/plans/6.0-admin-rbac.md。二、关键设计决策Key Decisions以下是原提案中未经讨论不得偏离的决策清单也是理解整套机制的骨架Scope 词汇表为每个顶级管理资源提供read_resource/write_resource约 15 个 scope。write_*蕴含read_*。便捷别名read_all与write_all分别授予全部读取、或全部读写权限。别名在检查时展开而非存储时展开因此管理员日后重新调整权限无需重写已存储值。Scopes 只作用于 API KeyJWT 管理员继续使用 CanCanCan他们持有Spree::Role。6.0 起此条被部分取代JWT 员工也要通过同一道 key gate其角色的目录键catalog keys扮演与 scope 相同的角色。不向后兼容旧的管理 API KeyAdmin API 当时尚未生产发布此后创建的所有 secret key 必须显式声明 scopes。资源粒度而非动作粒度没有cancel_orders、approve_orders之类的细分 scope——write_orders覆盖所有写操作包括状态流转和成员动作。动作映射index/show→read_resource其余一切动作包括cancel/approve等自定义成员动作→write_resource。Scope 由控制器通过scoped_resource :name显式声明而不是从控制器名自动推导。这让嵌套控制器可以映射到与父级不同的 scope例如Orders::PaymentsController→payments。6.0 的部分取代Superseded设计文档在开头特别标注2026-08-07见 6.0-admin-rbac.md6.0 中scope 词汇表成为唯一的权限目录THE permission catalog是 staff 角色与 API Key 共用的单一授权词汇permission sets 被删除无兼容桥接Spree::ApiKey::SCOPES不再是一个冻结字面量而是从权限目录派生——扩展注册的自动成为可铸造的 scope员工端点/admin_users、/invitations、/roles从settings拆出形成新的read_staff/write_staff对不要给 JWT 认证路径加 scope 检查的决策被取代key gate 泛化到 JWT 员工成为两种主体principal的主要管理端强制手段。仍然有效的决策资源粒度、write_*蕴含read_*、别名机制、每控制器的scoped_resource声明此外它还成为 403 响应中required_permission诊断信息的来源、以及 secret key 的 scope 不可变性。三、存储设计scopes 列与 Spree::ApiKey 模型原提案的迁移与模型提案中的迁移极其克制——一个跨数据库兼容的text列JSON 序列化数组默认[]即无 scope 的密钥在 Admin API 上什么都做不了fail closedclass AddScopesToSpreeApiKeys ActiveRecord::Migration[7.2] def change add_column :spree_api_keys, :scopes, :text, default: [], null: false end end提案中的模型核心节选serialize :scopes, type: Array, coder: JSON、secret key 的presence校验、KNOWN_SCOPES冻结字面量、未知 scope 校验以及 scope 判定方法has_scope?def has_scope?(scope) return true if scopes.include?(scope) return true if scope.start_with?(read_) scopes.include?(write_#{scope.delete_prefix(read_)}) return true if scopes.include?(write_all) return true if scope.start_with?(read_) scopes.include?(read_all) false end四条规则分别对应直接持有 scope、write_*蕴含read_*、write_all全放行、read_all放行所有read_*。当前仓库中的实际实现对照 spree/core/app/models/spree/api_key.rb实现演进了几处关键变化1. scope 词表从权限目录派生而非冻结字面量。提案中的KNOWN_SCOPES常量已被类方法known_scopes取代api_key.rb#L20-L22def self.known_scopes Spree.permissions.catalog_keys ALIAS_SCOPES endSpree.permissions的目录实现在 spree/core/lib/spree/core/permission_configuration.rb其中register_resourceL123允许扩展注册新资源catalog_keysL180、key?L211与expand_keysL259 附近提供词表查询与别名展开。这意味着扩展只需注册资源其read_*/write_*键就自动成为可铸造的 scope无需改动ApiKey模型。2. 存储从serialize改为 JSON 列属性。当前实现api_key.rb#L24-L30# Scopes are stored in a JSON column (jsonb on PostgreSQL, json elsewhere). # The DB driver handles array - JSON conversion; no serialize needed. attribute :scopes, default: [] def scopes(value) super(Array(value).map(:to_s).reject(:blank?)) end3. scope 不可变性immutability落在模型层。api_key.rb#L55-L63 显示三条校验secret key 必须带至少一个 scopepresence、scope 必须全部已知validate_known_scopesL152-L158错误消息经Spree.t国际化、以及已持久化的 secret key 一旦修改 scope 即被拒绝scopes_immutable。源码注释解释了原因对齐 Stripe/GitHub/AWS 的做法——权限变更应通过铸造新密钥并吊销旧密钥完成这保持审计边界清晰也防止一把共享/泄露的 key 悄悄获得写权限。校验放在模型层还保证了 API、旧管理端、rake 任务等所有入口被统一覆盖。另有一个scopes_enforceable?L148-L150细节仅在创建或 scope 变更时强制词表校验避免吊销一个用旧词表铸造的 key 时因 scope 已被移除/重命名而校验失败。4. Secret key 本身只存 HMAC 摘要。generate_tokenL176-L191对 secret key 生成sk_前缀 24 位 base58 随机串数据库只保存token_digestHMAC-SHA256密钥为Rails.application.secret_key_base见compute_token_digestL93-L102和前 12 位的token_prefix用于展示明文仅通过内存中的plaintext_tokenL32-L39在创建瞬间暴露。查找走find_by_secret_tokenL82-L87按摘要精确匹配。这解释了为什么scope 不可变 吊销重发是唯一的权限调整路径——数据库里根本没有明文可比对。四、Scope 词汇表完整清单原提案的 scope 与端点映射表是本文的核心参考资料完整继承如下Scope覆盖端点read_orders/write_orders/orders/*、/orders/:id/itemsline items 归入 ordersread_products/write_products/products/*、/variants/*、/option_types/*、/prices/*、/media/*read_customers/write_customers/customers/*、/customers/:id/addresses、/customers/:id/credit_cardsPII 随主资源走read_payments/write_payments/orders/:id/payments、/payments/*read_fulfillments/write_fulfillments/orders/:id/fulfillmentsread_refunds/write_refunds/orders/:id/refundsread_gift_cards/write_gift_cards/orders/:id/gift_cards、未来的/gift_cards/*read_store_credits/write_store_credits/customers/:id/store_credits、/orders/:id/store_creditsread_promotions/write_promotions/promotions/*rules、actions、coupon codes 嵌套在内read_stock/write_stock/stock_locations/*、/stock_items/*、/stock_transfers/*、/stock_reservations/*——完整库存面read_categories/write_categories/categories/*exports 无专属 scope/exports/*由被导出资源的读 scope 把关Spree::Export.required_scope按类名推导、子类可覆写。export 本质是批量读独立的 exports scope 会让密钥导出其本无法直接读取的数据。索引列表会按可读类型过滤read_settings/write_settings/payment_methods、/markets、/countries、/tax_categories、/stores、/channels、员工/admin_users、/invitations、/roles6.0 已移至read_staff/write_staff、/allowed_origins、/custom_field_definitions/*schema 配置合并在此read_webhooks/write_webhooks/webhook_endpoints/* 嵌套 deliveries——从settings拆出因为 webhook 端点会把事件载荷订单、客户外泄到任意 URLread_api_keys/write_api_keys/api_keys/*——凭据管理刻意不放在settings下配合创建时的防提权保护。业界惯例Shopify/Stripe/BigCommerce是干脆把凭据管理排除出 scope 体系专用 scope 对 保护是可授予的折中方案read_dashboard/dashboard/*分析统计无写对应物read_all所有read_*scopewrite_all所有read_*与write_*scope完整管理员拆分启发式原文规则当合作伙伴集成现实地可能只要其一时才拆独立 scope。例如分析工具只读订单、不读客户→ 拆订单管理要写 line items→ 不拆。刻意不做 scope 把关的端点/auth/*—— 登录/刷新处于认证前/me—— 返回调用者自身的权限信息无需 scope/tags—— 只读枚举低风险的自动补全数据/direct_uploads—— 预签名 URL 助手已有认证把关存储侧才是 scope 边界。注意官方开发者文档 docs/api-reference/admin-api/authentication.mdx 中的 scope 参考表是面向使用者的当前版词汇表资源覆盖面更广如customer_groups、price_lists、gift_card_batches均已并入对应 scope 的覆盖说明并且补充了一条重要规则自定义字段的值随其挂载的资源走write_products可管理 product/variant/option type 上的自定义字段值而自定义字段定义schema属于settings。五、强制执行ScopedAuthorization Concern提案中的原始实现提案设计了一个混入Spree::Api::V3::Admin::BaseController的ScopedAuthorizationconcern类方法scoped_resource(name)记录资源名before_action :authorize_api_key_scope!中若当前请求由 API key 认证current_api_key非空且控制器声明了_scoped_resource则按action_kindindex/show→read其余 →write拼出所需 scope 并调用has_scope?不满足即raise CanCan::AccessDenied。每个管理控制器只需一行声明class Spree::Api::V3::Admin::OrdersController ResourceController scoped_resource :orders end嵌套控制器单独声明例如/orders/:id/payments下的Orders::PaymentsController声明scoped_resource :payments。仓库中大量控制器遵循此模式如 orders/payments_controller.rb、webhook_endpoints_controller.rb 等 100 余个管理控制器均含scoped_resource声明。当前仓库中的实现fail-closed 与 JWT 员工闸门现网实现在 spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb比提案多了解决三类真实问题的机制1. fail-closed 的密钥自解析。核心防护在authorize_api_key_scope!L67-L124。注释解释了一个隐蔽漏洞若该守卫先于认证流程运行此时current_api_key为 nil——简单写return unless current_api_key会让攻击者携带的 secret key 绕过 scope 检查。因此守卫就地自行解析密钥resolve_current_api_key_for_scope_check!L174-L179若请求携带了 secret key 却无法解析为当前 store 下的有效 key直接返回 401invalid_token而不是放行只有确认完全没有 secret key的请求JWT / publishable才进入非密钥路径。2.skip_scope_check!显式豁免。类方法skip_scope_check!L46-L54支持三种粒度整控制器豁免、only: :index按动作豁免例如 exports 索引按可读类型过滤集合、走另外的授权逻辑、以及jwt_only: true——只豁免 JWT 员工但仍对 secret key 强制 scope用于仪表盘读取的壳数据如 store 本身登录员工可以看但 scope 受限的集成 key 不该在其授权范围外读到。同时定义MissingScopedResource异常L23-L28API key 认证的控制器必须声明scoped_resource、覆写scoped_resource_name或显式skip_scope_check!否则抛错——这是fail closed在声明侧的体现。3. 403 诊断信息。scope 不满足时不再raise CanCan::AccessDenied而是渲染结构化错误L118-L123render_error( code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:access_denied], message: API key lacks scope: #{required}, status: :forbidden, details: { required_scope: required } )此外action_kindL196-L199不再硬编码%w[index show]而是尊重ResourceController可覆写的read_actions列表——控制器声明一次自定义只读动作如typesscope 类型映射与 CanCanCan 动作映射同时被修正。4. JWT 员工的同构闸门。authorize_staff_permission!L129-L158实现 6.0 的取代决策JWT 员工走同一个 key gate其角色的目录键来自Spree::Ability#permission_keysadmin 角色的 ability 直接持有完整catalog_keys见 spree/core/app/models/spree/ability.rb#L161扮演 scope 的角色。所需键不在目录内时回退到 CanCanCanauthorize!被拒时记日志含 user、required、held 键并返回details: { required_permission: ... }的 403——这正是设计文档中scoped_resource声明成为 403 诊断信息来源的落地。六、与 CanCanCan 的协作及 current_ability 解析提案明确了双轨协作模型API key 请求scope 检查先跑。通过后 CanCanCan 照常运行但其 ability 从 key 的created_by用户解析——按记录的规则store 作用域、软删除资源等仍然生效created_by为 nil 时 ability 为空操作全放行因为资源级授权已由 scope 完成。JWT 用户请求scope 检查空转CanCanCan 原样运行。current_ability的解析策略提案代码def current_ability current_ability || Spree::Ability.new(ability_user, ability_options) end def ability_user return current_user if current_user return current_api_key.created_by if current_api_key.created_by nil endSpree::Ability.new(nil, store: store)得到 guest ability 是安全的因为 scope 检查已先完成了资源级授权CanCanCan 只承担 per-record 过滤。当前源码中这一优先级体现在ScopedAuthorization#scope_limited_principal?scoped_authorization.rb#L204-L206只有有 key 且无 user的请求才按 scope 授权与AdminAuthentication#current_ability的凭据优先级JWT 用户优先保持一致。使用者文档也确认了这一点两个头同时存在时 JWT 胜出scopes 被忽略见 docs/api-reference/admin-api/authentication.mdx 的 Authentication summary 一节。七、防止 scope 提权ApiKeysController 的创建保护设计文档将key 不能铸造超出自身权限的 scope列为词汇表的一部分当前实现见 spree/api/app/controllers/spree/api/v3/admin/api_keys_controller.rb控制器声明scoped_resource :api_keysL11注释明确凭据管理不是店铺配置write_settings的 key 不得吊销/销毁更高权限的 keyskip_scope_check! only: :currentL15让 key 描述自身无需read_api_keys。创建时的防提权保护L23-L40覆盖两种主体secret key 铸造的新 key 只能携带原 key 已持有的 scopeJWT 员工只能铸造其角色权限键范围内的 scope持有 admin 角色者不受限。由于 scope 与角色 permissions 共享同一目录词表两者都以展开后的键集合比较超出部分返回 403 并在details.excess_scopes中列出具体超额项。吊销而非删除revoke动作L46-L52只打revoked_at标记行保留以便审计日志与created_by/revoked_by可查询。最小化 mass assignmentpermitted_paramsL103-L107在 update 时只放行name——key_type、scopes、channel_id均为 create-only与模型层不可变校验互为呼应注释特别说明不给扩展开 union 口子因为 scope 与类型本身就是授权面不是可扩展的资源数据。/api_keys/currentL63-L73描述本次请求所用 key 的实时 scopes供spree apiCLI 展示凭据的真实当前权限而非本地旧快照JWT 管理员则用GET /admin/me。使用者侧的入口是 Spree CLI见 authentication.mdxspree api-key create --type secret --scopes read_orders,write_products spree api-key list spree api-key revoke key_id八、错误响应格式scope 不足的响应固定为403 Forbidden{ error: { code: access_denied, message: API key lacks scope: write_orders, details: { required_scope: write_orders } } }提案最初把details.required_scope设计为可选增强当前实现已将其作为标配输出守卫 L118-L123 的details: { required_scope: required }测试用例也以此断言见下节。SDK 不需要感知 scope 的存在——服务端强制并返回缺失 scope 名称OpenAPI 规范则通过 rswag 的security声明为每个端点标注所需 scope。九、测试机制如何被验证spree/api/spec/controllers/spree/api/v3/scoped_authorization_spec.rb 覆盖了三类核心断言恰好对应提案迁移路径第 7 步要求每个控制器 spec 覆盖的场景带所需 scope 的请求成功scopes: [read_orders]的 key 调index→ 200缺 scope 返回 403 且携带required_scoperead_customers的 key 调 ordersindex→ 403error.details.required_scope read_orders只读 scope 调destroy→ 403required_scope write_orders别名展开read_all放行一切读但拒绝写write_all读写全通write_orders单独持有也放行读蕴含规则。此外还有两个高价值的回归场景执行顺序回归L173-L221以DashboardController为例由于authorize_api_key_scope!先于authenticate_admin!运行守卫时刻current_api_key尚为 nil。该 spec 验证守卫自行解析密钥且 fail closed——无 scope 的 secret key 请求被拒而非静默跳过检查而 JWT 管理员正常通过promotions 词表回归L141-L171历史上scoped_resource :promotions声明存在但词表中缺少该 scope 对导致 promotions 端点只能靠*_all到达。spec 用read_promotions放行 /read_orders拒绝并断言required_scope read_promotions锁住此缺陷。十、UI、SDK 与 OpenAPI 文档API key 创建 UI提案要求在现有 API keys 管理界面铸造 secret key 时——资源复选框树read/write 两列、全选读 / 全选写 / 完整管理员write_all快捷预设、内联 scope 说明文案如Read orders — view orders, line items, status、保存前校验至少勾选一个 scope、以显式数组存储而非存储别名。SDK 与 OpenAPISDK 无需感知 scope服务端强制 403 报错带缺失 scope 名OpenAPI spec 通过 rswag 的security [api_key: [scopes...]]语法为每端点声明所需 scope提案同时告诫此前编写的 spec 应预期未来的 security 增强不要在描述文本里手工重复 scope 信息。十一、迁移路径与对后续开发的约束提案给出的迁移步骤无数据迁移——没有生产环境的 admin API key 需要迁移给spree_api_keys加scopes列默认[]Spree::ApiKey加入KNOWN_SCOPES现已演进为known_scopes与has_scope?加入ScopedAuthorizationconcern 并混入Admin::BaseControllercurrent_ability解析回退到current_api_key.created_by为每个管理控制器声明scoped_resource当时约 25 个控制器各一行如今该声明已遍布上百个控制器API key 管理 UI 暴露 scope 复选框为每个管理控制器补三类场景的 controller spec更新docs/api-reference/admin-api/authentication.mdx的 scope 参考。对并行工作的约束提案原文此方案落地后任何新管理控制器必须调用scoped_resource :name审查者应拒绝不声明的 PR当前MissingScopedResource异常把这条约定变成了运行时强制不重新审视本提案不得加入按动作的 scopecancel_orders等不向 JWT 认证路径加 scope 检查——6.0 后此条已被取代key gate 泛化为 JWT 员工同样适用此方案前加入的 OpenAPI spec 应预期security增强。十二、开放问题与后续演进提案保留的开放问题read_dashboard是否进一步拆分当前把所有分析端点捆在一起若将来出现按团队的仪表盘营收、履约、客户可能需要read_revenue_dashboard等。策略是等真实的合作伙伴需求出现再拆OAuth 流程中的 scopes5.5 不做若未来构建公共应用市场OAuth 颁发的 token 将以相同方式携带 scopes复用同一词表scope 拒绝请求的审计日志对应用开发者排障有用可挂靠现有Spree::EventBus模式首版不做webhook 订阅read_webhooks/write_webhooks先保留命名待 webhook 管理端点落地时实现从仓库现状看webhook_endpoints_controller.rb 已存在并声明了对应 scope。6.0 的演进方向详见 docs/plans/6.0-admin-rbac.md则是把本方案升级为统一权限基座scope 词表 唯一权限目录Spree::ApiKey.known_scopes从目录派生staff 端点独立为read_staff/write_staffJWT 员工与 secret key 共用同一道 key gate。这一演进没有推翻 5.5 的任何持久决策资源粒度、蕴含规则、别名、per-controller 声明、scope 不可变而是把仅适用于 key 的机制泛化为适用于所有管理端主体的机制。十三、实践要点小结给集成 key 选最小 scope 集先用read_all验证集成再按details.required_scope报错收敛为具体read_*/write_*组合403 响应会直接告诉你缺哪个 scope。write_*自动蕴含read_*不必冗余声明别名只建议用于快速起步UI 存储的是显式数组。改权限 换 keyscope 不可变是模型层强制的权限调整通过spree api-key createspree api-key revoke完成审计链完整。警惕提权路径通过已有 key 铸造新 key 时只能携带自身 scope 的子集excess_scopes403write_api_keys是独立于settings的显式授权。扩展开发者新增管理控制器务必scoped_resource :name注册新资源Spree.permissions.register_resource后其 scope 对自动进入known_scopes无需改动 key 模型。参考文件索引设计文档、ApiKey 模型、ScopedAuthorization concern、ApiKeys 控制器、权限目录配置、Scope 机制 spec、Admin API 认证文档、6.0 RBAC 方案。【免费下载链接】spreeOpen Source eCommerce Platform for B2B, Marketplace, and Enterprise. REST API, TypeScript SDK, and production-ready Next.js storefront. Self-host it. Own your stack. No vendor lock-in. Zero platform fees.项目地址: https://gitcode.com/GitHub_Trending/sp/spree创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考