Authelia 与 Incus 集成指南基于 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/authelia本指南以 Authelia 官方集成文档为蓝本完整讲解如何将 IncusLinux Containers 社区开源的容器与虚拟机管理系统接入 Authelia 的 OpenID Connect 1.0 Provider实现以 Authelia 为统一身份源的 SSO 登录。读完本文后你将能够在 Authelia 中正确注册 Incus 客户端、在 Incus 侧通过 CLI 完成 OIDC 对接配置并理解 issuer、audience、redirect_uri 等关键参数为何必须严格一致以及 Authelia 底层端点与令牌签发机制的工作原理。集成概览与测试版本Incus 的 Web 界面原生支持 OpenID Connect 1.0 认证可以作为 Authelia 的 Relying Party依赖方接入。官方文档标明该集成的支持级别为community社区支持并在以下版本组合上完成过验证Autheliav4.38.10Incusv6.0.1集成后用户访问 Incus Web 界面时不再直接输入本地账号密码而是跳转到 Authelia 完成认证可含 2FA认证成功后携带令牌回到 Incus即出现Login with SSO登录入口。开始之前注册客户端的通用注意事项在动手配置前有几个 OpenID Connect 1.0 注册客户端的通用要点必须提前了解对应文档模板 oidc-common 中的 Common Notesclient_id必须全局唯一每一个注册客户端的 ID 都不能与其它客户端重复。client_id的字符限制只允许包含 RFC3986 Unreserved Characters。client_secret的存储方式虽然明文存储目前仍被接受但该行为已被标记为不推荐未来不保证继续支持强烈建议使用哈希形式存储若使用哈希且工作因子过高可能导致客户端认证超时相关调优见 FAQTuning the work factors。必须补齐 Provider 级配置以下示例只给出客户端注册片段你仍须按 OpenID Connect 1.0 Provider 配置 完成 issuer、密钥、存储等强制项配置。客户端配置选项远不止这些示例仅覆盖本集成所需的最小集合完整选项清单请查阅 OpenID Connect 1.0 Clients 配置。假设值Assumptions本文示例基于以下假设配置时请替换为你自己的域名项目值应用根地址Incushttps://incus.example.com/Authelia 根地址即 OIDC Issuerhttps://auth.example.com/Client IDincus后续所有配置中的example.com与auth子域名均为文档变量占位符请按实际环境替换。第一步在 Authelia 中注册 Incus 客户端在 Authelia 的configuration.yml中为 Incus 添加如下客户端注册配置对应 OpenID Connect 1.0 Clients 文档identity_providers: oidc: ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. ## See: https://www.authelia.com/c/oidc clients: - client_id: incus client_name: Incus public: true authorization_policy: two_factor require_pkce: false pkce_challenge_method: redirect_uris: - https://incus.example.com/iodc/callback audience: - https://incus.example.com scopes: - openid - offline_access response_types: - code grant_types: - authorization_code - refresh_token access_token_signed_response_alg: RS256 userinfo_signed_response_alg: none token_endpoint_auth_method: none各关键参数的作用与约束如下依据 clients.md 的选项说明client_id/client_name客户端标识与展示名。client_name默认与client_id相同会显示在 Authelia 的 UI 中client_id必须与 Incus 侧配置的oidc.client.id完全一致。public: true将客户端类型声明为public公开。公开客户端无法安全保存机密凭据RFC 6749 Section 2.1适合 Web 前端 / CLI 工具这类场景。启用后client_secret必须留空。这也是本配置中token_endpoint_auth_method: none的原因——公开客户端在令牌端点不进行客户端认证。authorization_policy: two_factor该客户端适用的授权策略取值可为one_factor、two_factor或 Provider 侧 authorization_policies 中自定义的策略名。注意它与 访问控制规则 是两套完全不同的机制前者只作用于 Authorization Request。require_pkce: false/pkce_challenge_method: 本集成示例不强制 PKCE。若后续要开启pkce_challenge_method可选值为空字符串、plain或S256官方强烈推荐S256详见下文安全加固小节。redirect_uris允许的回调地址白名单大小写敏感未列入列表的回调将被拒绝。这里配置为https://incus.example.com/iodc/callback务必与 Incus 实际发起回调的路径完全一致包括路径段的大小写与斜杠。audience允许该客户端请求并被授予的 audience 白名单配置为 Incus 的应用根地址https://incus.example.com。它主要作用于 Access TokenID Token 的 audience 始终是请求它的客户端 ID。scopes允许消费的 scope 列表。openid是 OIDC 的必需 scopeoffline_access用于启用刷新令牌Refresh Token能力——根据 集成导论 中的 Grant Types 说明只有具备offline_accessscope 的客户端才应使用refresh_token授权类型。response_types: [code]仅启用授权码流程Authorization Code Flow这是安全等级最高且官方推荐的响应类型。grant_types授权类型白名单authorization_code用于换取令牌refresh_token配合offline_accessscope 实现令牌刷新。access_token_signed_response_alg: RS256Access Token 的签名算法。默认值为none不透明令牌此处配置为RS256后Access Token 将以 JSON Web Token 形式签发对应 OAuth 2.0 JWT Profile for Access Tokens / RFC 9068 中标记为 Complete 的支持项。userinfo_signed_response_alg: noneUserInfo 端点响应不签名直接以application/json返回对应 UserInfo 端点算法表。token_endpoint_auth_method: none令牌端点不做客户端认证与public: true配套公开客户端在令牌端点无法出示机密凭据。第二步在 Incus 侧配置 OpenID Connect配置 Incus 有两种方式官方文档只推荐其中一种CLI。前提是 Incus 的 Web 界面已经就绪并可通过https://incus.example.com/访问。依次执行以下三条命令完成配置# 1. 设置 oidc.issuer使其与 Authelia 根地址Issuer一致 incus config set oidc.issuer https://auth.example.com # 2. 设置 oidc.client.id与 Authelia 配置中的 client_id 一致 incus config set oidc.client.id incus # 3. 设置 oidc.audience与 Incus 应用根地址一致 incus config set oidc.audience https://incus.example.com也可以直接使用incus config edit一次性编辑上述键值。配置完成后可通过incus config show查看最终的配置结果应当类似config: oidc.issuer: https://auth.example.com oidc.client.id: incus oidc.audience: https://incus.example.com第三步验证登录流程完成上述两侧配置并重启相关服务后访问https://incus.example.com/Web 界面应出现Login with SSO按钮点击后浏览器被重定向到 Authelia 的授权端点用户完成登录authorization_policy: two_factor意味着需要完成两步认证认证通过后浏览器携带授权码回到 Incus 的回调地址Incus 在后台向 Authelia 令牌端点换取 Access Token / Refresh Token 并建立会话。如果按钮未出现或登录失败请优先核对issuer / client.id / audience 三值必须与 Authelia 侧完全一致这条黄金法则。原理深挖Authelia 的 OpenID Connect Provider 实现为了在排错时心中有数这里从源码与集成文档角度梳理 Authelia 作为 OP 的核心实现。发现端点与标准端点Authelia 实现了 OpenID Connect Discovery 1.0 与 OAuth 2.0 Authorization Server MetadataRelying Party如 Incus可通过以下两个 well-known 端点自动发现全部端点信息路径挂在 Authelia 根地址下即 Issuer 之后/.well-known/openid-configuration/.well-known/oauth-authorization-server可发现的端点及其实现见 集成导论Endpoint Implementations其中与本集成相关的核心端点包括端点路径以https://auth.example.com为 Issuer 示例JSON Web Key Set/jwks.jsonAuthorization/api/oidc/authorizationToken/api/oidc/tokenUserInfo/api/oidc/userinfoIntrospection/api/oidc/introspectionRevocation/api/oidc/revocation从源码结构看这些端点分别在 handler_oauth2_authorization.go、handler_oauth2_token.go、handler_oauth2_jwks.go 中实现而 Provider 的初始化、客户端配置装载与发布配置生成分别位于 internal/oidc/provider.go、internal/oidc/issuer.go 与 internal/oidc/discovery.go。Audience 策略Access Token 与 ID Token 的差异本配置中audience: [https://incus.example.com]需要理解其实际作用范围。根据 集成导论Audiences 的说明ID Token 的 audience始终且默认只包含请求它的客户端标识即incus用于向 Relying Party 传达这份令牌是发给谁的Access Token 与 Refresh Token 的 audience则是授权流程或最近一次刷新流程中实际被授予的 audience用于资源服务器 / 授权服务器内部的策略判定本示例中即为https://incus.example.com。这也是为什么 Incus 侧必须把oidc.audience设置为应用根地址、而不是 Authelia 地址的原因。若要调整 ID Token audience 的派生方式可配置 Provider 侧的 claims_policies 与id_token_audience_mode选项。令牌刷新与会话维持配置中同时声明了offline_accessscope 与refresh_tokengrant type这意味着 Incus 在 Access Token 过期后可以静默续期。Authelia 的 Audience 与 Scope 采用子集规则Request Subset Rules刷新时客户端可以请求少于、但不能多于最初被授予的 scope 与 audience。安全加固建议可选以下机制在 集成导论Security 中有完整论述虽然并非 Incus 对接的必需项但值得了解PKCERFC 7636由于 Incus 以公开客户端类型接入无法在令牌端点出示凭据启用 PKCE 可提供授权码持有证明缓解授权码拦截攻击。若 Incus 支持建议将require_pkce设为true并将pkce_challenge_method设为S256。Pushed Authorization RequestsRFC 9126可通过 Provider 级enforce或客户端级require_pushed_authorization_requests强制所有授权请求先经 PAR 端点提交显著提升抗钓鱼能力。OAuth 2.0 Authorization Server Issuer IdentificationRFC 9207允许 Relying Party 通过响应中的 issuer 参数校验响应来源若客户端支持应开启。常见问题排查现象排查方向Incus 界面不出现Login with SSO按钮确认 Web 界面可访问、oidc.issuer可达确认 Incus 版本支持 OIDC官方建议以 v6.0.1 及以上验证点击登录后报 redirect_uri 相关错误核对 redirect_uris 与 Incus 实际回调地址完全一致大小写敏感例如https://incus.example.com/iodc/callback令牌交换失败核对oidc.client.id与 Autheliaclient_id一致公开客户端必须搭配token_endpoint_auth_method: none刷新令牌失败确认已同时配置offline_accessscope 与refresh_tokengrant typeaudience 不匹配确认 Incus 的oidc.audience与 Authelia 客户端audience白名单均为应用根地址https://incus.example.com相关文档Authelia OpenID Connect 1.0 Clients 配置Authelia OpenID Connect 1.0 Provider 配置OpenID Connect 1.0 集成导论端点、响应类型、授权类型、算法表OpenID Connect 1.0 常见问题生成客户端凭据、密钥哈希等OpenID Connect 1.0 Scope 与 Claims 定义Incus OpenID Connect 官方认证文档【免费下载链接】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），仅供参考