一、概述
本章节将介绍客户基于自有用户管理系统（AM）对接VSaaS云存储功能的实现方案。VSaaS平台自带设备管理功能（DM），支持设备与方案绑定、事件查询/回放/下载/删除等操作，第三方系统通过认证对接后可直接使用这些功能。
核心对接逻辑：通过OAuth 2.0协议实现第三方AM系统与VSaaS平台的身份认证，完成用户信息校验和令牌交换，最终第三方APP可通过VSaaS Token访问云存储相关功能。
二、第三方认证流程
图：VSaaS第三方认证对接流程
第三方认证用于云端服务器之间的用户信息合法性校验，采用OAuth 2.0协议流程，具体步骤如下：
- 1. 用户使用第三方APP注册账号，并通过登录API登录第三方AM系统；
- 2. 第三方AM系统返回特定的auth code给第三方APP；
- 3. 第三方APP调用「Get Vsaas Token API」，携带auth code请求TUTK VSaaS服务器；
- 4. TUTK VSaaS服务器调用「Get Access Token API」，从第三方AM系统获取Access Token，具体可参考：用户信息认证；
- 5. 第三方AM系统返回Access Token给TUTK VSaaS服务器；
- 6. TUTK VSaaS服务器调用「Get User Info API」，携带Access Token从第三方AM系统获取用户信息；
- 7. 第三方AM系统返回用户信息给TUTK VSaaS服务器；
- 8. TUTK VSaaS服务器验证用户信息合法性，生成VSaaS Token并返回给第三方APP；
- 9. 第三方APP可通过「VSaaS Refresh Token API」从TUTK VSaaS服务器获取刷新令牌（refresh token），用于Token过期后重新获取。
三、API接口
（一）获取VSaaS令牌（Get vsaas token）
第三方APP通过此接口向VSaaS服务器提交auth code，获取用于访问VSaaS功能的核心令牌（vsaas token）。
1. 请求说明
| 项 | 说明 |
|---|---|
| HTTP请求方式 | POST（VSaaS固定URL：https://vsaas-domain/vsaas/api/v1/auth/oauth_token?realm={realm}） |
| 请求头（Header） | Authorization: Basic {base64(client_id:client_secret)}（客户自有client_id和client_secret，需与VSaaS预先配置一致）Content-Type: application/x-www-form-urlencoded |
2. 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
realm | String | 是 | 由TUTK提供，用于区分不同客户 |
grant_type | String | 是 | 固定值："authorization_code" |
code | String | 是 | 第三方AM系统返回的auth code（授权码） |
scope | String | 否 | 权限范围，多个权限用空格分隔（由VSaaS定义支持的权限） |
state | String | 否 | APP生成的随机字符串，用于防止CSRF攻击，响应将返回相同值 |
3. 响应说明
3.1 响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
access_token | String | VSaaS核心令牌，用于访问云存储及设备管理功能 |
token_type | String | 固定返回："Bearer" |
expires_in | String | 令牌有效期（单位：秒），默认3小时（10800秒） |
refresh_token | String | VSaaS刷新令牌，用于access_token过期后重新获取 |
scope | String | 实际授予的权限范围 |
3.2 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回VSaaS令牌及相关信息 |
| 400 | 参数错误 | realm、code缺失或格式错误 |
| 401 | 认证失败 | client_id/client_secret无效，或auth code已过期 |
4. 接口示例
请求示例（curl）
curl -X POST https://vsaas-domain/vsaas/api/v1/auth/oauth_token?realm={realm} \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code&code=theauthcode'
响应示例（成功）
{
"expires_in": 10800,
"scope": "read write",
"token_type": "Bearer",
"refresh_token": "BqVK9Dv8EdS7fCxVKtIAvlzHCNn9eg",
"access_token": "sDDJFhDo80cstYKnWBhq7ErA2dP45Y"
}
（二）刷新VSaaS令牌（Refresh Vsaas Token）
当VSaaS的access_token过期时，第三方APP通过此接口使用refresh_token获取新的access_token。
1. 请求说明
| 项 | 说明 |
|---|---|
| HTTP请求方式 | POST（VSaaS固定URL：https://vsaas-domain/vsaas/api/v1/auth/refresh_token?realm={realm}） |
| 请求头（Header） | Authorization: {原access_token}（过期前的有效access_token）Content-Type: application/x-www-form-urlencoded |
2. 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
realm | String | 是 | 由TUTK提供，与获取VSaaS令牌时一致 |
grant_type | String | 是 | 固定值："refresh_token" |
refresh_token | String | 是 | 上一次获取VSaaS令牌时返回的refresh_token |
client_id | String | 是 | 由TUTK提供的客户唯一标识 |
client_secret | String | 是 | 由TUTK提供的客户密钥 |
3. 响应说明
3.1 响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
access_token | String | 新的VSaaS访问令牌 |
token_type | String | 固定返回："Bearer" |
expires_in | String | 新令牌有效期（单位：秒），默认3小时（10800秒） |
refresh_token | String | 新的刷新令牌（支持循环使用） |
scope | String | 权限范围（与原令牌一致） |
3.2 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回新的VSaaS令牌 |
| 400 | 参数错误 | 必填参数缺失或格式错误 |
| 401 | 认证失败 | refresh_token无效、client_id/client_secret错误，或realm不匹配 |
4. 接口示例
请求示例（curl）
curl -X POST https://vsaas-domain/vsaas/api/v1/auth/refresh_token/ \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=refresh_token&refresh_token=BqVK9Dv8EdS7fCxVKtIAvlzHCNn9eg&client_id=0Feq934VvPK4CZW9FTdKCtnYHo2CApSSLxhBDXTK&client_secret=DdVaF0eitGygXCPRt7OtJJGwQHEbWq7A6ddqkDekyqwkxHJG2XrqwmQ5ZOn3tTTDTlpNjkgffXmCnfU26e0frlt8dulI0iz59tuSxdvdq63NHrPUVUNxuzX7mreJs7ip'
响应示例（成功）
{
"expires_in": 10800,
"scope": "read write",
"token_type": "Bearer",
"refresh_token": "QDTw4Q3pp9PuSwe2WOW7QV2bviXuaC",
"access_token": "h8kz9fLfuk0x77Co8rJZAveTAhn71L"
}
四、对接资料
对接前需第三方平台需向TUTK提供以下资料，TUTK将根据客户的需求，生成并提供对应的对接资料，确保认证流程正常打通：
（一）TUTK 提供的资料
| 资料名称 | 用途说明 |
|---|---|
realm | 客户唯一标识，用于VSaaS平台区分不同对接客户 |
plan id | 云存储方案ID，绑定设备时使用 |
client_id | VSaaS分配给客户的唯一标识，用于令牌交换时的身份校验 |
client_secret | VSaaS分配给客户的密钥，用于令牌交换时的签名校验 |
vsaas backend url | VSaaS后端服务地址（含令牌接口、设备管理接口等） |
（二）客户需要提供的资料
| 资料名称 | 用途说明 |
|---|---|
client_id | 客户AM系统分配给VSaaS的唯一标识（用于VSaaS访问客户AM接口） |
client_secret | 客户AM系统分配给VSaaS的密钥（用于VSaaS访问客户AM接口） |
token交换的url | 客户AM系统的令牌交换接口URL（支持获取/刷新Access Token） |
用户信息认证的url | 客户AM系统的用户信息查询接口URL（支持通过Access Token获取用户email） |
