> ## Documentation Index > Fetch the complete documentation index at: https://doc.lwops.cn/llms.txt > Use this file to discover all available pages before exploring further. # 用户登录认证 ## 开放能力-用户登录认证 ## 操作手册 用户登录认证 ## 概述 提供用户认证配置功能，支持 LDAP 认证、CAS 客户端、CAS 服务端和 OAuth2 客户端等方式，实现用户统一身份认证与单点登录，降低登录复杂度。 ## 操作步骤 ### LDAP 认证 LDAP 用于对接 AD 或 OpenLDAP 目录。要求平台版本为 7.0 及以上，证书配置和高级过滤功能需核对实际版本。 #### 开启 LDAP 并配置目录连接 首先进入【用户管理】页面，再点击管理下的【认证配置】，进入用户认证配置页面 用户登录认证 原文图片 2 切换至【LDAP认证】，开启【开启LDAP】，并填写主机与端口等信息 * 主机：目标服务器地址 * 端口：普通 ldap\:// 用 389；加密 ldaps\:// 用 636。填完整 URI 时，按页面要求确认端口。 用户登录认证 原文图片 3 #### 配置 AD 用户搜索 填写【Base DN】，控制搜索范围，覆盖允许登录的用户： * AD 的【搜索属性】通常为 sAMAccountName； * 配置【绑定 DN】、【绑定密码】，用于连接目录查询用户 * 用户过滤器按实际登录范围配置。 用户登录认证 原文图片 4 #### 配置 OpenLDAP 用户搜索 * 对接 OpenLDAP，根据实际目录填写 Base DN，示例：dc=example,dc=org * 搜索属性一般填 uid * 绑定 DN 填写目录完整账号标识，示例：cn=reader,dc=example,dc=org * 基础用户过滤器按需填写 用户登录认证 原文图片 5 #### 按需配置证书 使用证书连接时，需要： * 填写 CA 根证书路径 * 若对端需客户端证书认证，额外填写客户端证书、客户端密钥路径 * 证书文件部署至乐维运行环境可读目录 * 主机地址、协议、端口需与证书信息匹配 用户登录认证 原文图片 6 #### 保存并验证登录 核对配置后点击【确定】保存。使用目录中的测试账号重新登录，检查能否完成认证，并核对登录用户、角色和部门。对于不在过滤范围内的用户，确认不能按该认证配置完成登录。 用户登录认证 原文图片 7 #### 登录异常时核对绑定与查询 先确认绑定账号可用，再按相同 Base DN 和过滤条件查询测试用户。以下命令在可访问目录的测试环境中执行；-W 表示交互输入密码。AD 查询时将 uid 条件替换为 sAMAccountName。 ```text theme={null} 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 地址；仅在对端要求客户端证书时设置相应证书变量。 ```text theme={null} 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 协议版本 * 用户名属性：需与对端实际返回的用户标识保持一致 用户登录认证 原文图片 8 点击【确定】保存，从单点登录入口发起登录。完成外部 CAS 认证后，确认浏览器返回乐维，且登录用户与对端身份一致。 ### CAS 服务端 需要让第三方应用使用乐维完成身份认证时，开启乐维的 CAS 服务端，由第三方应用接收并验证票据。 #### 开启乐维 CAS 服务端 切换至【Cas服务端】，开启【开启Cas服务端】，点击【确定】保存。 用户登录认证 原文图片 9 第三方准备登录回调 service 地址，引导浏览器访问乐维 CAS 登录入口。\{SERVER}为乐维访问基地址，service 参数的第三方地址需 URL 编码 ```text theme={null} GET {SERVER}/backend_api/auth/cas/login?service={URL_ENCODED_SERVICE_URL} ``` #### 接收并校验登录票据 用户登录成功后，第三方从跳转参数获取 ticket，由后端调用乐维票据校验接口，不可仅依靠浏览器带回的 ticket 判定登录成功。CAS 校验需匹配签发票据时的 service，部署时按接口核对参数兼容性： ```text theme={null} GET {SERVER}/backend_api/auth/cas/p3/serviceValidate?ticket={SERVICE_TICKET}&service={URL_ENCODED_SERVICE_URL}。 ``` #### 读取用户并验证对接 校验通过后，从authenticationSuccess节点读取 user，第三方创建本地会话，核对返回用户名与测试账号；错误/失效时禁止创建登录会话。响应示例： ```text theme={null} test_user ``` ### OAuth2 客户端 乐维作为客户端接入外部 OAuth2 服务时，使用【Oauth2客户端】配置。先确认对端授权服务，再配置乐维回调与用户映射。 #### 获取客户端信息并登记回调 在对端登记乐维客户端，获取客户端 ID、客户端密钥、授权类型，以及授权、令牌和用户信息接口。将乐维页面提示的重定向地址登记到对端，协议、域名、端口和路径应保持一致。 #### 填写认证接口 切换至【Oauth2客户端】，填写【客户端ID】、【客户端密钥】、【授权类型】和【重定向地址】。随后填写对端的【授权地址】、【Token地址】和【用户信息地址】，并选择对端要求的【用户信息方法】。 * 用户信息映射：依据对端返回数据配置用户标识、登录名、姓名字段，先获取测试用户真实响应结构再确认映射关系，请勿直接复制其他系统字段名。 * 重定向地址：用于接收授权结果 * 授权地址：用于发起对端授权，两者不能互换。 * 乐维回调地址示例如下，实际以当前页面提示和部署路由为准。 ```text theme={null} https://ops.example.org/backend_api/auth/sign/auth?authclient=Oauth2Client ``` 用户登录认证 原文图片 10 #### 配置用户创建与同步 保留【启用 State 验证】；按账号管理需求设置【是否创建用户】。开启自动创建用户时，配置【默认用户权限】与【默认用户部门】；如需登录时更新用户属性，按需开启【自动同步用户信息】。 用户登录认证 原文图片 11 #### 保存并验证单点登录 核对各项配置后开启状态，点击【确定】保存。使用测试账号发起登录，确认授权后返回乐维，登录名与对端一致，并检查默认角色、部门和同步后的属性。错误 state、无效密钥或不匹配回调地址不应建立有效登录会话。 ### OAuth2 服务端对接 乐维作为 OAuth2 服务端向业务系统提供认证，第三方业务系统作为客户端，采用授权码流程对接。 #### 创建第三方客户端 平台需升级至 7.0.2 及以上版本 在乐维 Web 目录执行以下命令，按提示录入第三方回调地址redirect\_uri；若存在客户端管理页面，也可在页面登记客户端。 ```text theme={null} php yii oauth/create ``` 将生成的客户端 ID、客户端密钥交付对接方，两端配置保持一致。redirect\_uri为第三方接收授权结果地址，并非乐维/fe-auth授权入口。 #### 配置第三方客户端的访问地址 统一浏览器授权地址和后端 API 地址，避免混用不同服务器或将 backend\_api 重复拼接。以下为对外代理地址的配置示例；部署路径 / 端口不同时按需替换。 ```text theme={null} [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。 ```text theme={null} 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 与授权请求保持一致。请求包含以下字段，密钥和授权码使用本次对接的实际值。 ```text theme={null} 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 以及所需用户属性，映射到第三方系统用户，再建立对应登录会话。 ```text theme={null} POST {API_BASE}/oauth/auth/account Authorization: Bearer {ACCESS_TOKEN} ``` #### 刷新访问令牌 需要刷新时，向刷新接口提交 access\_token 与 refresh\_token，根据响应更新访问令牌和有效期，并验证新令牌可正常调用用户信息接口。 ```text theme={null} POST {API_BASE}/oauth/auth/refresh access_token={ACCESS_TOKEN} refresh_token={REFRESH_TOKEN} ``` #### 销毁令牌并完成验证 调用销毁接口时在请求头中携带访问令牌。销毁后确认该令牌不能继续访问受保护接口。此步骤验证令牌退出，不代表所有系统的会话都会同时退出；全局退出范围按实际对接方案确认。 ```text theme={null} POST {API_BASE}/oauth/auth/logout Authorization: Bearer {ACCESS_TOKEN} ``` 最终使用测试账号串联验证“授权跳转—授权码—令牌—用户信息—登录会话”，再验证刷新和销毁行为。记录实际测试时间、版本和结果；本操作文档中的命令与响应均为说明示例。