企业官网建设流程全解析

Authelia 与 Drupal 集成指南：基于 OpenID Connect 1.0 实现单点登录（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 Provider（身份提供方），讲解如何将开源 CMS 系统 Drupal 配置为 OpenID Connect 1.0 Relying Party（依赖方/客户端），从而复用 Authelia 的集中式身份认证能力，为 Drupal 站点提供统一登录入口。读完本文后，你将掌握在 Autheliaconfiguration.yml中注册 OIDC 客户端、理解各配置项含义，以及在 Drupal 管理后台完成 OIDC Generic 客户端对接的完整实战方案，并了解整套登录流程背后的源码级原理。

测试版本与集成前提

本集成指南基于以下版本组合进行验证：

• Authelia：v4.39.24
• Drupal：v10.4.0

本示例做出如下假设（实际部署时请替换为你自己的域名与凭据）：

其中insecure_secret仅为演示用途，严禁在生产环境使用（详见下文"前置须知"）。文中出现的example.com、auth等占位符，在官方文档中可通过站点变量（sitevar）自动替换为你自己的域名。

前置须知：配置前必读

在动手配置 OIDC 注册客户端之前，有几条来自 Authelia 官方的重要规范需要了解，它们直接决定了配置能否通过校验、运行是否安全。

Client ID 与 Client Secret 的规范

1. client_id要求：
   • 每个客户端必须使用唯一值，不能与其他已注册客户端重复；
   • 只能包含 RFC3986 Unreserved Characters（即A-Z a-z 0-9 - . _ ~）；
   • 长度不能超过 100 个字符；
   • 官方推荐使用 64 位随机字符，文中drupal仅为便于阅读和演示，生产环境应使用随机生成的标识符。
2. client_secret要求：
   • 示例中的insecure_secret仅用于演示，生产环境必须使用随机生成的高强度密钥；
   • 密钥可以明文存储于 Authelia 配置中，但该行为已被标记为弃用，未来版本不保证继续支持；
   • 强烈推荐以哈希形式存储（详见下文"生成客户端密钥哈希"小节）。
3. 配置示例的范围：
   • 本文给出的 Authelia YAML 仅包含客户端注册部分，你必须同时按照 OpenID Connect 1.0 Provider 配置指南 完成 Provider 的其余必填配置（如issuer_private_keys、access_token_lifespan等）；
   • 示例只展示了客户端可用选项中的一小部分，建议通读 OpenID Connect 1.0 Clients 配置指南 了解全部选项及其影响。

密码学算法与端点位置

Authelia 作为 OpenID Connect 1.0 Provider 支持丰富的签名与加密算法。与本文示例直接相关的是userinfo_signed_response_alg: 'none'，表示 UserInfo 端点以普通 JSON（application/json）而非签名 JWT 形式返回用户信息。有关签名/加密算法全表、授权码流程（Authorization Code Flow）、响应模式（Response Mode）等协议细节，可参阅 OpenID Connect 1.0 集成介绍。

第一步：在 Authelia 中注册 OIDC 客户端

完整配置示例

在 Authelia 的configuration.yml中，于identity_providers.oidc.clients列表下追加如下客户端配置：

identity_providers: oidc: ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. clients: - client_id: 'drupal' client_name: 'Drupal' client_secret: '$pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng' # The digest of 'insecure_secret'. public: false authorization_policy: 'two_factor' redirect_uris: - 'https://drupal.example.com/openid-connect/generic' scopes: - 'openid' - 'email' - 'profile' userinfo_signed_response_alg: 'none' token_endpoint_auth_method: 'client_secret_basic'

关键配置项逐项解析

结合 OpenID Connect 1.0 Clients 配置指南 中的定义，各选项含义如下：

• client_id：客户端标识符，必须与 Drupal 端配置的 Client ID 完全一致，且满足上文提到的唯一性、字符集与长度约束。
• client_name：在 Authelia 用户界面中展示的友好名称，默认为client_id的值。
• client_secret：Authelia 与 Drupal 之间的共享密钥，两端必须一致。此处存放的是insecure_secret的 PBKDF2-SHA512 哈希摘要（对应原文注释 "The digest of 'insecure_secret'"）。
• public: false：声明这是一个机密型客户端（confidential client），即它有能力安全保管client_secret。机密型客户端必须在 Token 端点完成客户端认证，不能使用none认证方式。
• authorization_policy: 'two_factor'：指定该客户端的授权策略。two_factor表示要求用户完成双重因素认证（2FA）后才能完成授权；可选值还包括one_factor（仅需单因素）与deny（拒绝）。
• redirect_uris：允许的授权回调地址白名单。Drupal 的 OIDC Generic 模块固定回调路径为/openid-connect/generic，因此这里必须注册https://drupal.example.com/openid-connect/generic，且必须与实际部署的 Drupal 域名完全匹配。回调 URI 的校验是防止授权码被劫持的关键防线，务必精确配置。
• scopes：授权范围。openid是 OIDC 协议必需的范围；email与profile让 Authelia 在 UserInfo 响应中提供用户邮箱及基本资料（昵称、姓名等）声明。
• userinfo_signed_response_alg: 'none'：UserInfo 端点响应的签名算法。Drupal 的 OIDC Generic 客户端仅解析普通 JSON 响应，因此设为none（不签名）。若设为其他算法（如RS256），则 Drupal 无法解析签名后的 JWT 响应。
• token_endpoint_auth_method: 'client_secret_basic'：客户端在 Token 端点的认证方式。client_secret_basic表示使用 HTTP Basic Auth 方案携带 Client ID 与 Secret（依据 RFC6749 规范），这也是机密型客户端的常见默认值。

生成客户端密钥哈希

