Authelia OpenID Connect 1.0 客户端授权策略ADR1全解析为什么 Access Control 规则不能用于 OIDC【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本篇技术指南基于 Authelia 官方架构决策记录 ADR1: OpenID Connect Client Authorization Policies系统讲解 Authelia 作为 OpenID Connect 1.0 Provider 时客户端授权策略的设计动机、规则判定原理与配置方法。你将理解为何常规 Access Control Rules 与授权码流程不兼容、哪些判定条件可以保留subject、哪些只能部分兼容networks并掌握authorization_policy与authorization_policies两个配置项的完整用法从而为你的 OIDC 客户端实现正确的、符合规范的访问控制。ADR1 是什么一次决定 OIDC 授权策略走向的架构决策ADR1Architecture Decision Record 1是 Authelia 于 2024 年 5 月 28 日发布、状态为Accepted的官方架构决策主题是OpenID Connect Client Authorization Policies。它回答了一个社区中长期存在的困惑为什么 Authelia 的 Access Control Rules 无法正确作用于 OpenID Connect 1.0 的授权码流程Authorization Code Flow以及应当用什么机制替代它。该决策明确了后续实现的两条主线为 OpenID Connect 1.0 客户端注册引入独立的授权策略配置项即authorization_policy只允许使用与 OIDC 流程语义兼容的判定条件当前仅subject未来可能加入networks。这些策略只在 Authorization Request 阶段生效不替代客户端应用自身应实现的基础访问控制。ADR1 的价值不仅在于解释现状更在于为后续开发划定了边界防止未来出现把不兼容的 Access Control 规则强行套用到 OIDC 上的架构错误。背景OIDC 授权与常规 Access Control 的本质差异在深入规则兼容性之前需要先理解 Authelia 中两类机制的定位差异Access Control Rules位于 docs/content/configuration/security/access-control.md是针对每个 HTTP 请求method、资源 URI、query、域名、客户端 IP设计的逐请求授权体系服务于 Authelia 作为反向代理认证网关的场景。OpenID Connect 1.0用户Resource Owner / 最终用户在 Authorization Server即 Authelia处认证并同意将部分个人身份信息PII交给客户端Relying Party。随后客户端凭令牌访问受保护资源。这里授权的含义与逐请求访问控制完全不同。正如 ADR1 所指出的OpenID Connect 1.0 的本质是最终用户同意在授权服务器处证明自己已认证并把该信息及部分个人可识别信息交给客户端使客户端能据此判断用户是否被授权。正确的访问控制应发生在客户端应用侧——用户在授权码流程中同意的是个人信息交换而非对后续每个资源的访问授权。为什么不兼容ADR1 给出的四大核心理由ADR1 的 Rational 部分列出了普通 Access Control Rules 与 OpenID Connect 1.0 授权码流程不兼容的最关键原因标准访问控制规则的多个要素在 OIDC 中根本没有对应物method、资源 URI、query 参数、客户端 IP 地址等信息不会传递给 OIDC Provider。这些信息只存在于用户访问资源服务器的请求中授权服务器在授权码流程中无从得知。授权码流程只发生一次策略只在初始登录时被评估一次。之后客户端通过 Access Token / Refresh Token 访问资源时授权服务器不再参与因此任何逐请求的策略在令牌生命周期内都无法再次执行。Refresh Flow 只能评估 subjectOAuth 2.0 / OpenID Connect 1.0 目前没有在 Refresh Flow 中拒绝主体的标准错误机制。即使未来实现Refresh Flow 发生在 Relying Party 上下文授权服务器唯一能可靠评估的只有主体subject本身。存在上下文歧义构成安全隐患subject 规则在 OIDC 会话生命周期内大体适用但其他条件并非如此。管理员可能因为不理解文档或术语歧义OAuth 2.0 与 OIDC 1.0 规范庞大复杂而错误理解规则的适用范围这显然构成重大安全问题。判定条件兼容性分析哪些能用哪些不能用ADR1 用专门一节逐条分析了标准 Access Control 判定条件与 OIDC 流程的兼容性并给出两条重要特别说明特别说明 1不要试图用这些条件去匹配redirect_uri。这些条件的设计目的是比较用户正在访问的资源而非回调地址且domain_regex、resources、query等条件使用正则语法而 OAuth 2.0 / OIDC 1.0 规范只允许对redirect_uri做简单字符串比较。特别说明 2不要试图用匹配请求资源类条件domain、domain_regex、resources、methods、query来比较用户正在访问的资源。这要求 Relying Party 在用户每次请求时都拿着 Access Token 去请求授权服务器没有任何规范描述此功能唯一可能携带用户行为信息的授权码流程又恰恰不包含这些元数据。各条件的具体兼容性结论如下判定条件兼容性原因domain/domain_regex/resources/query无见特别说明 1 与 2相关信息不会出现在授权请求中methods无见特别说明 2授权码流程缺失该元数据subject完全兼容主体信息可在授权码流程中可靠获得应单独为 OIDC 提供networks部分兼容仅在授权码流程用户直接请求或客户端凭证流程Resource Owner 即客户端本身中可用用户 IP 变化后令牌依然有效且无法撤销Refresh Flow 中远端 IP 是 Relying Party 而非 Resource Owner决策结果OIDC 客户端授权策略的设计边界综合上述分析ADR1 的 Proposed Design 提出为 OIDC 客户端注册实现独立的授权策略配置允许设置subject条件用户名或组未来可能在授权码流程阶段强制实施的networks条件。并可能为 Relying Party 实现另一套独立策略用于限制允许使用 OIDC 客户端的远端 IP 范围。最终Decision确定OIDC 授权策略的条件严格限定为语义上最合理的元素。决策发布时仅纳入subjectnetworks因已有合理论证留作未来可能扩展项。策略仅在 Authorization Request 阶段生效不作用于后续任何流程。它们不应成为应用放弃实现最低限度访问控制的借口没有账户或被禁用账户的用户同样不应能在第三方应用中完成授权且规范中没有空间在授权请求之外执行这些动作。与其实现 Provider 侧策略不如实现规范中的既有元素例如已支持的Authentication Method References claimamr与Requested Authentication Context Class Reference 参数acr_values。仓库实现策略在源码中如何落地ADR1 的决策已在当前仓库中完整落地可从源码结构与配置模板交叉验证。配置模型schema 中的策略定义策略的配置模型定义在 internal/configuration/schema/identity_providers.goIdentityProvidersOpenIDConnectPolicy包含DefaultPolicy枚举one_factor/two_factor/deny对应 JSON Schema 约束与Rules规则列表IdentityProvidersOpenIDConnectPolicyRule每条规则包含policy枚举同上、subject复用AccessControlRuleSubjects类型与networks[]*net.IPNet。注意deny是仅存在于该策略体系的取值——标准策略只有one_factor与two_factor而deny可通过这些配置选项独家获得。运行时行为client_policy.go 的匹配逻辑策略的运行时评估在 internal/oidc/client_policy.goNewClientAuthorizationPolicy将 schema 配置转换为运行时对象DefaultPolicy通过authorization.NewLevel解析规则逐条转换为ClientAuthorizationPolicyRuleGetRequiredLevel(subject)按顺序遍历规则第一条完全匹配的规则生效若全部不匹配则回退到DefaultPolicy。这正对应 provider 文档中每条规则按顺序匹配第一条完全匹配的规则即被应用的策略的描述。若匹配到deny规则用户不会被询问同意consent该同意被视为已拒绝并返回 OIDC 的access_denied错误。生效时机Authorization Request 阶段在 internal/handlers/handler_oauth2_authorization.go 中可以看到处理授权请求时通过client.GetAuthorizationPolicy()取得客户端策略随后的日志与错误处理均携带policy.Name策略在授权请求处理链路的开头即被使用——这正是 ADR1 所强调的仅在 Authorization Request 阶段生效。实战配置为 OIDC 客户端应用授权策略客户端级authorization_policyauthorization_policy是注册客户端Registered Client的一个直接选项完整定义见 docs/content/configuration/identity-providers/openid-connect/clients.md#authorization_policy类型为 string默认值two_factor可选one_factor、two_factor或引用 provider 级authorization_policies中定义的策略名。官方文档特别提醒该选项与 Access Control Rules 是刻意且明确不同的原因详见 ADR1 与 OIDC FAQ它只作用于 Authorization Requests不应成为应用缺失基础访问控制的拐杖。Provider 级authorization_policies 自定义策略当需要仅允许特定用户访问特定客户端这类 RBAC 需求时可在 Provider 级定义命名策略见 docs/content/configuration/identity-providers/openid-connect/provider.md#authorization_policies。官方也建议尽量依靠 OIDC Relying Party 基于可用 claims 提供 RBAC 控制。以下配置定义一个名为policy_name的策略对services组的用户返回deny其余用户默认two_factor并附加内网网段限制然后应用到客户端client_with_policy_nameidentity_providers: oidc: authorization_policies: policy_name: default_policy: two_factor rules: - policy: deny subject: group:services networks: - 192.168.1.0/24 - 192.168.2.51 clients: - client_id: client_with_policy_name authorization_policy: policy_name子选项说明default_policystring默认two_factor当没有任何规则能确定生效策略时使用的默认有效策略。ruleslist(object)必填策略判定时考虑的规则列表策略必须包含此字段才算有效。policystring默认two_factor规则匹配时应用的策略合法值为one_factor、two_factor、deny。subjectlist(list(string))情境必填主体条件语法同 Access Control Configuration 的 subject。与 networks 二选一否则规则无效。networkslist(string)network 语法情境必填本规则适用的网络列表可引用命名 Network Definitions。官方对该字段给出了安全警示规则只能在授权码流程中 Resource Owner 提供同意时应用用户 IP 可能变化同意授予且令牌签发后技术上无法再强制执行该检查详见 ADR1。同样要求与 subject 至少配置其一。与 Access Control 的完整配置骨架对照客户端完整配置骨架含authorization_policy可在 docs/content/configuration/identity-providers/openid-connect/clients.md 与 internal/configuration/config.template.yml 中找到典型片段如下identity_providers: oidc: clients: - client_id: unique-client-identifier client_name: My Application client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng # The digest of insecure_secret. redirect_uris: - https://oidc.example.com:8080/oauth2/callback scopes: - openid - groups - email - profile grant_types: - refresh_token - authorization_code response_types: - code authorization_policy: two_factor require_pkce: false pkce_challenge_method: S256authorization_policy默认值为two_factor即未配置时客户端要求用户通过两步认证后才可完成授权请求。决策的后果与 FAQ 印证Consequences由于上述不兼容性管理员习惯使用的若干 Access Control 元素method、资源、query、域名等在 OIDC 客户端授权场景下无法实现需要接受这一架构边界。这一结论在官方 FAQ 中亦有印证docs/content/integration/openid-connect/frequently-asked-questions.mdAccess Control 配置为逐请求授权而设计resources、query、methods、networks等条件对每个请求高度特异domain/domain_regex也因令牌签发给客户端而非特定域名而难以适用。因此 Authelia 将授权策略实现为客户端上的直接选项并倾向于扩展那些与 OIDC 兼容良好的条件如subject其余条件由于只能在初始授权请求期间应用几乎不可能进入 OIDC 策略体系。总结ADR1 为 Authelia 的 OpenID Connect 1.0 客户端授权策略奠定了清晰的设计基石理解边界普通 Access Control Rules 面向逐请求授权与授权码流程在信息可得性、执行时机上根本冲突保留兼容subject完全兼容并已实现networks部分兼容仅授权码 / 客户端凭证流程留待未来限定范围策略仅在 Authorization Request 阶段生效客户端应用仍需自行实现最低限度的访问控制面向规范优先使用amr、acr_values等规范既有机制而非 Provider 侧自定义策略。对于希望以 Authelia 作为 OIDC Provider 的部署者请牢记把用户级授权判断交给客户端的 claimssubject、groups把认证强度要求交给authorization_policy与未来的amr/acr_values才是符合 ADR1 精神与 OIDC 规范的正确姿势。【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考