用户登录认证 - 乐维文档

开放能力-用户登录认证

操作手册

用户登录认证

概述

提供用户认证配置功能，支持 LDAP 认证、CAS 客户端、CAS 服务端和 OAuth2 客户端等方式，实现用户统一身份认证与单点登录，降低登录复杂度。

操作步骤

LDAP 认证

LDAP 用于对接 AD 或 OpenLDAP 目录。要求平台版本为 7.0 及以上，证书配置和高级过滤功能需核对实际版本。

开启 LDAP 并配置目录连接

首先进入【用户管理】页面，再点击管理下的【认证配置】，进入用户认证配置页面

切换至【LDAP认证】，开启【开启LDAP】，并填写主机与端口等信息

主机：目标服务器地址
端口：普通 ldap:// 用 389；加密 ldaps:// 用 636。填完整 URI 时，按页面要求确认端口。

配置 AD 用户搜索

填写【Base DN】，控制搜索范围，覆盖允许登录的用户：

AD 的【搜索属性】通常为 sAMAccountName；
配置【绑定 DN】、【绑定密码】，用于连接目录查询用户
用户过滤器按实际登录范围配置。

配置 OpenLDAP 用户搜索

对接 OpenLDAP，根据实际目录填写 Base DN，示例：dc=example,dc=org
搜索属性一般填 uid
绑定 DN 填写目录完整账号标识，示例：cn=reader,dc=example,dc=org
基础用户过滤器按需填写

按需配置证书

使用证书连接时，需要：

填写 CA 根证书路径
若对端需客户端证书认证，额外填写客户端证书、客户端密钥路径
证书文件部署至乐维运行环境可读目录
主机地址、协议、端口需与证书信息匹配

保存并验证登录

核对配置后点击【确定】保存。使用目录中的测试账号重新登录，检查能否完成认证，并核对登录用户、角色和部门。对于不在过滤范围内的用户，确认不能按该认证配置完成登录。

登录异常时核对绑定与查询

先确认绑定账号可用，再按相同 Base DN 和过滤条件查询测试用户。以下命令在可访问目录的测试环境中执行；-W 表示交互输入密码。AD 查询时将 uid 条件替换为 sAMAccountName。

ldapwhoami -x -H "ldap://ldap.example.org:389" \
-D "cn=reader,dc=example,dc=org" -W
ldapsearch -x -H "ldap://ldap.example.org:389" \
-D "cn=reader,dc=example,dc=org" -W \
-b "dc=example,dc=org" "(uid=test_user)"

证书模式可在同一查询命令中指定 CA、客户端证书和密钥，并改用 LDAPS 地址；仅在对端要求客户端证书时设置相应证书变量。

LDAPTLS_CACERT=/path/ca.crt \
LDAPTLS_CERT=/path/client.crt \
LDAPTLS_KEY=/path/client.key \
ldapsearch -x -H "ldaps://ldap.example.org:636" \
-D "cn=reader,dc=example,dc=org" -W \
-b "dc=example,dc=org" "(uid=test_user)"

CAS 客户端

乐维作为客户端接入外部 CAS 统一认证系统时，使用【Cas客户端】配置。

准备外部 CAS 参数

向对端确认 CAS 服务地址、支持的协议版本和用于标识用户的返回属性，同时确认乐维回调服务地址在对端的登记要求。

填写客户端认证配置

切换至【Cas客户端】，开启【开启Cas认证】。

【服务端地址】：包含对端要求的路径前缀
版本：CAS 协议版本
用户名属性：需与对端实际返回的用户标识保持一致

点击【确定】保存，从单点登录入口发起登录。完成外部 CAS 认证后，确认浏览器返回乐维，且登录用户与对端身份一致。

CAS 服务端

需要让第三方应用使用乐维完成身份认证时，开启乐维的 CAS 服务端，由第三方应用接收并验证票据。

开启乐维 CAS 服务端

切换至【Cas服务端】，开启【开启Cas服务端】，点击【确定】保存。

第三方准备登录回调 service 地址，引导浏览器访问乐维 CAS 登录入口。{SERVER}为乐维访问基地址，service 参数的第三方地址需 URL 编码

GET {SERVER}/backend_api/auth/cas/login?service={URL_ENCODED_SERVICE_URL}

接收并校验登录票据

用户登录成功后，第三方从跳转参数获取 ticket，由后端调用乐维票据校验接口，不可仅依靠浏览器带回的 ticket 判定登录成功。CAS 校验需匹配签发票据时的 service，部署时按接口核对参数兼容性：

GET {SERVER}/backend_api/auth/cas/p3/serviceValidate?ticket={SERVICE_TICKET}&service={URL_ENCODED_SERVICE_URL}。

读取用户并验证对接

校验通过后，从authenticationSuccess节点读取 user，第三方创建本地会话，核对返回用户名与测试账号；错误/失效时禁止创建登录会话。响应示例：

<cas:authenticationSuccess>
<cas:user>test_user</cas:user>
</cas:authenticationSuccess>

OAuth2 客户端

乐维作为客户端接入外部 OAuth2 服务时，使用【Oauth2客户端】配置。先确认对端授权服务，再配置乐维回调与用户映射。

获取客户端信息并登记回调

在对端登记乐维客户端，获取客户端 ID、客户端密钥、授权类型，以及授权、令牌和用户信息接口。将乐维页面提示的重定向地址登记到对端，协议、域名、端口和路径应保持一致。

填写认证接口

