Autheliaauthelia-gen misc oidc命令详解生成 OpenID Connect 1.0 配置与一致性测试方案【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaauthelia-gen是 Authelia 仓库内置的代码/文档生成器工具而misc oidc是其下专门负责生成 OpenID Connect 1.0 相关配置的命令族。本文以 authelia-gen misc oidc 参考文档 为主线完整解析该命令的选项体系并深入其核心子命令conformance结合源码说明它是如何批量生成 OIDC 一致性测试Conformance方案 JSON 与可直接合并进 Authelia 配置文件的客户端清单 YAML 的。读完本文你将掌握authelia-gen misc oidc的完整用法、每个参数的含义与默认值以及它背后构建测试方案 → 调用一致性测试平台 API → 输出客户端配置的完整工作流。命令概览misc oidc在 authelia-gen 中的位置authelia-gen根命令的入口定义在 cmd/authelia-gen/cmd_root.go其Short描述为 Authelias generator tooling。根命令下注册了code、contributors、docs、github、locales、commit-lint、misc、release等子命令组而miscGenerate miscellaneous things下又挂载了两个子命令见 cmd_misc.gomisc oidc—— Generate OpenID Connect 1.0 configurations即本文主题misc locale-move—— Move locales between namespaces。其中misc oidc自身并不直接执行任何逻辑它只是一个命令容器DisableAutoGenTag: true无RunE唯一的职责是承载子命令conformance见 cmd_misc.go。命令层级可表示为authelia-gen └── misc ├── oidc │ └── conformance ← 真正干活的地方 └── locale-move这与文档末尾的 SEE ALSO 栏目完全对应authelia-gen misc oidc同时链接到父命令 authelia-gen misc 和子命令 authelia-gen misc oidc conformance。基础用法与自有选项authelia-gen misc oidc自身的帮助信息只有一行-h, --help help for oidc也就是说单独执行authelia-gen misc oidc不会产生任何输出必须配合其子命令conformance使用。这一点也说明文档将oidc作为一个命令族command group看待而不是一个可执行动作。它与 CLI 文档生成器docs cli见 cmd_docs_cli.go配合共同构成了 Authelia 对 OIDC 配置生成能力的对外接口。继承自父命令的持久化选项与所有authelia-gen子命令一样misc oidc继承了根命令定义的全部持久化标志persistent flags这些标志在 cmd_root.go 中逐一声明。它们主要用于指定仓库目录结构、文档输出路径、GitHub 模板文件、JSON Schema 输出位置等生成环境参数绝大多数在生成 OIDC 配置的场景中不需要修改保持默认值即可-C, --cwd string Sets the CWD for git commands --dir.authentication string The authentication directory in relation to the root (default internal/authentication) --dir.docs string The directory with the docs (default docs) --dir.docs.adr string The directory with the ADR data (default reference/architecture-decision-log) --dir.docs.cli-reference string The directory to store the markdown in (default reference/cli) --dir.docs.content string The directory with the docs content (default content) --dir.docs.data string The directory with the docs data (default data) --dir.docs.static string The directory with the docs static files (default static) --dir.docs.static.json-schemas string The directory with the docs static JSONSchema files (default schemas) --dir.locales string The locales directory in relation to the root (default internal/server/locales) -d, --dir.root string The repository root (default ./) --dir.schema string The schema directory in relation to the root (default internal/configuration/schema) --dir.web string The repository web directory in relation to the root directory (default web) -X, --exclude strings Sets the names of excluded generators --file.bug-report string Sets the path of the bug report issue template file (default .github/ISSUE_TEMPLATE/bug-report.yml) --file.commit-lint-config string The commit lint javascript configuration file in relation to the root (default commitlint.config.mjs) --file.configuration-keys string Sets the path of the keys file (default internal/configuration/schema/keys.go) --file.docs-commit-msg-guidelines string The commit message guidelines documentation file in relation to the root (default docs/content/contributing/guidelines/commit-message.md) --file.docs.data.keys string Sets the path of the docs keys file (default configkeys.json) --file.docs.data.languages string The languages docs data file in relation to the docs data folder (default languages.json) --file.docs.data.misc string The misc docs data file in relation to the docs data folder (default misc.json) --file.docs.static.json-schemas.configuration string Sets the path of the configuration JSONSchema (default configuration) --file.docs.static.json-schemas.exports.identifiers string Sets the path of the identifiers export JSONSchema (default exports.identifiers) --file.docs.static.json-schemas.exports.totp string Sets the path of the TOTP export JSONSchema (default exports.totp) --file.docs.static.json-schemas.exports.webauthn string Sets the path of the WebAuthn export JSONSchema (default exports.webauthn) --file.docs.static.json-schemas.user-database string Sets the path of the user database JSONSchema (default user-database) --file.feature-request string Sets the path of the feature request issue template file (default .github/ISSUE_TEMPLATE/feature-request.yml) --file.scripts.gen string Sets the path of the authelia-scripts gen file (default cmd/authelia-scripts/cmd/gen.go) --file.server.generated string Sets the path of the server generated file (default internal/server/gen.go) --file.web.i18n string The i18n typescript configuration file in relation to the web directory (default src/i18n/index.ts) --file.web.package string The node package configuration file in relation to the web directory (default package.json) --latest Enables latest functionality with several generators like the JSON Schema generator --next Enables next functionality with several generators like the JSON Schema generator --package.configuration.keys string Sets the package name of the keys file (default schema) --package.scripts.gen string Sets the package name of the authelia-scripts gen file (default cmd) --version-count int the maximum number of minor versions to list in output templates (default 5) --versions strings The versions to run the generator for, the special versions current and next are mutually exclusive其中几个值得注意的语义-d, --dir.root默认./与-C, --cwd默认空决定了生成器在哪个仓库根目录下运行--versions、--latest、--next用于控制多版本含current/next特殊版本两者互斥下的生成行为--dir.docs.cli-reference默认reference/cli正是本参考文档所在目录docs/content/reference/cli的配置来源——也就是说本文档 本身也是由authelia-gen docs cli通过 cobra 的doc.GenMarkdownTreeCustom自动生成的见 cmd_docs_cli.go因此它与命令行实现始终保持一致。核心子命令authelia-gen misc oidc conformanceconformance是misc oidc下唯一的实际功能命令用于Generate OpenID Connect 1.0 conformance configurations。其完整命令行为authelia-gen misc oidc conformance [flags]它的自有选项定义在 cmd_misc.go--authelia-url string authelia url for conformance plans (default https://auth.example.com) --brand string brand name to use (default authelia) --consent string name of the consent mode to use (default implicit) -h, --help help for conformance --policy string name of the authorization policy to use (default one_factor) --suites strings names of the plans to generate --token string conformance api token --url string conformance suite url for conformance plans (default https://conformance.example.com) --version string version name各参数作用如下参数默认值含义--authelia-urlhttps://auth.example.com被测 Authelia 实例的公开地址用于拼接 OIDC Discovery 地址/.well-known/openid-configuration--urlhttps://conformance.example.comOpenID 一致性测试套件conformance suite的地址用于拼接回调地址与调用其 API--token空一致性测试平台的 API Token提供后才会上传测试方案--version空版本名称会写入每个测试方案的描述与别名--suites空全部要生成的测试方案名列表逗号分隔多值留空则生成全部 7 个方案--consentimplicit生成的 OIDC 客户端使用的授权同意模式consent mode--policyone_factor生成的 OIDC 客户端使用的授权策略authorization policy--brandauthelia品牌名用于方案别名与描述源码视角一次生成的完整执行流程执行conformance时miscOIDCConformanceRunEcmd_misc.go先逐项读取标志并校验 URL 合法性随后调用核心函数miscOIDCConformancecmd_misc.go。整体流程可概括为四步构建测试方案miscOIDCConformanceBuildSuites根据--suites过滤出需要生成的方案列表逐个写出方案 JSON每个方案以方案名.json文件写出例如conformance-basic.json采用 2 空格缩进的 JSON 编码上传方案到一致性平台仅当同时提供了--url与--token时通过doOIDCConformanceSuitePostPlan将方案POST到平台{url}/api/plan端点并校验返回状态码必须为201 Created聚合客户端配置把所有方案涉及的所有客户端汇总写入conformance-clients.yaml顶层结构为identity_providers.oidc.clients对应 OpenIDConnectClients 结构体。其中第 3 步的 HTTP 客户端使用了自定义的RequestHeaderTransportcmd_misc.go为每次请求附加Content-Type: application/json与Authorization: Bearer token头上传时通过查询参数携带planName与 JSON 序列化的variant见 doOIDCConformanceSuitePostPlan。若未提供 token则仅生成文件、不上传方便离线预演。七大内置测试方案miscOIDCConformanceBuildSuitescmd_misc.go内置了 7 个方案分别对应 OpenID Connect 认证流程的官方一致性测试计划plan name 常量见 const.go方案名--suites 取值友好名称对应测试计划 API 名称configConfigoidcc-config-certification-test-planbasicBasicoidcc-basic-certification-test-planbasic-form-postBasic (Form Post)oidcc-formpost-basic-certification-test-planhybridHybridoidcc-hybrid-certification-test-planhybrid-form-postHybrid (Form Post)oidcc-formpost-hybrid-certification-test-planimplicitImplicitoidcc-implicit-certification-test-planimplicit-form-postImplicit (Form Post)oidcc-formpost-implicit-certification-test-plan例如authelia-gen misc oidc conformance --version 4.40 --suites basic只会生成basic一个方案不带--suites则生成全部 7 个方案。方案内容的结构化生成每个方案由OpenIDConnectConformanceSuiteBuilder.Build()openid_conformance.go生成其 JSON 结构定义在 types.go。以--version 4.40、品牌authelia为例方案的生成规则如下命名与别名方案名为conformance-name别名形如conformance-basic-authelia440——由name的小写拼接brand与去点后的版本号组成描述形如Authelia 4.40 Basic Certification Profile非认证模式certification 为 false时后缀为Test Profile并采用conformance-test作为客户端 ID 前缀服务器信息discoveryUrl固定为--authelia-url拼接/.well-known/openid-configurationpublish固定为summaryvariant除config外的 6 个方案均声明server_metadata: discovery与client_registration: static_client见 openid_conformance.go。按流程区分的授权类型与响应模式Build()根据方案名动态决定三个关键能力集合Basic 类basic / basic-form-postgrant_types为authorization_coderefresh_tokenresponse_types仅codeImplicit 类implicit / implicit-form-postgrant_types为authorization_codeimplicitrefresh_tokenresponse_types为code、id_token、token、id_token tokenHybrid 类hybrid / hybrid-form-postgrant_types与 Implicit 相同response_types为code、code id_token、code token、code id_token token响应模式普通方案使用queryquery.jwt三个 Form Post 方案使用form_postform_post.jwt见 openid_conformance.go。这些取值直接复用了internal/oidc包中定义的常量如oidc.GrantTypeAuthorizationCode、oidc.ResponseModeFormPost等与 Authelia 运行时支持的枚举一一对应。客户端与密钥的自动生成除config方案外每个方案都会生成3 个 OIDC 客户端openid_conformance.go主客户端client_secret_basic 认证备用客户端-alt同样使用 client_secret_basicSecret Post 客户端-post使用 client_secret_post 认证方式。每个客户端的密钥为随机生成的 80 位字母数字字符串random.CharSetAlphaNumeric见 openid_conformance.go并立即通过MustHash使用PBKDF2摘要算法openid_conformance.go哈希后写入 Authelia 配置——也就是说conformance-clients.yaml中保存的是client_secret的密码摘要而非明文符合 Authelia 对客户端密钥的安全要求。每个客户端还包含以下固定配置redirect_uris指向一致性平台的回调地址suite-url/test/a/alias/callbackscopes包含openid、offline_access、profile、email、phone、address及allrequest_object_signing_alg为noneauthorization_policy与consent_mode则取自--policy与--consent参数。生成产物与 Authelia 配置的衔接一次完整的执行会在当前目录产出两类文件方案文件conformance-config.json、conformance-basic.json、conformance-basic-form-post.json、conformance-hybrid.json、conformance-hybrid-form-post.json、conformance-implicit.json、conformance-implicit-form-post.json未过滤时全部生成客户端清单conformance-clients.yaml结构如下示意identity_providers: oidc: clients: - client_id: conformance-certification-basic-authelia440 client_name: Authelia 4.40 Basic Certification Profile client_secret: PBKDF2 摘要 redirect_uris: - https://conformance.example.com/test/a/conformance-basic-authelia440/callback authorization_policy: one_factor consent_mode: implicit public: false scopes: [openid, offline_access, profile, email, phone, address, all] response_types: [code] grant_types: [authorization_code, refresh_token] response_modes: [query, query.jwt] token_endpoint_auth_method: client_secret_basic request_object_signing_alg: none这份 YAML 可以直接合并进 Authelia 主配置文件configuration.identity_providers.oidc.clients段。其字段与 internal/configuration/schema/identity_providers.go 中IdentityProvidersOpenIDConnectClient结构体的 koanf/yaml 标签完全对齐——例如authorization_policy、consent_mode、scopes、grant_types、response_types、response_modes、token_endpoint_auth_method等字段运行时 schema 均给出了严格的枚举校验如response_modes只接受form_post、query、fragment及各自的.jwt变体。测试用例如何验证生成逻辑仓库中的单元测试 openid_conformance_test.go 对上述逻辑进行了逐方案断言TestOpenIDConnectConformanceSuiteBuilder_Build覆盖config、basic、basic-form-post、implicit、implicit-form-post、hybrid、hybrid-form-post全部 7 种场景逐一校验方案的 Name、Plan别名、描述、discovery URL、variant、3 个客户端ID、Name、Secret 有效性、RedirectURIs、ResponseModes、ResponseTypes、GrantTypes、TokenEndpointAuthMethod以及--suites过滤行为TestMustHash则验证 PBKDF2 摘要函数不会 panic。如果你在本地修改了生成逻辑可以运行go test ./cmd/authelia-gen/ -run TestOpenIDConnectConformanceSuiteBuilder_Build|TestMustHash -v来回归验证。这些测试同样确认了config方案不生成客户端这一设计。典型使用场景与注意事项使用场景当需要针对某个 Authelia 版本跑一遍 OpenID Connect 官方一致性测试如 OpenID Certification 认证时可以这样组合使用# 生成全部 7 个方案并上传到一致性测试平台注意替换真实 URL 与 token authelia-gen misc oidc conformance \ --authelia-url https://auth.example.com \ --url https://conformance.example.com \ --token your-api-token \ --version 4.40 # 只生成并预览 basic 方案不上传、不联网 authelia-gen misc oidc conformance \ --authelia-url https://auth.example.com \ --url https://conformance.example.com \ --version 4.40 \ --suites basic注意事项--authelia-url与--url必须为合法绝对 URI源码中通过url.ParseRequestURI校验格式非法会直接报错上传方案要求平台返回201 Created否则整个命令以非零状态退出因此离线环境下应省略--token--suites采用字符串切片StringSlice解析多个方案名用逗号分隔例如--suites basic,hybrid--consent与--policy会原样写入每个客户端取值需符合 identity_providers.go 中authorization_policy如one_factor、two_factor与consent_mode如implicit、explicit、pre-configured、auto的合法枚举命令在当前工作目录下输出.json方案文件与conformance-clients.yaml运行前请确认目标目录写入权限由于conformance-clients.yaml通过os.O_TRUNC打开cmd_misc.go重复执行会覆盖旧文件。关联文档导航父命令authelia-gen misc核心子命令authelia-gen misc oidc conformance相关源码cmd_misc.go、openid_conformance.go、openid_conformance_test.go、cmd_root.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），仅供参考