Authelia access-control check-policy 命令详解在命令行中预检访问控制策略匹配【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaauthelia access-control check-policy是 Authelia 提供的一个诊断辅助命令它允许你在不实际发起 HTTP 请求的情况下将一组主体 对象subject object输入到访问控制规则引擎中精确判断哪条 ACL 规则会命中、命中后的策略bypass/one_factor/two_factor/deny是什么以及哪些规则只是潜在匹配。本文以官方命令参考文档 authelia_access-control_check-policy.md 为主线结合 internal/commands/acl.go 的实现与 internal/commands/acl_test.go 的测试用例讲解该命令的完整用法、输出格式与底层匹配原理帮助你在排障访问控制配置时快速定位问题。命令定位访问控制系统的诊断工具在 Authelia 的命令体系中check-policy是access-control父命令下唯一的子命令。父命令 authelia access-control 的定位是访问控制系统的辅助工具Helpers for the access control system而check-policy的具体职责从命令全名即可看出Checks a request against the access control rules to determine what policy would be applied.即拿一个模拟请求去和配置中的访问控制规则比对输出最终会生效的策略。它非常适合在以下场景使用排查为什么这个 URL 被重定向到了登录页 / 被直接放行验证新写的 ACL 规则如domain、resources、query、methods、network、subjects组合是否符合预期测试不同用户、不同用户组、不同来源 IP 会命中的策略差异在不修改任何服务运行状态的前提下做配置预检。需要特别说明的是该命令的输入是模拟请求URL、HTTP 方法、用户名、用户组、来源 IP 均由命令行参数指定不会真正访问目标站点。命令语法与位置authelia access-control check-policy [flags]完整的命令调用链为authelia→access-control→check-policy。从源码 internal/commands/acl.go 可以看到命令通过 Cobra 框架注册newAccessControlCommand创建access-control父命令Use: access-control短描述为 Helpers for the access control systemnewAccessControlCheckCommand创建check-policy子命令Use: check-policy并挂载了PreRunE: ctx.ChainRunE(ctx.HelperConfigLoadRunE)这意味着在执行策略检查前命令会先加载并解析配置文件——这也是为什么该命令依赖--config参数的原因。命令执行入口为AccessControlCheckRunE其处理流程如下internal/commands/acl.go读取--verbose标志调用validator.ValidateAccessControl(ctx.config, ...)校验访问控制配置若配置存在错误则直接报错退出用authorization.NewAuthorizer(ctx.config)构建授权器从命令行标志构造主体Subject与对象Object调用authorizer.GetRuleMatchResults(subject, object)得到逐条规则的匹配结果调用runAccessControlCheck输出格式化结果。输出格式与图例Legend解读命令的核心输出是一张表格表头固定为internal/commands/acl.go# Domain Resource Query Method Network Subject表格的每一行代表配置中的一条规则按配置顺序编号行首标记与各列取值遵循官方文档给出的图例符号含义#规则在配置中的位置从 1 开始*第一个完全匹配fully matched的规则~潜在匹配potential match即如果用户完成了认证可能命中此规则hit该列条件与请求匹配miss该列条件与请求不匹配may该列条件可能匹配例如 subjects 部分匹配hit / miss / may 的判定来源这三个取值由 internal/commands/acl.go 中的hitMissMay函数计算得出对规则在某一维度Domain、Resource、Query、Method、Network、Subject的匹配布尔值汇总——全部为真输出hit全部为假输出miss真假混杂输出may。其中 Subject 列会同时考虑MatchSubjects与MatchSubjectsExact两个布尔值因此当规则包含多个用户/组条件、只有部分匹配时该列会显示may。行首标记的语义行首标记在accessControlCheckWriteOutput中根据每条规则的RuleMatchResult生成internal/commands/acl.go*该规则IsMatch()为真且未被跳过——所有条件维度全部精确匹配~该规则IsPotentialMatch()为真——域、资源、查询、方法、网络都匹配但主体subjects只是可能匹配例如规则限定了特定用户或用户组而当前模拟请求是匿名状态空白该规则未匹配。完全匹配与潜在匹配的源码判定在 internal/authorization/types.go 中// IsMatch returns true if all the criteria matched. func (r RuleMatchResult) IsMatch() (match bool) { return r.MatchDomain r.MatchResources r.MatchQuery r.MatchMethods r.MatchNetworks r.MatchSubjectsExact } // IsPotentialMatch returns true if the rule is potentially a match. func (r RuleMatchResult) IsPotentialMatch() (match bool) { return r.MatchDomain r.MatchResources r.MatchQuery r.MatchMethods r.MatchNetworks r.MatchSubjects !r.MatchSubjectsExact }两者唯一的区别在于主体的匹配程度IsMatch要求MatchSubjectsExact为真即用户身份信息用户名/组与规则中的subjects条件完全吻合而IsPotentialMatch只要求MatchSubjects为真即规则有主体条件但模拟请求的用户信息不足以确认如匿名请求遇到限定用户的规则此时判定为潜在匹配。需要理解的是潜在匹配 ≠ 最终不生效。正如官方文档 Notes 中所强调的A rule that potentially matches a request will cause a redirection to occur in order to perform one-factor authentication. This is so Authelia can adequately determine if the rule actually matches.即当一条规则对当前请求是潜在匹配时Authelia 在真实请求处理中会先引导用户完成一次认证以确定该规则是否真正命中。这解释了为什么一个看起来应该放行的 URL 可能仍会触发跳转——因为需要先确认用户身份才能完成规则判定。命令行选项详解命令支持的选项在 internal/commands/acl.go 中注册与官方文档一致选项类型默认值说明--url stringstring必填请求对象object的 URL如https://example.com--method stringstringGET请求对象object的 HTTP 方法如GET、POST--username stringstring空主体subject的用户名--groups stringsstring slice空主体subject所属的用户组多个组用逗号分隔--ip stringstring空主体subject的来源 IP 地址--verboseboolfalse启用详细输出-h, --helpbool-显示帮助信息选项的底层处理逻辑从 internal/commands/acl.go 的getSubjectAndObjectFromFlags可以看出各选项如何被消费--url唯一必填项。通过authorization.NewObjectMethodURL解析internal/authorization/types.go内部使用url.ParseRequestURI校验因此无效 URL 会直接报错——测试用例ShouldErrorOnInvalidURLFlag与ShouldErrInvalidURL验证了这一点如://invalid会返回missing protocol scheme。--method默认值为GET源码中为fasthttp.MethodGet。解析后的对象还会进行归一化URL 的 scheme 与 host 转为小写、方法转为大写见NewObjectinternal/authorization/types.go。--ip通过net.ParseIP解析为net.IP用于匹配规则中的network条件。--username/--groups与--ip一起构成authorization.Subjectinternal/authorization/types.go其中groups使用StringSlice类型支持逗号分隔的多个值。从父命令继承的选项与所有authelia子命令一致check-policy还继承了两个全局选项-c, --config strings 配置加载的文件或目录更多信息运行 authelia -h authelia config默认 [configuration.yml] --config.experimental.filters strings 应用于所有配置文件的过滤器列表更多信息运行 authelia -h authelia filters其中-c/--config默认加载当前目录下的configuration.yml。由于命令执行前会先经HelperConfigLoadRunE加载配置指定的配置文件必须包含合法的access_control配置段否则会在ValidateAccessControl阶段报出 failed to execute command due to errors in the configuration 错误。使用示例与预期输出分析官方文档提供了 5 个由浅入深的示例下面逐一拆解。示例 1仅指定 URL——匿名请求的基准检查authelia access-control check-policy --config config.yml --url https://example.com只提供 URL方法使用默认值GET用户名、组、IP 均为空。输出第一行会显示Performing policy check for request to https://example.com method GET.随后逐行列出每条规则对该请求的匹配情况。由于未提供任何用户信息凡是带subjects限定的规则都会显示为~潜在匹配。示例 2追加用户名authelia access-control check-policy --config config.yml --url https://example.com --username john模拟用户john的请求。此时规则中subjects: - user: john之类的精确用户匹配会被判定为*完全匹配而仅匹配其他用户的规则则保持miss。示例 3追加用户组authelia access-control check-policy --config config.yml --url https://example.com --groups admin,public以admin和public两个组模拟请求groups是 StringSlice逗号分隔即可。对应subjects: - group: admin或group: public的规则会精确命中。示例 4追加 HTTP 方法authelia access-control check-policy --config config.yml --url https://example.com --username john --method GET显式指定GET方法与默认值一致。若配置中规则使用methods: - POST则该规则在 Method 列显示miss在方法维度使用通配符的规则仍会命中。测试用例ShouldSucceedWithVerboseOutput使用了POST方法验证了方法维度的匹配行为。示例 5启用详细输出authelia access-control check-policy --config config.yml --url https://example.com --username john --method GET --verbose--verbose的关键作用是改变Skipped规则的显示策略。从 internal/commands/acl.go 的源码看规则结果带Skipped标记——一旦出现一条完全匹配的规则其后所有规则都会被标记为跳过见GetRuleMatchResults中skipped skipped || results[i].IsMatch()internal/authorization/authorizer.go。默认非 verbose模式下遇到第一个被跳过的规则就停止输出而 verbose 模式会列出全部规则包括已被跳过不会生效的规则便于完整审视配置。测试用例ShouldBreakOnSkippedWhenNotVerbose验证了这一行为。输出结论的四种形态无论规则匹配情况如何命令最终都会给出一个明确的结论行internal/commands/acl.go共有四种形态存在完全匹配且没有更靠前的潜在匹配The policy policy from rule #N will be applied to this request.既有完全匹配又有更靠前的潜在匹配The policy potential from rule #N1 will potentially be applied to this request. If not policy applied from rule #N2 will be.只有潜在匹配The policy potential from rule #N will potentially be applied to this request. Otherwise the policy default from the default policy will be.无任何匹配The policy default from the default policy will be applied to this request as no rules matched the request.此外还有一个特殊分支当配置中完全没有配置任何规则时命令直接输出internal/commands/acl.goThe default policy default will be applied to ALL requests as no rules are configured.这四种结论逻辑与accessControlCheckWriteOutput中appliedPos/potentialPos的组合判断一一对应并已被测试用例ShouldApplyPolicyWhenMatchedRule、ShouldPreferPotentialWhenBeforeApplied、ShouldHandleMaybeMatch等完整覆盖。结合实战一个完整的检查示例假设config.yml中包含如下访问控制配置access_control: default_policy: deny rules: - domain: example.com policy: bypass - domain: *.example.com policy: one_factor methods: [POST] - domain: admin.example.com policy: two_factor subjects: - group: admins运行authelia access-control check-policy --config config.yml --url https://example.com --username john --groups admins --ip 192.168.1.1输出大致如下示意具体以实际为准Performing policy check for request to https://example.com method GET username john groups admins from IP 192.168.1.1. # Domain Resource Query Method Network Subject * 1 hit hit hit hit hit hit The policy bypass from rule #1 will be applied to this request.可以看到规则 #1example.com的bypass完全匹配结论为放行。若将 URL 换为https://admin.example.com则第 3 条规则的Domain列命中但由于请求未携带认证信息、组admins属于精确匹配但匿名主体无法确认可能呈现~潜在匹配最终输出will potentially be applied提示对应真实场景中会先触发认证以确定是否命中two_factor。命令背后的执行链路小结综合源码check-policy的完整调用链为配置加载PreRunE中的HelperConfigLoadRunE读取--config指定的文件internal/commands/acl.go配置校验validator.ValidateAccessControl校验访问控制段合法性授权器构建authorization.NewAuthorizer依据default_policy与规则列表创建授权器internal/authorization/authorizer.go主体/对象构造getSubjectAndObjectFromFlags解析各 flag 并归一化URL 小写化、方法大写化、IP 解析逐规则匹配GetRuleMatchResults遍历规则逐维度计算MatchDomain/MatchResources/MatchQuery/MatchMethods/MatchNetworks/MatchSubjects/MatchSubjectsExactinternal/authorization/authorizer.go规则维度的具体判定逻辑在 internal/authorization/access_control_rule.go结果输出runAccessControlCheck用tabwriter生成对齐表格并输出最终结论。该命令不修改任何持久化状态也不依赖服务运行纯粹基于配置文件离线计算因此可以放心地在排障、CI 校验或规则上线前使用。总结authelia access-control check-policy是理解与调试 Authelia 访问控制配置的利器它把哪个规则生效、哪个规则只是潜在匹配、最终应用什么策略这些原本藏在请求处理流程里的逻辑以一张清晰的表格和一句明确的结论直接呈现出来。掌握其hit/miss/may图例、*/~标记语义以及四种结论形态就能在几分钟内定位绝大多数 ACL 配置问题再结合--verbose与完整的用户/组/IP 参数即可覆盖从匿名请求到多组用户的各种真实场景。若需了解访问控制规则的配置语法与策略定义可进一步查阅 访问控制配置文档。【免费下载链接】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），仅供参考
