资源工坊

使用方接入流程 ​

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

准备工作 ​

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

  • 私网创建应用，在二开私网创建应用或者在协作开发者后台创建应用

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

  • 若是企业授权需使用使用云文档账号登录授权 XZTY20230531-143905.png

  • 若涉及用户授权，可在协作开发者后台或者二开私网设置授权回调地址

XZTY20230531-144259.png

XZTY20230531-144123.png

详细说明可参考文档：可参考【产品文档】集成应用管理手册-20230426

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

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

用户授权 ​

用户授权为委托授权的一种，委托人为普通用户。授权第三方应用获取所属用户相关数据。（获取涉及到用户个人信息的授权，不含应用能力和企业数据的授权）

授权流程 ​

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

XZTY20230531-144903.png

（用户授权时序图）

接口说明 ​

一、构造授权跳转链接，用户授权，获取临时授权码code 根据定义，构造授权跳转链接，用户同意授权后，会重定向跳转到指定的 redirect_uri，并附带 code、state 两个参数。主要是用于用户首次登录用户授权确认，用户确认后，下次直接登录应用，无需再次授权。请求说明

请求地址配置域名+/o+/oauth+/v1/authorize
请求方法GET/POST
签名方式无
支持应用类型企业自建应用
权限要求无

查询参数（Query）

参数参数类型是否必填说明
client_idstring是应用唯一标识
response_typestring是授权类型，固定为：code
redirect_uristring是授权后重定向的回调链接地址
scopestring是用户授权的权限，多个值以英文逗号分割 （用户授权、企业授权等开放权限，请务必确认在应用管理平台已经得到了授权）
statestring否由用户自定义，授权成功后会通过重定向接口带回
auto_grantboolean否是否自动授权,如果已经登录且auto_grant为true则不跳转到授权界面

请求地址示例 ​

json
[GET] 配置域名+/o+/oauth+/v1/authorize?response_type=code&client_id=APPID&auto_grant=false&redirect_uri=REDIRECTURI&scope=SCOPE&state=STATE

用户访问三方应用构造的授权链接地址：

  • 参数auto_grant为true，用户已经登陆，那么则直接跳转至授权回调地址

  • 参数auto_grant为false，用户还未登陆,先重定向至应用管理平台授权页面，判断用户未登录，那么重定向至登录页面 XZTY20230531-150408.png

  • 登录成功之后，跳转至授权页面 XZTY20230531-150451.png

  • 点击允许，从服务端获取临时授权码code，并调转至授权回调地址

  • 参数auto_grant为false，用户已经登陆，先重定向至授权页面，判断用户已经登陆，那么等待用户操作，点击允许，从服务端获取临时授权码code，并调转至授权回调地址 XZTY20230531-151005.png

  • 参数auto_grant为true，用户还未登录，则先重定向至应用管理平台授权页面，判断用户未登录，那么重定向至登录页面 XZTY20230531-150635.png

  • 登录成功后，跳转至授权页面，无需用户操作，自动获取临时授权码code，并跳转至授权回调地址 XZTY20230531-151057.png

响应体 ​

用户访问授权链接，并登录后，会跳转至授权页。 1.用户登录页面

XZTY20230531-151323.png

2.用户授权页面

XZTY20230531-151400.png3.用户同意授权 如果用户点击同意授权，页面将重定向至授权链接中的redirect_uri地址，并携带临时授权码(code)和用户自定义参数（state）。示例：redirect_uri?code=CODE&state=STATE 注意：code 作为换取 access_token 的票据，仅可使用一次且 10 分钟未被使用自动过期。 说明：请求中的redirect_uri会进行校验，必须先配置回调授权地址（当前仅校验host:port）二、获取或刷新access_token 服务端调用该接口获取或刷新用于访问用户授权凭证access_token。用户首次登录同意授权后，下次再次打开应用，服务端处理逻辑，让用户直接免登录直接打开应用。注意：获取到的 access_token 安全级别比较高，后续刷新 access_token、通过 access_token 获取用户信息等步骤，必须从服务器调用接口。请求说明

请求地址配置域名+/o+/oauth+/v1/token
请求方法POST
签名方式WPS-4签名（url仅签名/v1/token部分）
权限要求无

请求头（Header）

名称是否必须说明
Content-Type是固定为：application/x-www-form-urlencoded
Wps-Docs-Date是取当前时间，示例：Wed, 23 Jan 2013 06:43:08 GMT
Wps-Docs-Authorization是Authorization计算方法参考签名说明

请求体（Body）

参数参数类型是否必填说明
grant_typestring是授权类型，authorization_code：授权码模式，refresh_token：刷新授权码
codestring否临时授权码，grant_type为authorization_code时必填
redirect_uristring否授权回调地址，grant_type为authorization_code时必填
refresh_tokenstring否刷新凭证，grant_type为refresh_token时必填
scopestring是权限项

响应体（Response）

