Authelia 配置复用机制完全指南definitions 段网络定义与用户属性【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaAuthelia 的definitions配置段用于声明可在配置其他区域复用的定义避免重复书写相同取值是构建可维护、可扩展 SSO 配置的关键能力。本文以 docs/content/configuration/definitions/introduction.md 为核心骨架结合源码与配套文档系统讲解definitions.network网络列表与definitions.user_attributes基于 CEL 的用户属性的配置语法、校验规则、底层实现与实战场景读完即可在访问控制与 OpenID Connect 1.0 配置中落地复用。文章中的示例配置均来自官方文档的configuration.yml示例标注的源码路径可直接在仓库中继续深入阅读。一、definitions 段是什么在 Authelia 配置中definitions是一个顶层配置段。官方文档的定义只有一句话它控制可以在配置其他区域复用的定义而不是重复书写相同取值见 docs/content/configuration/definitions/introduction.md。这个设计解决的是配置中的去重问题例如同一组内网网段既要在访问控制规则中使用又要在 OIDC 授权策略中使用如果两处各自书写一长串 CIDR配置将难以维护而通过definitions声明一次、按名字引用即可一处定义、多处复用。从源码看该段的结构非常简洁。在 internal/configuration/schema/definitions.go 中定义如下type Definitions struct { Network map[string][]*net.IPNet koanf:network ... UserAttributes map[string]UserAttribute koanf:user_attributes ... } type UserAttribute struct { Expression string koanf:expression ... }可以确认definitions目前包含两个子段network一组命名网络列表CIDR 集合user_attributes一组基于 CEL 表达式推导的用户属性。这两类定义分别服务于 Authelia 两大核心功能访问控制Authorization与 OpenID Connect 1.0 身份提供者OIDC Provider。二、network可复用的命名网络列表2.1 配置语法definitions.network的配置极其简单本质是键值对键是名字值是网络地址列表。官方文档示例docs/content/configuration/definitions/network.mddefinitions: network: network_name: - 192.168.1.0/24 - 192.168.2.20 - 2001:db8::/32 - 2001:db8:1234:5678::1其中key键定义的名字例如上面的network_name。它是在配置其他区域引用该网络列表时使用的标识value值一个字符串列表每一项表示该定义覆盖的 IP 范围。既支持 IPv4 也支持 IPv6既支持 CIDR 网段也支持单个 IP。官方文档特别解释了 CIDR 的含义CIDR 记法如192.168.1.0/24表示一个 IP 地址区间斜杠后的数字表示网络部分占用的位数。例如/24表示前 24 位固定后 8 位可变共 256 个地址。单个 IP 如192.168.2.20可以直接书写也可以写成/32形式两者等价。2.2 使用场景这些命名网络被用作以下两处的网络来源官方文档明确说明见 network.md访问控制网络Access Control Networks在访问控制规则中作为networks引用详见 docs/content/configuration/security/access-control.md 中的 Networks 小节OpenID Connect 1.0 授权策略网络在 OIDC 授权策略的networks字段中引用详见 docs/content/configuration/identity-providers/openid-connect/provider.md 中的 Networks 小节。也就是说你可以在definitions.network里声明一次内网、办公网、专线等概念然后在访问控制规则与 OIDC 授权策略中通过名字反复引用。2.3 源码实现与解析细节从实现层面看definitions.network的值在 schema 中被定义为map[string][]*net.IPNet即名字 → CIDR 网络列表。值得注意的实现细节有两个其一网络定义与访问控制网络会合并。在配置加载阶段internal/configuration/provider.go 中的mapDefinitions函数会把access_control.networks下定义的命名网络一并并入definitions.network前提是definitions.network中不存在同名定义否则会报错该名字同时存在于 definitions 段与 access control 段。从源码结构可以推断这是为了兼容旧式配置以前命名网络在access_control.networks中声明现在统一收敛到definitions.network两处声明同名会触发明确错误提示。其二解析与校验发生在配置反序列化阶段。每条网络地址在加载时就会被解析成*net.IPNet因此非法 CIDR 会在启动早期被发现而不是运行到匹配时才暴露。在 internal/configuration/provider_test.go 的测试中可以看到加载包含两个命名网络lan、abc的配置后config.Definitions.Network中正确包含了各自的网段列表可用于验证上述行为。三、user_attributes用 CEL 表达式定义用户属性3.1 能力概述definitions.user_attributes允许你使用Common Expression LanguageCEL为用户定义自定义属性。CEL 是 Google 开源的一种非图灵完备表达式语言常用于安全策略与数据校验场景官方文档引用其规范见 user-attributes.md。官方文档明确指出这些属性当前可用于为 OpenID Connect 1.0 声明claims注入动态值参见 docs/content/integration/openid-connect/openid-connect-1.0-claims.md。默认启用的 CEL 扩展包括官方文档列出strings字符串处理lists列表处理sets集合处理math数学运算encoders编解码bindings变量绑定regex正则匹配3.2 配置语法官方文档示例docs/content/configuration/definitions/user-attributes.mddefinitions: user_attributes: # Boolean attribute example is_admin: expression: admin in groups # String attribute example department: expression: groups[0] # Number attribute example access_level: expression: admin in groups ? 10 : 5每个属性的结构是键名 结果属性的名字值只有一个expression字段CEL 表达式。上述示例会产出三个新属性is_admin布尔值判断admin是否在用户的groups列表中department字符串取用户groups列表的第一个元素access_level数值若用户在admin组则为10否则为5CEL 三元表达式。3.3 命名约束不得与保留属性或后端属性冲突这是 user_attributes 配置中最容易踩坑的一点官方文档强调属性名不能与认证后端中定义的额外属性extra attributes冲突也不能与 Authelia 已定义的公共属性冲突见 user-attributes.md。从源码可以确认这条约束的具体实现。在 internal/configuration/validator/definitions.go 中func ValidateDefinitions(config *schema.Configuration, validator *schema.StructValidator) { for name : range config.Definitions.UserAttributes { if !isUserAttributeDefinitionNameValid(name, config) { validator.Push(fmt.Errorf(errFmtDefinitionsUserAttributesReservedOrDefined, name, name)) } } }对应的校验逻辑位于 internal/configuration/validator/util.go 的isUserAttributeDefinitionNameValid它会依次检查名字是否属于 CEL 环境中的保留属性expression.IsReservedAttribute即 Authelia 公共属性如用户名、邮箱、groups 等标准用户属性是否与 LDAP 认证后端authentication_backend.ldap.attributes.extra中定义的额外属性同名是否与文件认证后端authentication_backend.file.extra_attributes中定义的额外属性同名。任一冲突都会在配置校验阶段直接报错错误信息模板见 internal/configuration/validator/const.go从而避免运行时属性解析的歧义。3.4 CEL 表达式中可用的上下文属性表达式中除了可以直接引用用户的公共属性如groups、用户名、邮箱等外官方文档还列出了一组仅在特定上下文中可用的属性属性描述上下文openid_authreq_claim_value相关 claims 请求中的value属性OpenID Connect 1.0 授权请求openid_authreq_claim_values相关 claims 请求中的values属性OpenID Connect 1.0 授权请求安全警告官方文档以 danger 级别 callout 强调openid_authreq_claim_value与openid_authreq_claim_values除非与以下两种机制之一配合使用否则不应在安全敏感场景中使用OAuth 2.0 JWT-Secured Authorization RequestsJAR见 RFC 9101若攻击者获知取值会构成安全风险还应配合JSON Web EncryptionJWERFC 7516OAuth 2.0 Pushed Authorization RequestsPAR见 RFC 9126。这两种机制都能防止 claims 取值被攻击者篡改尤其是中间人攻击与被攻陷客户端场景。简而言之授权请求中的 claims 值来自客户端默认不可信只有在 JAR必要时加 JWE或 PAR 保护下才可安全地用于敏感判定。3.5 底层实现CEL 环境、编译与求值user_attributes的运行时实现集中在 internal/expression 包中理解它有助于写出正确的表达式。环境与编译启动时internal/expression/user_attributes.go 的setup方法会基于配置创建 CEL 环境cel.NewEnv逐个编译definitions.user_attributes中的表达式并将编译产物缓存在programsmap 中。任何表达式解析或编译失败都会在启动检查阶段直接返回错误属于启动即失败的快速失败设计。标准属性入作用域环境会注入一系列标准用户属性用户名、groups、display name、email、email verified、emails、given name、middle name、family name、nickname、profile、picture 等相关构造代码见 internal/expression/util.go 中的newAttributeUser*系列函数LDAP 或文件后端的额外属性也会通过optExtra注入见 user_attributes.go。求值ResolveWithExtra见 user_attributes.go在请求到来时以用户详情为激活上下文对预编译 program 求值结果会转换为原生 Go 值返回若求值失败则返回未找到。上下文属性注入openid_authreq_claim_value与openid_authreq_claim_values作为 OAuth2 授权请求上下文属性被注入环境见 user_attributes.go 的newAttributeOAuth2AuthorizationRequestClaimValue等构造。3.6 使用场景为 OIDC 声明注入动态值官方文档说明这些属性当前用于 OpenID Connect 1.0 Provider 的POLPolicy相关配置。典型场景是在definitions.user_attributes中定义is_admin、department等派生属性然后在 OIDC 客户端配置中把这些属性映射为 ID Token 或 UserInfo 中的自定义 claims从而实现根据用户在后端中的原始属性如组成员关系动态生成 claim 值无需在认证后端侧维护额外字段。四、definitions 段使用要点速查位置顶层definitions与access_control、identity_providers等段平级。子段仅network与user_attributes两个以当前仓库 internal/configuration/schema/definitions.go 为准。network值为 CIDR/IP 字符串列表支持 IPv4、IPv6单 IP 可省略/32供访问控制网络与 OIDC 授权策略网络引用。user_attributes值为{ expression: CEL 表达式 }属性名不得与保留属性、LDAP 额外属性、文件后端额外属性冲突默认启用 strings/lists/sets/math/encoders/bindings/regex 扩展。校验时机命名冲突在配置校验阶段报错CEL 表达式编译失败在启动检查阶段报错网络 CIDR 在反序列化阶段解析。安全提醒openid_authreq_claim_value(s)仅在 JAR必要时加 JWE或 PAR 保护下用于安全敏感判定。五、进一步阅读definitions 总览docs/content/configuration/definitions/_index.md网络定义细节docs/content/configuration/definitions/network.md用户属性定义细节docs/content/configuration/definitions/user-attributes.md访问控制Networks 引用处docs/content/configuration/security/access-control.mdOIDC ProviderNetworks 与 POL 引用处docs/content/configuration/identity-providers/openid-connect/provider.mdOIDC claims 集成docs/content/integration/openid-connect/openid-connect-1.0-claims.md源码schema 定义 internal/configuration/schema/definitions.go、校验逻辑 internal/configuration/validator/definitions.go、CEL 运行时 internal/expression/user_attributes.go【免费下载链接】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），仅供参考
