Authelia 集成 EspoCRM：基于 OpenID Connect 1.0 实现单点登录（SSO）完整配置指南-平芜编程栈

Authelia 集成 EspoCRM：基于 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

本指南讲解如何将 EspoCRM 配置为 Authelia OpenID Connect 1.0 Provider 的 Relying Party（依赖方），实现统一的单点登录与多因素认证（MFA）。文中提供可直接参考的 Authelia 客户端注册 YAML 配置、EspoCRM Web 管理界面的逐步操作说明，并结合仓库源码与官方文档解释每个关键参数（如access_token_signed_response_alg、token_endpoint_auth_method、require_pkce等）的底层作用，帮助读者在自建环境中完成从零到一的对接。

测试版本（Tested Versions）

本指南基于以下版本组合验证通过，若你使用的版本存在差异，部分配置细节（尤其是端点路径与认证方式）可能需要相应调整：

Authelia：v4.38.8（参考docs/content/integration/openid-connect/clients/espocrm/index.md中的版本记录）
EspoCRM：v2.0.1

从仓库源码结构看，Authelia 的 OpenID Connect 1.0 Provider 属于其核心能力之一，并已通过 OpenID 官方认证（Basic OP / Implicit OP / Hybrid OP / Form Post OP / Config OP 五个配置档），详见 OpenID Connect 1.0 集成总览。

开始之前（Before You Begin）

在正式配置前，请务必阅读以下注意事项（这部分内容来自仓库中所有 OIDC 集成指南共用的oidc-commonshortcode，属于 Authelia 官方对第三方客户端的统一建议）：

通用注意事项（Common Notes）

关于client_id：
- 每个客户端的client_id必须唯一；
- 本指南中的espocrm仅用于可读性与演示，生产环境不应使用，建议参考如何生成客户端标识符或客户端密钥？（官方推荐 64 个随机字符，也可使用满足其他条件的任意值）；
- 只能包含 RFC3986 Unreserved Characters（即A-Z、a-z、0-9、-、.、_、~）；
- 长度不得超过 100 个字符。
关于client_secret：
- 本指南中的insecure_secret仅用于演示，生产环境绝对不要使用；
- 该字符串可以明文形式存储在 Authelia 配置中，但此行为已弃用，不保证未来版本继续支持；
- 强烈推荐以 PBKDF2 哈希形式存储密钥（本指南示例中的$pbkdf2-sha512$...即insecure_secret的哈希摘要）。需要注意的是，哈希成本（work factor）过高可能导致客户端请求超时，可参考调整工作因子一节。
关于配置示例：
- 本指南给出的 Authelia YAML 仅包含客户端注册部分的示例配置，你还必须同时配置 OpenID Connect 1.0 Provider 配置中要求的必选元素（如 issuer、密钥等）；
- 该示例只展示了已注册客户端全部可用选项中的一小部分，建议通读 OpenID Connect 1.0 客户端配置文档，熟悉其他选项及其影响。

前提假设（Assumptions）

本示例基于以下假设，配置前请替换为你的实际域名：

项目	值
应用根 URL	`https://espocrm.example.com/`（决定了 redirect URI 的形态）
Authelia 根 URL	`https://auth.example.com/`
Client ID	`espocrm`
Client Secret	`insecure_secret`

其中，Application Root URL直接决定回调地址（redirect URI）的格式：https://espocrm.example.com/login。这意味着一旦你修改了应用根 URL，就必须同步更新 Authelia 客户端配置中的redirect_uris。

配置 Authelia

在 Authelia 的configuration.yml中，为 EspoCRM 注册一个 OIDC 客户端。完整的客户端注册片段如下：

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: 'espocrm' client_name: 'EspoCRM' client_secret: '$pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng' # The digest of 'insecure_secret'. public: false authorization_policy: 'two_factor' require_pkce: false pkce_challenge_method: '' redirect_uris: - 'https://espocrm.example.com/oauth-callback.php' scopes: - 'openid' - 'email' - 'profile' response_types: - 'code' grant_types: - 'authorization_code' access_token_signed_response_alg: 'none' userinfo_signed_response_alg: 'none' token_endpoint_auth_method: 'client_secret_basic'

关键参数逐项解析

结合客户端配置文档与 Provider 配置文档，各参数含义如下：