示例中的client_secret是明文insecure_secret的 PBKDF2-SHA512 摘要。在实际部署中，你可以使用 Authelia 内置的authelia crypto hash命令生成任意明文密钥的哈希值，然后将哈希填入配置。相关命令实现在 internal/commands/crypto_hash.go 中，例如：

authelia crypto hash generate pbkdf2 --password 'your-strong-secret'

输出即为可直接写入client_secret字段的哈希字符串。以哈希形式存储密钥可避免配置文件中出现明文凭据；但需注意，过高的哈希工作因子会拖慢客户端认证时的验证过程，具体调优可参阅官方 FAQ 中关于工作因子的说明。

第二步：确认 Authelia 的 OIDC 端点地址

Drupal 端需要填写三个端点地址，它们都由 Authelia 自动提供，路径固定如下（前缀为 Authelia Root URL）：

这些路径与 Authelia 服务端实现一一对应：授权端点负责处理用户浏览器重定向与授权码签发，Token 端点负责以授权码换取 ID Token / Access Token，UserInfo 端点则返回用户声明。除上述三个端点外，Authelia 还实现了jwks.json、Introspection（/api/oidc/introspection）、Revocation（/api/oidc/revocation）等端点，完整列表见 OpenID Connect 1.0 集成介绍 的"Endpoint Implementations"章节。实际上，大多数 OIDC 客户端（包括 Drupal 模块）都支持通过 Discovery 端点https://auth.example.com/.well-known/openid-configuration自动发现全部端点，可有效避免手填地址出错。

第三步：在 Drupal 中配置 OpenID Connect 客户端

Drupal 侧仅有一种配置方式，即通过 Web 图形界面（Web GUI）完成。请确保 Drupal 已安装并启用OpenID Connect模块（即 Generic 客户端实现，对应官方文档中的 Drupal OpenID Connect Generic Client 文档）。

3.1 配置 OIDC 客户端连接参数

1. 浏览器访问 Drupal 管理后台：https://drupal.example.com/admin/config/services/openid-connect。
2. 按如下表格配置各项参数：

其中 Client ID 与 Client Secret 必须和 Authelia 侧clients条目中的值一一对应；三个端点地址必须与上文"第二步"中的地址一致（若你配置了域名自动替换变量，则按实际域名拼写）。

3.2 启用注册设置覆盖

1. 继续访问 Drupal 用户账户设置页：https://drupal.example.com/admin/config/people/accounts。
2. 找到Override registration settings（覆盖注册设置）选项并启用。

这一步的作用是允许 Drupal 将首次通过 Authelia 完成 SSO 认证的新用户自动创建为本地账户，从而实现"用 Authelia 账号直接登录 Drupal、无需单独注册"的无缝体验。若未启用该选项，通过 OIDC 认证的用户可能无法在 Drupal 中自动建号，登录流程会中断。

登录流程背后的工作原理

完成上述两端配置后，整个 SSO 流程如下（与 handler_oauth2_authorization.go、handler_oauth2_token.go 等处理器实现相对应）：

1. 用户访问 Drupal 受保护页面，未认证时被重定向至 Authelia 的Authorization Endpoint（/api/oidc/authorization），携带client_id=drupal、redirect_uri=.../openid-connect/generic、scope=openid email profile等参数。
2. Authelia 校验回调地址与 Authelia Root URL 的白名单匹配关系，并向用户展示登录与（按authorization_policy要求）2FA 界面。
3. 认证成功后，Authelia 将用户浏览器重定向回 Drupal 的回调地址/openid-connect/generic，并附带授权码（authorization code）。
4. Drupal 模块携带授权码调用 Authelia 的Token Endpoint（/api/oidc/token），以client_secret_basic方式完成客户端认证，换取 ID Token 与 Access Token。
5. Drupal 再调用UserInfo Endpoint（/api/oidc/userinfo）获取email、profile等用户声明（因userinfo_signed_response_alg: 'none'，响应为普通 JSON），据此创建或匹配本地用户账户并建立登录会话。

值得注意的细节是：本示例使用client_secret_basic认证方式，客户端凭据在每次 Token 请求时都会以 HTTP Basic Auth 形式发送，因此强烈建议全程启用 HTTPS，避免凭据在传输过程中泄露。从源码结构看（参见 internal/oidc/ 目录下的 provider 与 store 实现），Authelia 对 Token 请求的客户端认证、授权码与 PKCE 校验均有严格实现，作为 Relying Party 的 Drupal 无需自行处理这些底层细节。

注意事项与安全建议

1. 密钥管理：insecure_secret与示例哈希仅用于演示，生产环境应使用随机生成的高强度密钥，并优先以哈希形式写入配置（可通过authelia crypto hash generate pbkdf2生成）。
2. 域名一致性：Authelia 侧的redirect_uris与 Drupal 侧填写的端点地址都必须使用真实部署域名，任何一处不一致都会导致授权失败。
3. 2FA 策略：authorization_policy: 'two_factor'意味着所有通过 Drupal 登录的用户都会被强制要求双重因素认证；如需放宽可改为one_factor，但会降低整体安全水位。
4. 端点自动发现：若 Drupal 模块支持 Discovery（/.well-known/openid-configuration），优先使用自动发现代替手工填写端点，可避免版本演进带来的路径漂移问题。
5. 版本前提：本指南针对 Authelia v4.39.24 与 Drupal v10.4.0 验证，其他版本可能存在差异，请以你实际部署版本的官方文档为准。

延伸阅读

• OpenID Connect 1.0 集成介绍（端点、算法、参数全表）
• OpenID Connect 1.0 Provider 配置指南
• OpenID Connect 1.0 Clients 配置指南（全部客户端选项）
• 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