术语介绍与常见对接问题

基本术语表

术语	说明
认证	用户或机器通过账号密码等，中望账号系统生成能够代表其身份的凭证（如token）
授权	服务通过账号系统颁发的凭证，授予相关的访问或操作权限
资源	需要授权才能访问的服务，例如提供API接口的服务等
受信客户端	“受信”是对于其需要访问的资源而言，此客户端代表的是机器或服务，而不是特定的用户。受信客户端可以请求资源的高权限接口，如批量访问\操作等
用户客户端	面向用户的服务，如网站前端、产品终端等。此客户端代表用户向账号系统请求认证，并使用获取的用户凭证代表该用户请求资源。
作用域	资源对外提供的权限，注册客户端时必须申请其需要的作用域，仅拥有作用域的客户端可以请求相应的凭证，若客户端请求了未授予的作用域，将无法通过账号系统的认证获取凭证

常见对接问题

有需要保护的资源，如API服务
请按API资源保护注册资源，并在资源上使用JWT保护

有服务在不需要用户登录的情况下，访问\操作资源，例如服务A需要同步服务B的数据
请为服务A注册受信客户端，为服务B注册资源

有用户登录的场景
请注册用户客户端

需要批量查询中望账号系统用户信息
请在受信客户端中申请作用域：ZMS.Users.Read

有邀请用户或后台创建用户的场景
请在受信客户端中申请作用域：ZMS.Users.Create

中望内部服务在开发过程中需要在内网有账号认证和授权
请联系负责人获取账号系统内网版本

如何修改\删除资源、添加\修改\删除作用域
请联系负责人进行修改和删除，注意删除资源将同时删除资源的所有作用域，作用域删除或修改后，所有使用该作用域的客户端在请求认证时必须移除原作用域

