Apache APISIX authz-casdoor 插件实战接入 Casdoor 统一认证的完整指南【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix本指南围绕 Apache APISIX 中的authz-casdoor插件展开讲解如何通过该插件为网关路由接入 Casdoor 集中认证OAuth 2.0 Authorization Code 流程。读完本文你将掌握插件的四个核心配置属性、基于 Admin API 的启用与删除方法并能结合源码理解其重定向登录 → 回调换 Token → 会话免登的完整认证链路以及client_secret的加密存储机制。描述authz-casdoor是 Apache APISIX 提供的一个认证授权插件用于在 API 网关层面为受保护的路由添加 Casdoor 集中认证能力。当用户访问被该插件保护的路由时未登录用户会被重定向到 Casdoor 登录页面登录成功后由 Casdoor 携带授权码回调网关插件再向 Casdoor 换取访问 TokenAccess Token并将用户重定向回最初请求的目标 URL。从源码实现看该插件位于 apisix/plugins/authz-casdoor.lua其模块版本为 0.1priority 2559在 apisix/plugins/authz-casdoor.lua 中定义属于在请求处理早期阶段介入认证的高优先级插件。它依赖resty.session在服务端维护会话状态是典型的网关侧集中认证实现。属性插件的schema定义在 apisix/plugins/authz-casdoor.lua 中包含以下四个必填属性名称类型必选项描述endpoint_addrstring是Casdoor 的 URL。client_idstring是Casdoor 的客户端 id。client_secretstring是Casdoor 的客户端密钥。callback_urlstring是用于接收 code 与 state 的回调地址。属性约束与校验细节URL 不允许以/结尾endpoint_addr和callback_url的 schema 都使用了正则^[^%?][^/]$进行约束见 apisix/plugins/authz-casdoor.lua即地址中不能包含?且末尾字符不能是/。测试用例 t/plugin/authz-casdoor.t 中的 sanity 校验明确验证了带 query 参数的回调地址与以/结尾的 endpoint_addr都会导致 schema 校验失败。callback_url 必须是路由的 URI插件在运行时会把callback_url解析出真实的回调路径正则.//[^/](/.*)见 apisix/plugins/authz-casdoor.lua再与当前请求 URI 比对。因此callback_url的路径部分必须能命中当前路由例如示例中的/anything/callback落在路由/anything/*之下否则回调请求不会被插件识别为回调。TLS 使用告警插件的check_schema会调用core.utils.check_https见 apisix/plugins/authz-casdoor.lua当endpoint_addr、callback_url未使用https://前缀时会在日志中输出安全风险告警底层实现在 apisix/core/utils.lua提示生产环境应使用 TLS 保护认证跳转链路。client_secret 的加密存储schema 中声明了encrypt_fields {client_secret}见 apisix/plugins/authz-casdoor.lua这意味着client_secret字段会被加密后存储在 etcd 中。具体机制参考 插件开发指南 - 加密存储字段通过 Admin API 新增或更新资源时encrypt_fields中声明的参数会被 APISIX 自动加密后写入 etcd通过 Admin API 获取资源以及运行时使用该参数时APISIX 会自动解密业务侧无感知该能力需要 APISIX 版本不小于 3.1并在config.yaml中开启data_encryptionapisix: data_encryption: enable_encrypt_fields: true keyring: - edd1c9f0985e76a2测试用例 t/plugin/authz-casdoor.t 的 data encryption for client_secret 用例验证了这一行为通过 Admin API 读取到的client_secret是明文而直接读取 etcd 中存储的值则是加密后的密文。启用插件以下示例展示了如何在指定路由上启用authz-casdoor插件curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: edd1c9f034335f136f87ad84b625c8f1 -X PUT -d { methods: [GET], uri: /anything/*, plugins: { authz-casdoor: { endpoint_addr:http://localhost:8000, callback_url:http://localhost:9080/anything/callback, client_id:7ceb9b7fda4a9061ec1c, client_secret:3416238e1edf915eac08b8fe345b2b95cdba7e04 } }, upstream: { type: roundrobin, nodes: { httpbin.org:80: 1 } } }上述配置的要点uri设为/anything/*callback_url的路径/anything/callback必须落在该路由的匹配范围内endpoint_addr指向 Casdoor 服务示例中为http://localhost:8000callback_url是 Casdoor 登录成功后回调网关的完整地址示例中为http://localhost:9080/anything/callback协议、域名、端口需与网关对外可达地址一致client_id与client_secret在 Casdoor 侧创建应用时生成与 Casdoor 应用配置一一对应。Admin API 默认监听在9180端口请求头X-API-KEY对应conf/config.yaml中deployment.admin.admin_key[0].key的取值默认值为edd1c9f034335f136f87ad84b625c8f1。测试插件完整的认证流程一旦启用了该插件访问该路由的新用户首先会经过authz-casdoor插件的处理然后被重定向到 Casdoor 登录页面。成功登录后Casdoor 会将该用户重定向到callback_url并携带 GET 参数的code和state。该插件随后会向 Casdoor 请求一个访问 Token并确认用户是否已登录。在成功认证后该流程只出现一次并且后续请求不会被打断因为插件会将访问 Token 写入会话session后续请求直接复用会话不再跳转。上述操作完成后用户就会被重定向到最初请求的目标 URL。从源码看三步认证链路插件核心逻辑集中在access阶段见 apisix/plugins/authz-casdoor.lua整体可拆解为三个步骤步骤一判断当前请求是否为回调请求。插件将callback_url通过正则.//[^/](/.*)解析出纯路径部分real_callback_url若当前请求 URI 与之相等则进入回调处理分支校验会话存在且其中记录了state否则返回 503对应测试用例 TEST 7 的no session found见 t/plugin/authz-casdoor.t从 GET 参数中取code与state二者缺失时返回 400校验回调携带的state与会话中保存的state是否一致防止 CSRF 攻击不一致返回 400测试用例 TEST 8 验证了错误 state 场景见 t/plugin/authz-casdoor.t携带code调用 Casdoor 的 Token 接口换取访问 Token失败返回 503。步骤二换取访问 Token。fetch_access_token函数见 apisix/plugins/authz-casdoor.lua向{endpoint_addr}/api/login/oauth/access_token发起 POST 请求表单参数包含code、grant_typeauthorization_code、client_id与client_secret。返回体中必须包含access_token且expires_in不能为空或 0——Casdoor 约定expires_in为 0 表示 access_token 无效测试用例 TEST 9 用codewrong模拟了该场景见 t/plugin/authz-casdoor.t。步骤三建立会话并重定向回原目标。换取成功后插件新建一个生命周期为expires_in的会话session.new { cookie {lifetime lifetime} }把access_token写入会话并返回 302 重定向到会话中记录的original_uri用户即可继续访问原始目标。当请求既不是回调、也没有有效会话时插件会生成随机statemath.random(0x7fffffff)把original_uri与state写入新会话然后 302 重定向到{endpoint_addr}/login/oauth/authorize?response_typecodescopereadstate{state}client_id{client_id}redirect_uri{callback_url}用户完成 Casdoor 登录后浏览器携带code与state回到callback_url从而进入步骤一的回调分支形成闭环。测试用例佐证插件测试位于 t/plugin/authz-casdoor.t共 10 个用例覆盖schema 合法性校验TEST 1、启用插件与重定向TEST 2/3、模拟 Casdoor Token 服务TEST 4/5、正常回调换 Token 全链路TEST 6、无会话/错误 state/无效 Token 等异常分支TEST 7/8/9以及client_secret加密存储TEST 10。测试中通过test.com:1980与127.0.0.1:10420搭建了模拟 Casdoor 的 Token 端点可在本地复现插件的完整认证行为。删除插件当需要禁用authz-casdoor插件时可以通过以下命令删除相应的 JSON 配置APISIX 将会自动重新加载相关配置无需重启服务:::note您可以这样从config.yaml中获取admin_key并存入环境变量admin_key$(yq .deployment.admin.admin_key[0].key conf/config.yaml | sed s///g):::curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $admin_key -X PUT -d { methods: [GET], uri: /anything/*, plugins: {}, upstream: { type: roundrobin, nodes: { httpbin.org:80: 1 } } }将plugins置为空对象{}后该路由即不再经过 Casdoor 认证APISIX 的热更新机制会自动感知配置变更并即时生效无需重启网关进程。若需要重新启用只需再次 PUT 带authz-casdoor配置的完整路由即可。注意事项与最佳实践回调地址匹配callback_url必须是当前路由 URI 的一部分示例中/anything/callback需命中/anything/*否则回调请求无法进入插件处理分支。禁止结尾斜杠与 queryendpoint_addr、callback_url均不能以/结尾也不能携带?参数否则 schema 校验不通过。生产环境启用 TLScheck_schema会对非https的endpoint_addr、callback_url输出安全告警日志生产环境建议为 Casdoor 与回调地址配置 HTTPS。开启密钥加密APISIX 3.1 可在conf/config.yaml中开启data_encryption.enable_encrypt_fields并配置keyring使client_secret以密文形式落盘 etcd降低密钥泄露风险。会话生命周期会话有效期由 Casdoor 返回的expires_in决定Token 过期后用户需重新登录从而保证认证态与 Casdoor 侧保持一致。总结authz-casdoor插件将 Casdoor 的 OAuth 2.0 Authorization Code 认证能力以声明式配置的形式集成进 Apache APISIX 网关四个必填属性即可在指定路由上启用集中认证登录状态通过服务端会话持久化一次登录后续请求免打扰同时通过encrypt_fields对client_secret提供加密存储保护配合 schema 校验、state 防 CSRF 与 HTTPS 告警兼顾易用性与安全性。对于已经部署 Casdoor 的团队这是将统一身份认证下沉到网关层的最直接方案。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考