身份认证对接-OIDC-阿里云帮助中心

说明

该功能仅AI尊享版支持，版本差异请参考版本介绍。

OIDC 是什么

OIDC（OpenID Connect）是基于 OAuth 2.0 的身份认证协议，对 OAuth 2.0 未明确的部分进行了补充，二者授权流程基本一致，主要区别如下：

OIDC 授权流程中会额外返回 Id Token。
OIDC 制定了 OAuth 2.0 中未定义部分的规范，例如 scope，服务发现，用户信息字段等。

如何理解基于 OIDC 的身份认证对接

如果想要通过企业 IdP 进行身份认证最终完成邮箱登录，需要邮箱服务端与企业 IdP 服务端二者按照某种约定完成信息的传递，这个约定就是 OIDC 标准协议。

OIDC 标准协议支持多种模式，这里单指授权码模式（Authorization Code Grant）

需要邮箱服务端和企业 IdP 服务端分别实现 OIDC 标准协议，前者作为 OIDC Client，后者作为 OIDC Server。

OIDC 如何实现

OIDC 授权码模式（Authorization Code Grant）的具体实现，可以参照如下标准协议文档

另外，有关协议中定义较为宽松的部分，请严格按照本文档的说明实现（「配置步骤」-「第二步：在邮箱管理后台配置 OIDC Client」-「请在「OIDC 配置」页面，检查是否满足前提条件」）

基于 OIDC 的身份认证对接，登录流程图是怎样的

配置步骤

最终效果

配置完成后，有两种方式可通过企业 IdP 登录，二选一

方式一：访问企业的邮箱自定义登录地址，默认跳转企业 IdP 的登录页

方式二：访问企业的邮箱自定义登录地址，点击「更多登录方式」里对应 OIDC IdP 的图标

第一步：在企业 IdP 中为邮箱创建 OIDC Client

若企业是自建的 IdP，则找到企业内对应团队，为邮箱创建 OIDC Client。

若企业使用的是三方 IDaas 产品，则需要参考此 IDaas 产品的文档指引创建 OIDC Client。

关键配置如下：

授权模式（Token 接口的 grant_type）：authorization_code，refresh_token
返回类型（Authorization 接口的 response_type）：code
Token 接口身份验证方式：client_secret_post
id_token 签名算法：RS256
授权码过期时间：建议至少 600 秒
id_token 过期时间：建议 14 天（1209600 秒）
access_token 过期时间：建议 14 天（1209600 秒）
refresh_token 过期时间：：建议 28 天（2592000 秒）
（建议）scope 支持：openid、offline_access、email
（建议）claim 字段支持：email
登录回调地址：见配置页，如图

第二步：在邮箱域管理配置 OIDC Client

邮箱域管理，「企业定制」-「身份源管理」页面，点击「创建」按钮，进入「选择认证协议」页面。

点击「OIDC」身份源按钮，进入「OIDC 配置」页面。

请在「OIDC 配置」页面，检查是否满足前提条件。

条件	说明
必须满足
添加自定义登录地址	路径：「企业定制」-「界面定制」-「定制邮箱登录地址」-「添加域名」需要依赖企业的邮箱自定义登录地址，正确路由并跳转到对应企业的 OIDC IdP
完成自定义登录地址的CNAME配置	路径：「企业定制」-「界面定制」-「定制邮箱登录地址」-「CNAME设置」确保企业的邮箱自定义登录地址的正常使用
完成自定义登录地址的备案	路径：「企业定制」-「界面定制」-「定制邮箱登录地址」-「备案设置」确保企业的邮箱自定义登录地址的正常使用
建议满足
将自定义登录地址设置为默认链接	路径：「企业定制」-「界面定制」-「定制邮箱登录地址」-「设为功能邮件链接」某些场景下，需要提示员工通过企业的自定义登录地址使用邮箱
添加自定义登录地址对应的SSL证书	路径：「企业定制」-「域名管理」-「SSL证书管理」-「上传证书」使得企业自定义登录地址能够通过 HTTPS 访问，更安全
开启强制HTTPS	路径：「企业定制」-「域名管理」-「SSL证书管理」-「强制启用HTTPS」访问企业自定义登录地址默认建立 HTTPS 链接，提升安全性
全员强制开启安全密码 / 全员禁止使用第三方客户端	路径：「安全管理」-「账号安全策略」-「强制启用安全密码」/「允许使用第三方客户端」若想要开启 OIDC IdP 配置中的“仅允许通过此身份源完成登录”，则必须强制开启安全密码，才能正常使用标准协议（SMTP、IMAP、POP）强烈建议！邮箱绝大多数的账号安全问题都是源于标准协议，开启安全密码/禁用三方客户端，都能够根除邮箱安全问题，避免被盗号或产生资损注意：安全密码开启后，邮箱账密将无法通过标准协议认证，需要各个账号自己创建安全密码，并通过此密码使用标准协议。请规划好开启方案，降低影响（尤其是系统邮箱账号）

请在「OIDC 配置」页面，配置相关的字段信息。

注意：初次配置，需要验证测试，请先保持“设为默认登录方式”配置为关闭状态，以免导致员工无法正常登录邮箱