用户如何修改个人信息
有两种方式：
(1) 引导用户至中望用户中心(https://me.zwsoft.cn)
(2) 客户端申请ZMS.UserBasic.Write或ZMS.UserDetails.Write，自行实现页面，通过账号系统API接口进行修改

用户如何修改安全信息，如手机、邮箱、关闭账户等
有两种方式：
(1) 引导用户至中望用户中心(https://me.zwsoft.cn)
(2) 在客户端使用网页组件直接访问安全设置页面

概述与规范

中望统一账号概述

中望统一账号使用IdentityServer4（IDS4）作为用户身份认证与授权的主要技术，因此支持OAuth2和OIDC协议，提供了默认的接口端点，同时基于中望用户系统需求文档为各服务提供用户业务相关的功能。对于中望统一账号来说，接入的服务有两种情形：

作为资源，希望对该资源进行保护，只有通过认证的客户端或用户才能访问该资源。例如网站的后端服务、API服务等。

作为客户端，希望对用户进行登录认证，以获取用户信息、资源访问权限等。如网站的前端、需要访问其它受保护资源的服务等。

如需了解更加全面的认证与授权信息（如相关术语、概念、接口端点等），请参考IdentityServer4官方文档。

开发规范

接入中望统一账号后，可获得调用相关接口的权限，请遵守相关接口的使用规范。

当涉及到用户数据时：

确保仅将用户数据用于自身服务，且用户知悉数据的用途。

采取必要的措施保证用户数据安全，防止用户数据泄露或被盗。

中望开放平台有权要求各接入的服务删除用户的敏感数据，例如当用户注销其中望账号时。

若您的服务有用户的权益，为保证用户删除账号后不会产生权益纠纷，请自行缓存用户权益信息及关联信息，用户删除中望账号后将无法通过中望账号索引用户。

若需要限制用户删除账号，请提供查询接口，当不满足删除账号条件时，将引导用户到您提供的网址。

查询接口规范：

方法: GET
权限：无（可通过IP进行限制）
参数：guid（QUERY参数，中望用户GUID）, language(可选QUERY参数，用户语言代号，如：zh-CN)
返回示例：
{
    "deletable": false,
    "details": [
        {
            "message":"将显示在用户界面；请根据language返回相应语言的信息",
            "url":"页面链接，可以是处理权益的页面，也可以是相应的帮助文档；统一账号将引导用户前往此链接",
            "icon":"页面链接图标，可为null，但不能为空字符串"
        }
    ]
}

deletable为true时，details请返回空数组
details中的url需要支持QUERY参数（redirectUrl），页面需要提供按钮引导用户返回redirectUrl
icon大小至少为26X34，显示的背景色为#f7f7f7
message中可使用一个<br/>标签分隔字符串，此标签前的字符串将黑色加粗显示，此标签后的字符串将换行灰显

权限说明

作用域(Scope)是中望统一账号为客户端提供的在访问资源时的授权作用范围，只有拥有相关作用域权限的客户端才能申请对应资源的token。

中望账号作用域列表

作用域	说明	备注
openid	获取用户全局唯一ID	默认授予的作用域，不需要申请，仅限用户客户端
email	获取用户邮箱地址	对于非中望内部服务，手机号和邮箱信息需要用户在登录时确认同意
phone	获取用户手机号码	对于非中望内部服务，手机号和邮箱信息需要用户在登录时确认同意
offline_access	获取刷新token	默认授予的作用域，不需要申请
ZMS.Basic	获取用户基本信息，包括用户GUID、姓氏、名字、显示名称、头像链接、偏好语言。	默认授予的作用域，不需要申请
ZMS.UserDetails.Read	获取用户详细信息，包括用户GUID、姓氏、名字、显示名称、头像链接、偏好语言、资讯接收设置、出生日期、联系地址、工作信息、账号状态、用户名、第三方绑定信息	需要申请
ZMS.UserBasic.Write	修改用户基本信息，包括用户头像、姓氏、名字、显示名称、偏好语言	需要申请
ZMS.UserDetails.Write	修改用户详细信息，包括用户头像、姓氏、名字、显示名称、偏好语言、出生日期、联系地址、工作信息、资讯接收设置	需要申请
ZMS.Users.Read	在不需要用户登录的情况下，批量查询用户信息	需要申请，仅限受信客户端
ZMS.Users.Create	批量创建用户	需要申请，仅限受信客户端

可提供服务的中望业务权限

当其它资源使用中望统一账号进行资源保护时，第三方若取得该资源负责人的同意，中望统一账号可为其添加资源访问权限。

业务模块	说明	资源部门
产品服务	获取\查询产品信息	研发中台
订单服务	创建\查询订单，发起支付，发票\证书查看下载	研发中台
订阅授权服务	获取用户订阅产品信息、激活\查询产品授权	研发中台
统一云盘	获取空间信息、文件夹\文件操作	研发中台
云CAD	Web端图纸查看\协作	云CAD事业部
云3D	Web端3D建模仿真协作	云3D事业部

API资源保护

资源注册

通过在中望开放平台注册资源，可以使经过中望开放平台认证和授权的客户端获得资源的访问权限。

请准备以下材料并与研发中台联系：

材料	是否必须	说明	示例
英文资源名称	必须		ProductManageService
中文资源名称	可选		产品管理服务
资源说明	必须	简要说明资源的作用	用于中望内部的产品管理后台，提供产品定义、价格策略、产品上下架等功能，为其它服务提供产品信息
作用域英文名称及其说明	必须	作用域即资源的权限划分，作用域名称全局唯一，请在名称中添加区别性的标识，以避免与其它作用域重复。建议使用三段式命名：资源缩写.模块(或操作内容).权限	PMS.Product.Read：获取产品信息 PMS.Product.Write：修改产品基本信息
测试服\正式服	必须	当前申请接入的环境	正式服
资源负责人	必须		张三(zhangsan@zwcad.com)
角色控制	可选	定义角色类型时，其名称全局唯一，请在名称中添加区别性的标识，以避免与其它服务的角色重复。建议使用二段式命名：资源缩写.角色名称	PMS.RoleManager：产品服务角色管理员，可以指定用户角色 PMS.ProductManager：产品管理员，可以创建\更新产品

资源保护

在资源服务上，通过添加授权校验组件可对资源进行保护，不同的开发框架有不同的组件可选择使用，请根据资源服务的开发框架自行选择合适的组件（可搜索关键词：使用JWT保护API）。

例如 .NET CORE环境下可选择依赖包 Microsoft.AspNetCore.Authentication.JwtBearer。

角色控制

资源可以通过定义角色进行权限控制，当用户属于某种角色的成员时，其token中将包含”role“字段（字符串或字符串列表），资源可以根据该信息判断用户角色。

开放平台提供用户角色管理的相关API，详情请查看API接口角色分组

获取认证与授权

受信客户端

受信客户端是指受中望开放平台和所申请的资源服务信任的客户端，可以通过中望开放平台接口获取access_token，并调用某些较高权限的接口，如无需用户登录即可获取用户信息、批量获取用户信息等，一般适用于网站后端服务。当前受信客户端仅限中望内部服务申请。

客户端注册

通过在中望开放平台注册资源，可以使经过中望开放平台认证和授权的客户端获得资源的访问权限，请准备以下材料并填写接入表：客户端接入申请

材料	是否必须	说明	示例
英文名称	必须		SamCoreService
中文名称	可选		订阅核心服务
客户端说明	必须	简要说明客户端用途，申请受信的原因	中望订阅后端服务，需后端调用产品、订单、授权等子服务
申请的作用域	必须	如申请特殊作用域，需说明原因	（此示例仅用作举例，实际可申请的作用域请联系各服务负责人） ZMS.Users.Read：批量读取用户信息 ZMS.User.Create：创建用户（订阅需提供邀请用户的功能）
测试服\正式服	必须	当前申请接入的环境	正式服
客户端负责人	必须		张三(zhangsan@zwcad.com)

注意：在客户端通过审核并注册完成后，将发送客户端ID和密钥给客户端负责人，研发中台不保存该密钥信息，请妥善保存。如果密钥遗失或泄露，请及时联系研发中台生成新密钥。

获取令牌

受信客户端获取token时使用密码模式，且其过程不需要用户参与。
详情请查看API接口文档：受信客户端获取令牌

用户客户端

用户客户端通常用于需要用户登录认证的服务，如网站前端、桌面端产品、移动端产品等等。

客户端注册

请准备以下材料并填写接入表：客户端接入申请

材料	是否必须	说明	示例
英文名称	必须		ZWsoftWebCadClient
中文名称	可选		中望WebCAD前端
客户端说明	必须	简要说明客户端用途	中望WebCAD前端
申请的作用域	必须	如申请特殊作用域，需说明原因	（此示例仅用作举例，实际可申请的作用域请联系各服务负责人） email、phone：为用户发送WebCAD相关业务通知 Files.ReadWrite.All：读写用户网盘文件
允许的跨域地址	必须	此客户端访问请求资源时所使用的域名，服务将拒绝不在允许列表的域名发送的请求	https://web.zwcad.com
允许的回调地址	必须	客户端请求成功后，将重定向至指定的回调地址。当请求中指定的回调地址不在允许的列表时，服务将拒绝该请求	https://web.zwcad.com/ https://web.zwcad.com/callback
允许的退出回调地址	必须	客户端请求登出用户后，将重定向至指定的回调地址。	https://web.zwcad.com/
测试服\正式服	必须	当前申请接入的环境	正式服
客户端负责人	必须		张三(zhangsan@zwcad.com)

注意：在客户端通过审核并注册完成后，研发中台将通知客户端负责人。

获取\刷新令牌

本节介绍通过OAUTH2.0接口方式获取token，出于安全考虑，中望开放平台仅提供通过code模式请求token，主要步骤包括获取code，使用code兑换令牌，刷新token等。

获取服务配置

发现端点内提供了标准的信息，包括接口地址、校验令牌的公钥地址、服务器提供的受保护资源作用域(scope)，以及其他相关的配置信息。

API说明文档：获取服务配置

IDS4官方文档-发现端点

请求code

若用户未登录，则会自动跳转至用户登录页面

当用户已登录（或登录成功），则会将code通过参数的形式回调至指定地址

API说明文档：获取用户授权code

IDS4官方文档-授权端点

使用code兑换令牌

API说明文档：兑换用户令牌

IDS4官方文档-令牌端点

刷新令牌

获取的id_token和access_token有效期默认是2小时，refresh_token有效期为30天，请做好token的持久化

原refresh_token使用后将失效，请持久化新获取的refresh_token

API说明文档：刷新令牌

用户信息修改

用户安全信息修改

用户安全信息包括：邮箱、手机号、密码、第三方绑定、关闭账号等。

由于涉及用户的隐私和账号安全，因此不提供API接口修改，需要引导用户至统一账号提供的页面进行操作：修改帐号安全信息

用户非安全信息修改

用户非安全信息可通过账号平台提供的API修改，请参考API说明文档
修改用户基本信息
修改用户头像
修改用户详细信息

第三方关联支持

第三方名称	状态	说明
WeChat	支持	网页应用：默认使用统一帐号 APP应用：需要APP应用共享key和secret 微信内网页：默认使用“中望软件技术”官方公众号，支持由客户端获取登录信息
WorkWeChat	支持	扫码登录，支持企业认证、付费关联用户姓名及部门，支持由客户端获取登录信息
QQ	支持	跳转页面，支持由客户端获取登录信息
Huawei	支持	跳转页面，支持由客户端获取登录信息
Apple	支持	由客户端获取必要的信息，加密传输至统一帐号校验进行自动注册关联和登录
Google	支持	由客户端获取Google的用户token，加密传输至统一帐号校验进行自动注册关联和登录
Facebook	支持	由客户端获取Facebook的用户token，加密传输至统一帐号校验进行自动注册关联和登录
Mobile	支持	由客户端通过阿里云获取用户手机号Token，加密传输至统一帐号校验并获取手机号，自动注册关联和登录

接入说明

术语介绍与常见对接问题#

基本术语表#

常见对接问题#

概述与规范#

中望统一账号概述#

开发规范#

权限说明#

中望账号作用域列表#

可提供服务的中望业务权限#

API资源保护#

资源注册#

资源保护#

角色控制#

获取认证与授权#

受信客户端#

客户端注册#

获取令牌#

用户客户端#

客户端注册#

获取\刷新令牌#

获取服务配置#

请求code#

使用code兑换令牌#

刷新令牌#

用户信息修改#

用户安全信息修改#

用户非安全信息修改#

第三方关联支持#

术语介绍与常见对接问题

基本术语表

常见对接问题

概述与规范

中望统一账号概述

开发规范

权限说明

中望账号作用域列表

可提供服务的中望业务权限

API资源保护

资源注册

资源保护

角色控制

获取认证与授权

受信客户端

客户端注册

获取令牌

用户客户端

客户端注册

获取\刷新令牌

获取服务配置

请求code

使用code兑换令牌

刷新令牌

用户信息修改

用户安全信息修改

用户非安全信息修改

第三方关联支持