名称类型说明
codeinteger状态码，非0表示失败，参照状态码说明
msgstring错误信息，成功时统一为Success
dataobject
∟tokenobject凭证信息
∟access_tokenstring访问凭证
∟token_typestring固定为Bearer
∟expires_ininteger凭证有效期，单位为秒
∟refresh_tokenstring刷新凭证，在授权未过期之前，可用于刷新/重新获取访问凭证
∟access_tokenstring访问凭证
access_tokenstring访问凭证
token_typestring固定为Bearer
expires_ininteger凭证有效期，单位为秒
refresh_tokeninteger刷新凭证

响应体示例

json
{
  "code": 0,
  "data": {
    "token": {
      "access_token": "ACCESSTOKEN",
      "token_type": "Bearer",
      "expires_in": "EXPIRES",
      "refresh_token": "REFRESHTOKEN"
    }
  },
  "access_token": "ACCESSTOKEN",
  "token_type": "Bearer",
  "expires_in": "EXPIRES",
  "refresh_token": "REFRESHTOKEN"
}

企业授权 ​

企业授权为应用授权的一种，企业管理员授权第三方应用获取企业相关数据。（使用的能力涉及到企业数据，需要得到企业管理员的同意）

授权流程 ​

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

XZTY20230531-163844.png

（企业授权时序图）

接口说明 ​

获取企业授权凭证access_token 获取已授权的企业类型权限对应的access_token信息。（此处的access_token是企业超管授权第三方应用访问企业资源的凭证） 注意：企业授权凭证access_token有效期24小时，过期后可重新获取新的access_token。

请求说明

请求地址配置域名+/o+/oauth+/v1/token
请求方法POST
签名方式WPS-4签名（url仅签名/v1/token部分）
权限要求无

请求头（Header）

名称是否必须说明
Content-Type是固定为：application/x-www-form-urlencoded
Wps-Docs-Date是取当前时间，示例：Wed, 23 Jan 2013 06:43:08 GMT
Wps-Docs-Authorization是Authorization计算方法参考签名说明

请求体（Body）

参数参数类型是否必填说明
grant_typestring是授权类型，client_credentials：客户端模式
scopestring是权限项
company_idstring否企业id，多租户下的企业必传

响应体（Response）

名称类型说明
codeinteger状态码，非0表示失败，参照状态码说明
msgstring错误信息，成功时统一为Success
dataobject
∟tokenobject凭证信息
∟access_tokenstring访问凭证
∟token_typestring固定为Bearer
∟expires_ininteger凭证有效期，单位为秒
access_tokenstring访问凭证
token_typestring固定为Bearer
expires_ininteger凭证有效期，单位为秒

响应体示例

json
{
  "code": 0,
  "data": {
    "token": {
      "access_token": "ACCESSTOKEN",
      "token_type": "Bearer",
      "expires_in": "EXPIRES"
    }
  },
  "access_token": "ACCESSTOKEN",
  "token_type": "Bearer",
  "expires_in": "EXPIRES"
}

应用授权 ​

应用授权指由平台授权第三方应用使用开放能力权限。（使用的能力不涉及到企业数据，平台方比如二开平台同意即可使用能力）

授权流程 ​

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

XZTY20230531-170806.png

（应用授权时序图）

接口说明 ​

获取应用授权凭证access_token 获取已授权的应用类型权限对应的access_token信息。

注意：授权凭证access_token有效期24小时，过期后可重新获取新的access_token。请求说明

请求地址配置域名+/o+/oauth+/v1/token
请求方法POST
签名方式WPS-4签名（url仅签名/v1/token部分）
权限要求无

请求头（Header）

名称是否必须说明
Content-Type是固定为：application/x-www-form-urlencoded
Wps-Docs-Date是取当前时间，示例：Wed, 23 Jan 2013 06:43:08 GMT
Wps-Docs-Authorization是Authorization计算方法参考签名说明

请求体（Body）

参数参数类型是否必填说明
grant_typestring是授权类型，client_credentials：客户端模式
scopestring否权限项

响应体（Response）

名称类型说明
codeinteger状态码，非0表示失败，参照签名说明
msgstring错误信息，成功时统一为Success
dataobject
∟tokenobject凭证信息
∟access_tokenstring访问凭证
∟token_typestring固定为Bearer
∟expires_ininteger凭证有效期，单位为秒
access_tokenstring访问凭证
token_typestring固定为Bearer
expires_ininteger凭证有效期，单位为秒

响应体示例

json
{
  "code": 0,
  "data": {
    "token": {
      "access_token": "ACCESSTOKEN",
      "token_type": "Bearer",
      "expires_in": "EXPIRES"
    }
  },
  "access_token": "ACCESSTOKEN",
  "token_type": "Bearer",
  "expires_in": "EXPIRES"
}

开源SDK使用 ​

授权接口采用OAuth2.0协议标准，故认证授权接口支持通过三方SDK来调用。 如支持golang开源的OAuth2.0 Package调用（https://github.com/golang/oauth2）

  • 官方提供了默认的Auth Basic认证方式，安全度不高，需使用本方案的签名方案
  • golang官方提供了扩展认证方式，步骤如下：1.自定义HTTPClient XZTY20230531-171821.png 2.传入自定义HTTPClient XZTY20230531-171915.png