资源工坊

版本支持 ​

V7文档中心release_dc_v7.0.2306a.20230608 以及之后版本。

面向对象 ​

该对接文档仅面向第三方集成应用，描述了如何在V7文档中心环境下如何调用集成能力。

概念说明 ​

概念说明
授权（Authorization，AuthZ）向用户或应用授予能够访问某资源的权限的行为
认证（Authentication，AuthN）一般可以分为用户身份（普通用户、超管）认证以及应用身份认证
能力提供方通过二开平台透出其集成能力的应用方，如基础应用、增值应用等，通常称为能力提供方
能力使用方通过二开平台访问集成能力的应用方，如第三方集成应用，通常称为能力使用方
OAuth2.0授权协议，支持第三方应用程序获取对 HTTP 服务的有限访问，通过编排审批交互来代表资源所有者资源所有者和 HTTP 服务之间，或通过允许第三方应用程序以自己的名义获取访问
access_token授权令牌，用于调用 Service Provider 提供的接口
refresh_token刷新令牌，在 access_token 令牌过期后，可以使用 refresh_token 获取新令牌
company_id企业唯一标识
scope调用开放平台接口、接收订阅事件通知的权限

整体流程 ​

1

签名说明 ​

集成应用接口访问默认采用WPS4签名算法进行校验。

  • 接口签名时，只签uri字段，不签域名
  • 如：/o/cid/api/xxx，只签/api/xxx部分

WPS-4签名算法

Header中需要携带以下字段：

参数参数类型是否必须说明
Content-Typestring是目前固定为: "application/json"
Wps-Docs-Datestring是取当前时间, 格式: "Wed, 23 Jan 2013 06:43:08 GMT"
Wps-Docs-Authorizationstring是签名值

Authorization计算方法如下：

Wps-Docs-Authorization: "WPS-4 ${AppId}:${Signature}"
Signature: hmac-sha256(AppKey, Ver + HttpMethod + URI + Content-Type + Date + sha256(HttpBody))
  • Ver：WPS-4，表示算法版本，后续算法有更新，则变更该字段
  • HttpMethod：表示HTTP 请求的Method的字符串，如PUT、GET、POST、HEAD、DELETE等
  • URI：不带域名，如："/api_url?app_id=aaaa"
  • Content-Type：表示请求内容的类型，如："application/json"
  • Date：对签名时限进行验证
  • HttpBody：如果为空，则sha256(body)部分取空串

访问凭证 ​

开放API的请求到达二开集成网关后，第一步是验证Access Token信息，验证通过后二开会将Token信息进行转换，并传递给业务方，业务方同样会校验Token信息，并获取其中的信息用于数据权限校验。

  • Access Token信息需携带在请求头中，格式遵循OAuth2.0协议标准

Authorization: Bearer ${access_token}

接入流程 ​

该部分旨在指导集成应用如何对接集成能力接口。

准备工作 ​

使用方接入前，需保证以下工作已完成

  • 私网创建应用

  • 应用授权：授权相关开放能力

    • 企业授权需使用云文档账号登录授权

img

  • 若涉及用户授权，则需先设置授权回调地址

img

接入流程-获取访问凭证 ​

访问凭证可分为用户授权、企业授权和应用授权凭证。

用户授权 ​

用户授权为委托授权的一种，委托人为普通用户。授权第三方应用获取所属用户相关数据。

授权流程

第三方应用需要获取用户信息（如：头像、用户名、用户文件等）时，由开放平台发起的授权流程，用户完成授权后，第三方应用可通过获取到的access_token进行数据获取。

img

​ 用户授权时序图

企业授权 ​

企业管理员授权第三方应用获取企业相关数据。

授权流程

由系统管理员对第三方应用进行的授权，如获取企业通讯录的管理权限、角色配置权限、审核日志的查询权限等，此类授权一般需要获取管理员角色相关的权限。通过企业授权获取access_token，第三方应用可以在业务系统中的对应场景操作以上管理员才具备的数据权限。

img

​ 企业授权时序图

应用授权 ​

应用授权指由平台授权第三方应用使用开放能力权限。

授权流程

由平台管理员对第三方应用进行的授权，如获取应用文档开放能力等，授权后第三方应用方可通过接口获取相应scope的access_token信息。

img

​ 应用授权时序图