字段/功能	说明
基础配置
显示名称	这个名称会显示在用户登录界面的按钮上
应用 Logo	登录页会显示此图标，作为 OIDC 登录的入口
Client ID	企业 OIDC IdP 提供的 Client ID
Client Secret	企业 OIDC IdP 提供的 Client Secret
Issuer URL	企业 OIDC IdP 提供的 Issuer URL
回调地址	你需要将这些链接全部配置到企业 OIDC IdP 的回调地址上
登录配置
启用身份源	必须开启此开关，才能验证/使用此身份源进行登录开启后，登录页会新增依赖此身份源的 OIDC 登录按钮
设为默认登录方式	开启后，访问企业邮箱的定制登录地址，会自动跳转企业 IdP 登录页注意：请确保使用此身份源可以正常登录邮箱，验证无误后再开启！否则员工将无法登录邮箱！
仅允许通过此身份源完成登录	新企业建议开启此项开关，老企业（大量邮箱账号已使用）谨慎开启！开启后，员工仅允许通过此身份源认证，不允许通过邮箱账密等其他方式认证。例如：无法通过访问阿里企业邮箱官方地址，使用邮箱账密登录标准协议和第三方客户端（Outlook、Foxmail）无法通过邮箱账密登录，必须开启「三方客户端安全密码」，使用生成的安全密码认证注意：请确保已全员强制启用安全密码（安全管理-账号安全策略-强制启用安全密码），否则标准协议和第三方客户端（Outlook、Foxmail）将无法使用！

配置完成后，点击「保存」按钮完成创建。
若保存失败，检查 Issuer URL 是否满足条件

注意：这里建议满足的条件，是指 Issuer URL 响应可以不满足，但企业 OIDC IdP，必须实现这些能力，否则认证流程无法成功！

条件	说明
必须满足
需要提供authorization_endpoint	OIDC 的 Authorization 接口，即企业 OIDC IdP 的登录页地址
需要提供token_endpoint	OIDC 的 Token 接口，用于 code 换取 token / refresh_token 换取新的 access_token
需要提供jwks_uri	OIDC 的 Token 接口，会返回 id_token（JWT 类型），解析 JWT 的密钥，需要通过 jwks_uri 获取
建议满足注意：这里建议满足的条件，是指 Issuer URL 响应可以不满足，但企业 OIDC IdP，必须实现这些能力，否则认证流程无法成功！
需要提供introspection_endpoint	用于解析 access_token 信息，判断 access_token 是否有效，获取当前员工的 email。introspection_endpoint、userinfo_endpoint 二者实现其一即可
需要提供userinfo_endpoint	通过 access_token 换取员工信息，用于获取当前员工的 email。introspection_endpoint、userinfo_endpoint 二者实现其一即可
需要提供end_session_endpoint	用于浏览器退登，确保邮箱退登时，同时退登已登录的企业身份账号
grant_types_supported需要支持authorization_code和refresh_token	OIDC 的 Token 接口，请求参数 grant_type 的值需要支持 authorization_code、refresh_token
response_types_supported需要支持code	OIDC 的 Authorization 接口，请求参数 response_type 的值需要支持 code，即授权码模式
claims_supported需要支持email字段	OIDC 的 Token 接口，返回 id_token（JWT 类型），需要包含 email 字段
scopes_supported需要支持openid、email和offline_access	OIDC 的 Authorization 接口，请求参数 scope 的值需要支持 openid、email 和 offline_access
id_token_signing_alg_values_supported需要支持RS256	OIDC 的 Token 接口，返回 id_token（JWT 类型）签名算法需要支持 RS256
token_endpoint_auth_methods_supported需要支持client_secret_post	OIDC 的 Token 接口，验证请求方身份的 client_id、client_secret 参数，需要支持通过 post 请求传入
introspection_endpoint_auth_methods_supported需要支持client_secret_post	OIDC 的 Introspection 接口，验证请求方身份的 client_id、client_secret 参数，需要支持通过 post 请求传入
若支持PKCE，则code_challenge_methods_supported需要支持S256	如果企业 OIDC IdP 支持 PKCE，则 code_challenge 编码方法需要支持 S256

正常情况下，Issuer URL 的响应，应至少包含如下信息

{
    "authorization_endpoint": "https://mail.example.com/oidc/auth",
    "token_endpoint": "https://mail.example.com/oidc/token",
    "jwks_uri": "https://mail.example.com/oidc/.well-known/jwks.json",
    "claims_supported": [
        "email"
    ],
    "code_challenge_methods_supported": [
        "S256"
    ],
    "end_session_endpoint": "https://mail.example.com/oidc/session/end",
    "grant_types_supported": [
        "authorization_code",
        "refresh_token"
    ],
    "response_types_supported": [
        "code"
    ],
    "scopes_supported": [
        "openid",
        "offline_access",
        "email"
    ],
    "token_endpoint_auth_methods_supported": [
        "client_secret_post"
    ],
    "userinfo_endpoint": "https://mail.example.com/oidc/me",
    "introspection_endpoint": "https://mail.example.com/oidc/token/introspection",
    "introspection_endpoint_auth_methods_supported": [
        "client_secret_post"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256"
    ]
}

配置完成后，点击「保存」按钮完成创建。

第三步：验证认证对接是否成功

保存配置后，会弹出如下信息，需要验证是否都能够正确通过企业 OIDC IdP 登录邮箱

浏览器：复制地址，通过无痕模式访问。点击 OIDC 图标，跳转企业 IdP 进行登录