文档帮助平台
首页服务端API参考 应用开发集成文档 网页应用 网页应用免登
网页应用免登
更新时间：2025-01-22 17:53:48

网页应用免登

身份验证为应用 web 系统提供了获取正在访问的UC用户身份的能力，便于应用 web 系统构建登录流程。

步骤

第一步：获取Client ID 与 Client Secret

企业管理员可登陆企业管理平台，在应用管理菜单下选择编辑对应应用。在应用编辑界面的应用凭证菜单下可获得应用唯一的Client ID 与 Client Secret。

获取凭证

第二步：获取授权码code

获取授权码有三种方式：

第一种：从url携带的参数中获取（适用于工作台窗口、独立UME浏览器窗口、系统浏览器打开）

首先需要应用打开主页跳转配置中的应用免登开关。

应用免登

打开开关后，从ume工作台打开应用主页时，会自动将授权码code携带在url上。例如：https://www.baidu.com?code=abcdefg

应用前端需要获取参数中的code字段内容来获取授权码。

第二种：主动调用jsapi获取（适用于工作台窗口和独立UME浏览器窗口打开）

  • 在需要进行免登的页面引入UC提供的JS文件：
<script src="/ume-js-api-4.0.4.js"></script>
  • 通过主动调用js方法获取code：
ume.permission.getCode({
    clientId:"",// 应用程序对应的 Client ID
    redirectUri:"",// 应用的访问地址
    success: function (res) {
        // 成功回调参数
        // 如：{"code":"xxx"}
    }
})

详情请查看 UME JS-API接口文档.zip。

第三种：访问UC免登页面获取（适用于工作台窗口和独立UME浏览器窗口打开）

UC提供了一个免登页面以帮助应用获取授权码code，然后自动携带code重定向到应用地址。

具体页面地址为：{{UC服务器地址}}+/ume/workbench/pc/authen。

需要携带两个参数在url上：

  • clientId：应用自身clientId
  • redirectUri：需要重定向到的地址。（参数需要经过 URLEncode 处理）

例如https://www.yealink.com/ume/workbench/pc/authen?clientId=cli_9dff7f6ae&redirectUri=http%3A%2F%2Fwww.yealink.com

code 有效期为5分钟，且只能使用一次。

第三步：获取access token

获取到code之后，需要携带code和redirect_uri获取access token。具体获取接口参考获取访问凭证。

redirect_uri参数内容为当前浏览器访问的地址。

UC系统授信的redirect_uri地址为管理员为应用配置的PC&移动端主页地址。

token 有效期为 1 小时。建议在40分钟左右使用refresh token再次请求获取新token，避免token过期造成的请求失败，与此同时旧的 token 依然有效。

请求消息示例

POST /open/api/v2/token HTTP/1.1
Content-Type: application/json
accept: application/json
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
timestamp: 1610544682145
nonce: aac64aa63454457294d440d8be191254

{
    "grant_type": "authorization_code",
    "code": "XXXXXXXXXXXX",
    "redirect_uri":"xxxxx"
}

响应参数示例

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "[JWT TOKEN]",
  "token_type": "bearer", 
  "refresh_token": "[JWT TOKEN]",
  "expires_in": 3599,
  "refresh_expires_in": 86399
}
第四步：获取登陆用户信息

获取到用户级access token后，可请求用户查询接口获取当前登陆用户信息。具体获取接口参考查询登陆用户详情。应用内部维护当前登录用户与自身账号体系的关联关系

请求消息示例

GET /open/api/v2/users/me HTTP/1.1
Host: api.yealink.com
Content-Type: application/json

响应参数示例

HTTP/1.1 200 
Content-Type: application/json;charset=UTF-8

{
	"id": "9ecc83e4c7d44728bbb1e2ec226dffe7",
	"partyId": "c22c0ab68bc74219aa894261b2d131dc",
	"groupId": "65ddf0d5c0d64d4aab3bacc2cd690c28",
	"type": 2,
	"name": "zd3",
	"email": "test@yealink.com",
	"number": "145516*2222",
    "status": "offline",
	"extension": null,
	"extAccount": "zd3",
	"mobile": "13500000000",
	"title": null,
	"gender": 0,
	"accountStatus": 0,
	"emailBound": false,
	"mobileBound": false,
	"permissionCode": "A"，
	"enableMeetingNow": false,
	"enableMeetingAppoinitment": true
}
第五步：刷新access token

refresh_token用途

  • 免登操作成功后，因access_token有效期较短，当access_token 过期时 便可携带refresh_token(该refresh_token取第三步请求响应体中的refresh_token响应参数)调用接口获取新的access_token 和 refresh_token，以保证调用UC API接口时携带的access_token均为有效的，避免access_token过期导致调用UC API失败。
  • 获取的access_token和refresh_token均存在有效期，前者有效期较短，后者较长。
  • 通过 refresh_token获取的新 access_token 和 refresh_token 有效期与初次生成一致。具体获取接口参考获取访问凭证。

refresh token 有效期为 24 小时。使用refresh token再次请求获取新token时会得到新的refresh token，与此同时旧的refresh token失效。

请求消息示例

POST /open/api/v2/token HTTP/1.1
Content-Type: application/json
accept: application/json
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
timestamp: 1610544682145
nonce: aac64aa63454457294d440d8be191254

{
    "grant_type": "refresh_token",
    "refresh_token": "XXXXXXXXXXXX"
}

响应参数示例

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "[JWT TOKEN]",
  "token_type": "bearer", 
  "refresh_token": "[JWT TOKEN]",
  "expires_in": 3599,
  "refresh_expires_in": 86399
}
本页目录