Passport 客户端API接入指南

客户端API

Passport 客户端API是面向已有独立的ID系统，需要使用UOS Passport提供的其它服务(如好友，权利，排行榜等)的开发者提供的客户端API列表。
以下文档中 URL / Request / Response 中出现的 idDomainID 均为 UOS App ID

API Endpoint: https://p.unity.cn

用户身份认证(JWT)

使用 UOS Passport 提供的所有客户端API之前都需要将已有的独立的ID系统的用户/角色关联到 UOS 系统的用户与角色，并获取 JWT 用户认证信息。

如何关联 UOS 角色并获取 JWT ?

未集成客户端 SDK 的开发者，可使用 External Login API 来关联 UOS 角色并获取 JWT。

JWT API 基本信息

接口功能: 关联 UOS 角色并获取 JWT
请求方法: POST
请求地址: https://p.unity.cn/v1/login/external
请求体: application/json

{
    "externalUserID": "<userId>", //需要获取 JWT 的玩家 id,
    "externalPersonaID": "<personaID>", //可选，非必填，需要获取 JWT 的角色 id,
    "displayName": "<displayName>", //可选，非必填，角色名字（仅创建时传入生效）,
    "realmID": "<realmID>" //可选，非必填，服务器 id
}

响应数据

{
    "personaAccessToken": "<token>",  //JWT(JSON Web Token), 可用于后续 API 的鉴权
    "personaRefreshToken": "<token>",  //角色 RefreshToken
    "expiresAt": "<expiresAt>"   //JWT 的过期时间
}

是否需要认证: 需携带 Authorization

使用 Nonce Authorization 来获取 JWT，步骤如下:

在 UOS 网站上获取当前需要使用的 UOS APP 的 AppId 和 AppSecret
注：此处 AppId 和 AppSecret，可在 UOS 网站上获取
在请求 JWT API 的 Request Header 中增加如下 Header:
- X-TIMESTAMP: 当前时间戳
- X-NONCE: 随机生成的UUID
- X-APPID: 当前需要使用的 UOS APP 的 AppId
- Authorization: nonce hexadecimal(sha256(appId + ":" + appSecret + ":" + X-TIMESTAMP + ":" + X-NONCE))
完整获取 JWT 参考示例如下:

授权

获取用户的JWT身份认证信息后，在后续请求下列客户 API 的 Request Header 中增加如下 Header:

Authorization: Bearer {jwt}
X-TIMESTAMP: 当前时间戳
X-NONCE: 随机生成的UUID
X-APPID: 当前需要使用的 UOS APP 的 AppId
X-NONCE-TOKEN: hexadecimal(sha256(appId + ":" + appSecret + ":" + X-TIMESTAMP + ":" + X-NONCE))

"Nonce Authorization"是一种身份验证机制，用于确保在通信中的请求是合法的。"Nonce" 是 "Number Used Once"（一次性数字）的缩写，是一个只能使用一次的随机或唯一值。Nonce 在身份验证中通常用于防止重放攻击。

Passport 客户端API接入指南

Passport 客户端API接入指南

客户端API

用户身份认证(JWT)

JWT API 基本信息

授权

客户端可供集成的 API 列表

Realm

User

Persona

Friends

Report

AntiAddiction

Leaderboard

Guild

Token

Achievement

Economy

Inbox

Billboard

BattlePass

Quest

MonthlyCard