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）

本指南在以下版本组合下经过验证：

• Authelia：v4.38.0
• Uptime Kuma：v1.23.11

场景假设（Assumptions）

为便于说明，本示例基于以下假设值，你可根据实际部署替换：

本指南中的部分值支持通过文档变量自动替换（如域名变量），实际部署时请替换为你的真实域名与密钥。

工作原理：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 集成指南。

其核心链路为：

1. Uptime Kuma 通过Client Credentials 授权流向 Authelia 的 Token 端点换取 Access Token；
2. Token 被授予authelia.bearer.authzscope 并携带指定的audience（即待监控资源 URL）；
3. Uptime Kuma 监控请求时把该 Token 以Bearerscheme 放入Authorization请求头发送给受保护资源；
4. 反向代理将请求转发到 Authelia 的授权端点（authz endpoint），Authelia 内省（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 参考指南

同时需要理解三个关键点：

1. implementation必须与你的代理匹配：server区块下 authz 端点的implementation取值（如ForwardAuth、ExtAuthz、AuthRequest、Legacy）必须与你的反向代理类型相符；
2. endpoint_name即实际端点路径：endpoint_name决定了授权端点的实际路径，端点统一位于/api/authz/<endpoint_name>。需要注意——只要配置了一个自定义端点，其他默认授权端点（如/api/verify、/api/authz/forward-auth等）就会被全部移除；
3. 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_method：client_secret_basic，即客户端使用 HTTP Basic 方式在 Token 端点进行认证；
• client_secret：配置中存放的是明文insecure_secret的PBKDF2-SHA512 摘要，生产环境务必使用 Authelia 提供的哈希生成工具生成自己的摘要。

Uptime Kuma 侧配置

Uptime Kuma 只有一种配置方式：通过Web 图形界面（Web GUI）完成。

Web GUI 配置步骤

1. 新建一个状态监控器，或编辑现有的监控器；
2. 选择监控类型，例如HTTP(s) Keyword（HTTP 关键字），并设置一个期望在响应中找到的关键字；
3. 设置待监控的 URL（该 URL 必须与 Authelia 客户端配置中的audience参数一一对应）；
4. 按以下内容配置认证选项：

其中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