client_id/client_name：客户端唯一标识与界面显示名称。client_name默认与 ID 相同，此处显式设为EspoCRM便于在 Authelia 的授权确认界面中识别。
client_secret：Authelia 与 EspoCRM 共享的密钥，必须与应用侧配置的密钥一致。此处使用 PBKDF2 哈希形式（$pbkdf2-sha512$...），即明文insecure_secret的摘要，符合官方对生产环境的强烈建议。
public: false：将客户端声明为机密类型（confidential client）。机密客户端可以在 Token 端点使用密钥进行认证，这也是token_endpoint_auth_method得以生效的前提；若为true（公开客户端），client_secret必须留空。
authorization_policy: 'two_factor'：定义该客户端的授权策略，本例要求用户在登录时必须通过双因素认证（2FA）。可替换为one_factor以仅要求单因素。
require_pkce: false：不强制要求 PKCE（Proof Key for Code Exchange）。EspoCRM 采用client_secret_basic的机密客户端认证方式，本身已具备前端通道之外的客户端凭证保护，因此本指南未开启 PKCE 强制。若需要为单个客户端强制 PKCE，可将其设为true；全局强制则使用 Provider 配置中的enforce_pkce选项。
pkce_challenge_method: ''：配合require_pkce使用的挑战方法，合法值为空字符串、plain或S256。设置非空值会同时隐式启用require_pkce；官方强烈推荐支持方使用S256。
redirect_uris：EspoCRM 的回调地址。必须与 EspoCRM 侧填写的 "Authorization Redirect URI" 完全一致（即https://espocrm.example.com/oauth-callback.php），否则授权码无法正确回传。
scopes：请求的权限范围，本例请求openid、email、profile三个 scope，对应 ID Token 与 UserInfo 端点中返回的身份与资料信息。
response_types: ['code']：仅允许授权码流程（Authorization Code Flow），这是最常用也最安全的 Web 应用流程（详见集成总览中的 Response Types 表格）。
grant_types: ['authorization_code']：仅允许授权码授予类型。若未来需要刷新令牌（Refresh Token），需追加refresh_token（并配合offline_accessscope）。
access_token_signed_response_alg: 'none'：Access Token 不进行 JWT 签名。这通常意味着 Access Token 以不透明（opaque）形式签发，EspoCRM 只需将其作为 Bearer Token 使用；这也是多数第三方应用的默认兼容做法。若需要 JWT 格式的 Access Token，可改为RS256等签名算法。
userinfo_signed_response_alg: 'none'：UserInfo 端点返回普通 JSON（application/json）而非签名 JWT，是兼容性最好的默认选择。若设为签名算法，响应将变为application/jwt格式。
token_endpoint_auth_method: 'client_secret_basic'：客户端在 Token 端点使用HTTP Basic Auth携带 Client ID 与 Client Secret 进行认证（对应 OAuth 2.0 的client_secret_basic方法）。其他可选值包括client_secret_post（POST 表单体携带）、client_secret_jwt、private_key_jwt等，具体见集成总览的 Client Authentication Method 表格。

配置 EspoCRM

EspoCRM 侧只有一种配置方式：通过Web 管理界面（Web GUI）完成。

通过 Web 界面配置

按照以下步骤将 EspoCRM 接入 Authelia：

访问你的 EspoCRM 实例；
使用**管理员（Administration）**账号登录；
进入Authentication（认证）设置页面；
将认证方式（method）选择为OIDC；
依次填写以下选项：

EspoCRM 配置项	值
Client ID	`espocrm`
Client Secret	`insecure_secret`
Authorization Redirect URI	`https://espocrm.example.com/oauth-callback.php`
Fallback Login	推荐开启（允许使用内部用户登录，作为 OIDC 不可用时的兜底）
Allow OIDC Login for admin users	推荐开启（允许管理员通过 OIDC 登录）
Authorization Endpoint	`https://auth.example.com/api/oidc/authorization`
Token Endpoint	`https://auth.example.com/api/oidc/token`
JSON Web Key Set Endpoint	`https://auth.example.com/jwks.json`

关于端点的说明

上表中的三个端点路径来自 Authelia 的 OpenID Connect 1.0 端点实现（详见集成总览的 Endpoint Implementations 一节）：

Authorization Endpointhttps://auth.example.com/api/oidc/authorization：负责用户认证与授权，是 OIDC 流程的入口；
Token Endpointhttps://auth.example.com/api/oidc/token：用于用授权码换取 Access Token / ID Token；
JSON Web Key Set Endpointhttps://auth.example.com/jwks.json：向依赖方提供 Authelia 的公开签名密钥，用于校验 JWT 签名。

此外，Authelia 还实现了.well-known/openid-configuration与.well-known/oauth-authorization-server两个标准发现端点。支持 OIDC Discovery 的客户端可以直接从这两个端点自动获取全部端点地址；若 EspoCRM 支持发现机制，优先使用发现端点可避免手工配置端点时出错。

安全与兼容性提示

由于 EspoCRM 属于第三方应用，Authelia 官方在oidc-common提示中强调：对于不支持规范行为的客户端，本指南仅提供尽力而为的适配。请始终优先参考 EspoCRM 官方文档确认其 OIDC 实现细节，并关注其安全公告。
生产环境中务必使用强随机密钥（推荐 64 字符以上），并以哈希形式存储在 Authelia 配置中，切勿沿用insecure_secret。
若你的 EspoCRM 实例与 Authelia 处于不同域名，请确认 Authelia 的 CORS 配置允许跨域请求，避免 Token 端点请求被浏览器拦截。
若启用Fallback Login，请确保 EspoCRM 内部用户与 Authelia 用户体系之间的权限隔离符合你的安全预期。