Authelia 与 Uptime Kuma 集成指南：基于 OpenID Connect 1.0 Client Credentials 的 SSO 监控认证

Authelia 与 Uptime Kuma 集成指南基于 OpenID Connect 1.0 Client Credentials 的 SSO 监控认证【免费下载链接】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 官方 OpenID Connect 1.0 集成指南之一完整讲解如何将开源监控工具 Uptime Kuma 接入 Authelia 的 OIDC 提供方通过client_credentials客户端凭证授权流程和authelia.bearer.authz专用 scope让 Uptime Kuma 在无需用户登录会话的情况下对受保护资源执行 HTTP 状态监控。读完本文你将掌握 Authelia 的 Server Authz Endpoints 自定义端点、Bearer Token 授权方案、客户端 audience 配置以及 Uptime Kuma 侧 OAuth2 认证的完整配置方法。适用版本Tested Versions本指南在以下版本组合下经过验证Autheliav4.38.0Uptime Kumav1.23.11场景假设Assumptions为便于说明本示例基于以下假设值你可根据实际部署替换项目假设值应用根 URLUptime Kumahttps://uptime-kuma.example.com/Authelia 根 URLhttps://auth.example.com/Client IDuptime-kumaClient Secretinsecure_secret受保护资源 URLhttps://application.example.com/本指南中的部分值支持通过文档变量自动替换如域名变量实际部署时请替换为你的真实域名与密钥。工作原理OAuth 2.0 Bearer Token 授权Uptime Kuma 集成依赖 Authelia 的一项特殊能力将 Access Token 作为 Bearer Token 用于授权以替代标准的会话 Cookie 转发授权流Session Cookie Forwarded Authorization Flow。该能力遵循 [RFC 6750: OAuth 2.0 Bearer Token Usage] 规范实现详细说明见仓库中的 OAuth 2.0 Bearer Token Usage 集成指南。其核心链路为Uptime Kuma 通过Client Credentials 授权流向 Authelia 的 Token 端点换取 Access TokenToken 被授予authelia.bearer.authzscope 并携带指定的audience即待监控资源 URLUptime Kuma 监控请求时把该 Token 以Bearerscheme 放入Authorization请求头发送给受保护资源反向代理将请求转发到 Authelia 的授权端点authz endpointAuthelia 内省Introspect该 Token校验 scope、audience、有效期等再结合access_control规则决定放行或拒绝。从源码可以看到该 scope 在 internal/oidc/const.go 中被定义为常量ScopeAutheliaBearerAuthz authelia.bearer.authz并且 internal/oidc/util.go 强制校验该 scope只能单独请求或与offline_accessscope 一同请求不允许与openid等其他 scope 混用否则返回ErrInvalidScope。在授权端点的 Bearer 处理链路上internal/handlers/handler_authz_authn.go 负责完成 Token 内省先校验 Token 必须是 Access Token前缀为authelia_at_而非刷新令牌authelia_rt_或授权码authelia_ac_随后检查客户端是否注册了authelia.bearer.authzscope、audience 是否匹配最终解析出对应的用户或客户端身份用于匹配访问控制规则。重要安全前置说明本实现涉及 Authelia 较新且较为特殊的配置区块动手配置前务必先完整阅读以下两份文档Server Authz Endpoints 配置指南Proxy Authorization 参考指南同时需要理解三个关键点implementation必须与你的代理匹配server区块下 authz 端点的implementation取值如ForwardAuth、ExtAuthz、AuthRequest、Legacy必须与你的反向代理类型相符endpoint_name即实际端点路径endpoint_name决定了授权端点的实际路径端点统一位于/api/authz/endpoint_name。需要注意——只要配置了一个自定义端点其他默认授权端点如/api/verify、/api/authz/forward-auth等就会被全部移除HeaderAuthorization策略是叠加式认证在本配置中它允许请求通过Authorization头携带 Bearer Token 进行认证同时仍然保留基于 Cookie 的会话授权方式两种认证策略共存。Authelia 侧配置以下是完整的示例Authelia客户端配置configuration.yml与上文假设值配套使用server: endpoints: authz: endpoint_name: implementation: authn_strategies: - name: HeaderAuthorization schemes: - Basic - Bearer - name: CookieSession access_control: rules: - domain: - application.example.com subject: oauth2:client:uptime-kuma policy: one_factor 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: uptime-kuma client_name: Uptime Kuma client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng # The digest of insecure_secret. public: false require_pkce: false pkce_challenge_method: requested_audience_mode: implicit scopes: - authelia.bearer.authz audience: - https://application.example.com/ grant_types: - client_credentials access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: client_secret_basic配置要点逐项解读Server Authz Endpoints 区块endpoint_name自定义的授权端点名称最终路径为/api/authz/endpoint_name配置后默认端点全部失效详见 Server Authz Endpoints 配置指南implementation根据代理类型填写ForwardAuth/ExtAuthz/AuthRequest/Legacy具体差异见 Proxy Authorization 参考指南authn_strategies认证策略按顺序尝试第一个成功的策略生效。HeaderAuthorization策略在此启用了Basic与Bearer两种 scheme随后是CookieSession兜底会话认证策略执行逻辑可参见 internal/handlers/handler_authz_builder.go。Access Control 区块oauth2:client:uptime-kuma是一种特殊主体subject它指向uptime-kuma这个客户端 ID允许通过 Client Credentials 授权流签发、且签发给该客户端的 Access Token 使用本规则由于 Client Credentials 授权流签发的 Token始终按 1FA 认证级别处理因此这里只能使用one_factor策略。OIDC 客户端区块requested_audience_mode: implicit默认值为explicit要求客户端必须显式通过audience表单参数请求 audience 才会签发设为implicit后当客户端未显式请求 audience 时自动视为请求其被允许请求的全部 audience。由于 Uptime Kuma 目前不支持发送audience表单参数本配置必须设置为implicit两种模式的行为对照详见 OpenID Connect 1.0 Clients 配置文档audience填写你希望用 Uptime Kuma 监控的受保护资源端点可配置多个即上文假设中的https://application.example.com/scopes仅包含authelia.bearer.authz可额外添加offline_access但不可混用其他 scope这是 internal/oidc/util.go 强制执行的校验grant_types仅client_credentials对应 Uptime Kuma 的机器对机器监控场景token_endpoint_auth_methodclient_secret_basic即客户端使用 HTTP Basic 方式在 Token 端点进行认证client_secret配置中存放的是明文insecure_secret的PBKDF2-SHA512 摘要生产环境务必使用 Authelia 提供的哈希生成工具生成自己的摘要。Uptime Kuma 侧配置Uptime Kuma 只有一种配置方式通过Web 图形界面Web GUI完成。Web GUI 配置步骤新建一个状态监控器或编辑现有的监控器选择监控类型例如HTTP(s) KeywordHTTP 关键字并设置一个期望在响应中找到的关键字设置待监控的 URL该 URL 必须与 Authelia 客户端配置中的audience参数一一对应按以下内容配置认证选项配置项值MethodOAuth2: Client CredentialsAuthentication MethodAuthorization HeaderOAuth Token URLhttps://auth.example.com/api/oidc/tokenClient IDuptime-kumaClient Secretinsecure_secretOAuth Scopeauthelia.bearer.authz其中OAuth Token URL指向 Authelia 的 OIDC Token 端点即https://authelia根域名/api/oidc/token。下方截图展示了 Uptime Kuma 中上述认证配置的示例安全注意事项与调优建议务必结合 Bearer Token 指南阅读本集成建立在 OAuth 2.0 Bearer Token Usage 之上其中列出了多项强制性的客户端注册约束scope 白名单、PAR/PKCE S256、显式 consent 模式、受支持的 grant type 与 response type 等建议在配置生产环境前通读authelia.bearer.authz的防护设计该授权方案默认不启用必须显式在授权端点配置Bearerscheme且 Token 必须同时满足具备该 scope、通过 Bearer scheme 提交、未过期未吊销、确为 Access Token等条件见 internal/handlers/handler_authz_authn.go 的内省校验逻辑audience 严格匹配授权请求的 resource 与 Token 的 granted audience 按大小写敏感的精确字符串匹配路径不一致如缺少末尾/会导致授权被拒绝监控目标差异若你监控的是需要登录的 Web 应用请改用 Authorization Code 授权流与用户绑定Client Credentials 流适合纯 API / 无需用户会话的监控场景且始终按 1FA 处理只对one_factor规则有效。相关文档索引OpenID Connect 1.0 集成总览OAuth 2.0 Bearer Token Usage 集成指南Server Authz Endpoints 配置指南Proxy Authorization 参考指南OpenID Connect 1.0 Clients 配置文档OpenID Connect 1.0 Provider 配置文档【免费下载链接】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），仅供参考