一、概述
本章節(jié)將介紹客戶基于自有用戶管理系統(tǒng)（AM）對接VSaaS云存儲功能的實現(xiàn)方案。VSaaS平臺自帶設備管理功能（DM），支持設備與方案綁定、事件查詢/回放/下載/刪除等操作，第三方系統(tǒng)通過認證對接后可直接使用這些功能。
核心對接邏輯：通過OAuth 2.0協(xié)議實現(xiàn)第三方AM系統(tǒng)與VSaaS平臺的身份認證，完成用戶信息校驗和令牌交換，最終第三方APP可通過VSaaS Token訪問云存儲相關功能。
二、第三方認證流程
圖：VSaaS第三方認證對接流程
第三方認證用于云端服務器之間的用戶信息合法性校驗，采用OAuth 2.0協(xié)議流程，具體步驟如下：
- 1. 用戶使用第三方APP注冊賬號，并通過登錄API登錄第三方AM系統(tǒng)；
- 2. 第三方AM系統(tǒng)返回特定的auth code給第三方APP；
- 3. 第三方APP調(diào)用「Get Vsaas Token API」，攜帶auth code請求TUTK VSaaS服務器；
- 4. TUTK VSaaS服務器調(diào)用「Get Access Token API」，從第三方AM系統(tǒng)獲取Access Token，具體可參考：用戶信息認證；
- 5. 第三方AM系統(tǒng)返回Access Token給TUTK VSaaS服務器；
- 6. TUTK VSaaS服務器調(diào)用「Get User Info API」，攜帶Access Token從第三方AM系統(tǒng)獲取用戶信息；
- 7. 第三方AM系統(tǒng)返回用戶信息給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. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
realm | String | 是 | 由TUTK提供，用于區(qū)分不同客戶 |
grant_type | String | 是 | 固定值："authorization_code" |
code | String | 是 | 第三方AM系統(tǒng)返回的auth code（授權(quán)碼） |
scope | String | 否 | 權(quán)限范圍，多個權(quán)限用空格分隔（由VSaaS定義支持的權(quán)限） |
state | String | 否 | APP生成的隨機字符串，用于防止CSRF攻擊，響應將返回相同值 |
3. 響應說明
3.1 響應參數(shù)
| 參數(shù)名 | 類型 | 說明 |
|---|---|---|
access_token | String | VSaaS核心令牌，用于訪問云存儲及設備管理功能 |
token_type | String | 固定返回："Bearer" |
expires_in | String | 令牌有效期（單位：秒），默認3小時（10800秒） |
refresh_token | String | VSaaS刷新令牌，用于access_token過期后重新獲取 |
scope | String | 實際授予的權(quán)限范圍 |
3.2 響應狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回VSaaS令牌及相關信息 |
| 400 | 參數(shù)錯誤 | 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. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
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 響應參數(shù)
| 參數(shù)名 | 類型 | 說明 |
|---|---|---|
access_token | String | 新的VSaaS訪問令牌 |
token_type | String | 固定返回："Bearer" |
expires_in | String | 新令牌有效期（單位：秒），默認3小時（10800秒） |
refresh_token | String | 新的刷新令牌（支持循環(huán)使用） |
scope | String | 權(quán)限范圍（與原令牌一致） |
3.2 響應狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回新的VSaaS令牌 |
| 400 | 參數(shù)錯誤 | 必填參數(shù)缺失或格式錯誤 |
| 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將根據(jù)客戶的需求，生成并提供對應的對接資料，確保認證流程正常打通：
（一）TUTK 提供的資料
| 資料名稱 | 用途說明 |
|---|---|
realm | 客戶唯一標識，用于VSaaS平臺區(qū)分不同對接客戶 |
plan id | 云存儲方案ID，綁定設備時使用 |
client_id | VSaaS分配給客戶的唯一標識，用于令牌交換時的身份校驗 |
client_secret | VSaaS分配給客戶的密鑰，用于令牌交換時的簽名校驗 |
vsaas backend url | VSaaS后端服務地址（含令牌接口、設備管理接口等） |
（二）客戶需要提供的資料
| 資料名稱 | 用途說明 |
|---|---|
client_id | 客戶AM系統(tǒng)分配給VSaaS的唯一標識（用于VSaaS訪問客戶AM接口） |
client_secret | 客戶AM系統(tǒng)分配給VSaaS的密鑰（用于VSaaS訪問客戶AM接口） |
token交換的url | 客戶AM系統(tǒng)的令牌交換接口URL（支持獲取/刷新Access Token） |
用戶信息認證的url | 客戶AM系統(tǒng)的用戶信息查詢接口URL（支持通過Access Token獲取用戶email） |