切换至【Oauth2客户端】，填写【客户端ID】、【客户端密钥】、【授权类型】和【重定向地址】。随后填写对端的【授权地址】、【Token地址】和【用户信息地址】，并选择对端要求的【用户信息方法】。

用户信息映射：依据对端返回数据配置用户标识、登录名、姓名字段，先获取测试用户真实响应结构再确认映射关系，请勿直接复制其他系统字段名。
重定向地址：用于接收授权结果
授权地址：用于发起对端授权，两者不能互换。
乐维回调地址示例如下，实际以当前页面提示和部署路由为准。

https://ops.example.org/backend_api/auth/sign/auth?authclient=Oauth2Client

配置用户创建与同步

保留【启用 State 验证】；按账号管理需求设置【是否创建用户】。开启自动创建用户时，配置【默认用户权限】与【默认用户部门】；如需登录时更新用户属性，按需开启【自动同步用户信息】。

保存并验证单点登录

核对各项配置后开启状态，点击【确定】保存。使用测试账号发起登录，确认授权后返回乐维，登录名与对端一致，并检查默认角色、部门和同步后的属性。错误 state、无效密钥或不匹配回调地址不应建立有效登录会话。

OAuth2 服务端对接

乐维作为 OAuth2 服务端向业务系统提供认证，第三方业务系统作为客户端，采用授权码流程对接。

创建第三方客户端

平台需升级至 7.0.2 及以上版本在乐维 Web 目录执行以下命令，按提示录入第三方回调地址redirect_uri；若存在客户端管理页面，也可在页面登记客户端。

php yii oauth/create

将生成的客户端 ID、客户端密钥交付对接方，两端配置保持一致。redirect_uri为第三方接收授权结果地址，并非乐维/fe-auth授权入口。

配置第三方客户端的访问地址

统一浏览器授权地址和后端 API 地址，避免混用不同服务器或将 backend_api 重复拼接。以下为对外代理地址的配置示例；部署路径 / 端口不同时按需替换。

[oauth]
client_id={CLIENT_ID}
client_secret={CLIENT_SECRET}
base_url=https://ops.example.org/backend_api

auth_url=https://ops.example.org/fe-auth

token_url=/oauth/auth/token
refresh_url=/oauth/auth/refresh
account_url=/oauth/auth/account
logout_url=/oauth/auth/logout

发起授权并接收授权码

第三方引导浏览器访问乐维授权地址。response_type 使用 code，redirect_uri 使用已登记并经过 URL 编码的回调地址，同时携带本次请求的 state。接收回调后先核对 state，再读取 code。

GET https://ops.example.org/fe-auth?response_type=code&client_id={CLIENT_ID}&redirect_uri={ENCODED_CALLBACK_URL}&state={STATE}

使用授权码换取令牌

由第三方后端向令牌接口发起 POST 请求。{API_BASE} 表示上一步配置的 base_url；redirect_uri 与授权请求保持一致。请求包含以下字段，密钥和授权码使用本次对接的实际值。

POST {API_BASE}/oauth/auth/token
Content-Type: application/json

{
"client_id": "{CLIENT_ID}",
"client_secret": "{CLIENT_SECRET}",
"grant_type": "authorization_code",
"code": "{AUTHORIZATION_CODE}",
"redirect_uri": "{CALLBACK_URL}"
}

确认响应中包含 access_token、expires_in 和 token_type；存在 refresh_token 时一并按对接要求保存。以实际响应有效期为准，不直接复制示例令牌。

获取用户信息并建立会话

携带访问令牌请求用户信息接口，读取返回的 username、nickname 以及所需用户属性，映射到第三方系统用户，再建立对应登录会话。

POST {API_BASE}/oauth/auth/account
Authorization: Bearer {ACCESS_TOKEN}

刷新访问令牌

需要刷新时，向刷新接口提交 access_token 与 refresh_token，根据响应更新访问令牌和有效期，并验证新令牌可正常调用用户信息接口。

POST {API_BASE}/oauth/auth/refresh

access_token={ACCESS_TOKEN}
refresh_token={REFRESH_TOKEN}

销毁令牌并完成验证

调用销毁接口时在请求头中携带访问令牌。销毁后确认该令牌不能继续访问受保护接口。此步骤验证令牌退出，不代表所有系统的会话都会同时退出；全局退出范围按实际对接方案确认。

POST {API_BASE}/oauth/auth/logout
Authorization: Bearer {ACCESS_TOKEN}

最终使用测试账号串联验证“授权跳转—授权码—令牌—用户信息—登录会话”，再验证刷新和销毁行为。记录实际测试时间、版本和结果；本操作文档中的命令与响应均为说明示例。

​开放能力-用户登录认证

​操作手册

​概述

​操作步骤

​LDAP 认证

​开启 LDAP 并配置目录连接

​配置 AD 用户搜索

​配置 OpenLDAP 用户搜索

​按需配置证书

​保存并验证登录

​登录异常时核对绑定与查询

​CAS 客户端

​准备外部 CAS 参数

​填写客户端认证配置

​CAS 服务端

​开启乐维 CAS 服务端

​接收并校验登录票据

​读取用户并验证对接

​OAuth2 客户端

​获取客户端信息并登记回调

​填写认证接口

​配置用户创建与同步

​保存并验证单点登录

​OAuth2 服务端对接

​创建第三方客户端

​配置第三方客户端的访问地址

​发起授权并接收授权码

​使用授权码换取令牌

​获取用户信息并建立会话

​刷新访问令牌

​销毁令牌并完成验证