实例中心

最近更新时间:11/9/2023, 4:22:43 PM作者:andrewren(任豪)

基础概念

商品中心包含的所有应用(人工交付类型、SaaS交付类型),在被购买后均会在用户控制台中产生对应应用实例供用户使用,实例中心主要负责管理应用实例的生命周期,包括:实例发货、实例续费、实例变配(配置变更)、实例过期、实例销毁等操作。

人工交付类型接入

人工交付类型过程较为简单,此类商品在应用市场上架后,用户选择购买后,在用户控制台可看到对应人工交付的实例,点击实例信息可查看服务商联系方式,用户与服务商通过线下联系交付,交付完成后,用户在控制台点击“确认交付”进行确认。

此交付类型暂无第三方接入案例,即使需要接入也十分简单,只需在应用市场录入人工交付类应用并上架即可,在此不作赘述。

SaaS交付类型接入

物料准备

物料 提供方 说明
发货URL 第三方 由服务商开发,用于接受工业云SPI消息的地址
发货Token 第三方 由服务商提供,用于校验SPI消息的有效性
按照规范说明实现回调的六个接口(实例发货、续费、销毁、过期、配置变更、idaas&免密登录) 第三方 接口规范及标准详情见API规范部分

对接内容

服务提供商需要实现对接的六个接口,即可获得商品购买成功后的信息,并将相关成功信息返回给地市云展示给用户,六个步骤分别为实例发货、续费、销毁、过期、配置变更、idaas&免密登录。

内容 详情
发货URL&Token校验 接口规范及标准详情见API规范部分
实例创建接口 接口规范及标准详情见API规范部分
实例续费接口 接口规范及标准详情见API规范部分
实例过期接口 接口规范及标准详情见API规范部分
实例配置变更接口 接口规范及标准详情见API规范部分
实例免密登录接口 接口规范及标准详情见 API规范部分

具体如下:

步骤类型 触发场景 功能介绍 内容描述 适用版本
实例发货通知 用户通过工业云新购Saas类应用 地市云通知服务提供商发货处理。 用户( 认证的个人&企业账号)购买Saas类应用,支付后,应用市场通过调用服务提供商的实例发货通知接口发送信息至发货URL,由此通知服务提供商进行相应发货处理,发货成功后返回相应发货详情信息,包括服务商提供的唯一标识、免密地址等信息,实现用户购买、通知发货、服务商发货整个流程。需要注意的是,创建实例通知时,工业云会附加IDaaS信息,服务提供商需要保存IDaaS信息,并实现IDaaS规定的免密登录接口。 >=5.3
实例续费通知 用户对本地Saas类-周期售卖应用进行续费操作 地市云通知服务提供商续费处理。 用户( 认证的个人&企业账号)对已购Saas应用进行续期(应用在有效期内),用户在地市云控制台进行续费后,实例中心会通过实例续期接口发送续费消息至发货URL,服务商立刻返回续期结果,由此实现用户续费流程。 >=5.3
实例过期通知 用户购买本地Saas类-周期售卖应用,实例使用时间到期 地市云通知服务提供商过期处理。 用户通过地市云应用市场购买的周期售卖类应用,当实例超过过期时间后,应用市场会关闭地市云控制台实例,地市云应用市场会通过实例过期接口发送过期消息至发货URL,服务商返回处理结果。 >=5.3
实例销毁通知 用户使用过期后关闭 地市云通知服务提供商关闭处理 暂时不涉及,服务提供商调试此接口时,返回通过即可,在用户购买整个流程中,不涉及此操作 >=5.3
实例配置变更通知 用户对Saas类-周期售卖应用进行升级操作 地市云通知服务提供商商品配置修改处理。 用户( 认证的个人&企业账号)通过地市云应用市场购买过周期售卖应用后,且应用在有效期内,用户可对购买的Saas类服务进行配置变更升级或试用转正,包括规格、额外计费项等内容,用户通过地市云控制台进行升级操作,地市云应用市场会通过实例配置变更接口发送消息至发货URL,服务商立刻返回配置变更结果,此处需要用户配置变更,可能会包括规格修改与续费时间等参数。 >=5.5
实例免密登陆URL 用户通过工业云新购本地Saas类应用操作,服务提供商返回免密URL 地市云通知服务提供购买Saas免密地址。 用户( 认证的个人&企业账号)通过地市云应用市场购买本地应用类目下Saas类应用,地市云应用市场通知服务商发货后,服务商返回免密登陆地址,用户在地市云控制台即可通过进入应用按钮,通过免密地址进入服务提供商提供的Saas服务。 >=5.3
实例密码模式 用户通过工业云新购本地SaaS类应用,服务提供商返回管理地址、用户名、密码信息 地市云通知服务提供购买管理地址、账号信息 用户( 认证的个人&企业账号)通过地市云应用市场购买本地应用类目下Saas类应用,地市云应用市场通知服务商发货后,服务商返回管理地址、用户名、密码,用户在地市云控制台查看联系方式,即可查看服务商返回管理地址、用户名、密码,通过复制地址,登录即可进入应用 5.4

接口说明

在进⾏接⼝开发前,请了解以下相关要求:

项目 说明
传输协议 HTTP 传输协议
提交⽅式 均采⽤ POST ⽅法提交
数据格式 提交和响应均为 JSON 格式
字符编码 统⼀使⽤ UTF-8 字符编码
签名算法 SHA256, 具体签名校验⽅法下⽂详述
请求超时时间 3s
重试策略 请求失败会重试3次(创建、续费、配置变更、销毁)

验证流程

服务提供商与地市云进行对接涉及六个关键步骤,除此以外在进行接口调用过程中还涉及接口校验逻辑处理,其中接口合法性校验用于验证发货URL与Token合法性,这个过程贯穿于每个接口调用过程。

地市云运营商在sp端 - 服务管理 - 本地应用中,配置商品信息,在发货配置页面,添加发货URL与Token,保存商品,进行发货地址URL与Token校验,在编辑商品后,修改发货URL、Token后,也会进行发货地址校验。具体流程如下图所示:

接口验证

img

调试过程:

img

签名方法

服务商在控制台配置发货接⼝ URL 和 Token 后,⼯业云会以 Query String(GET 参数)的⽅式添加到 接⼝ URL 上,携带的参数如下:

参数 类型 说明
signature string 加密签名, signature 结合了服务商填写的 Token 参数和请求中的 timestamp 参数、eventId 等参数
timestamp integer UNIX 时间戳
eventId integer 随机数

服务商通过对传入的signature和自己计算出的signature进⾏校验,加密/校验流程如下:

(1)判断 timestamp 是否已经超时(签名推荐超时为30s,免登校验推荐为120s)。

(2)将 Token、timestamp、eventId 三个参数进⾏字典序排序。

(3)将三个参数字符串,拼接成⼀个字符串进⾏ SHA256 加密。

(4)服务商将加密后的字符串与 signature 对⽐即可。

检验 signature 的 Go 示例代码:

const Token = "abc123"
func checkSignature(signature, timestamp, eventId string) (bool, error) {
    currentTime := time.Now().Unix()
    timeInt, err := strconv.ParseInt(timestamp, 10, 64)
    if err != nil {
        return false, err
    }
    // 判断timestamp是否已经超时
    if currentTime - timeInt > 30 {
        return false, nil
    }
    //将 Token、timestamp、eventId 三个参数进⾏字典序排序
    toSignParams := []string{Token, timestamp, eventId}
    sort.Strings(toSignParams)
    // 将三个参数字符串,拼接成⼀个字符串进⾏SHA256加密
    signString := ""
    for _, k := range toSignParams {
        signString = signString + k
    }
    h := sha256.New()
    h.Write([]byte(signString))
    computeSignature := h.Sum(nil)
    signatureString := fmt.Sprintf("%x", computeSignature)
    //服务商将加密后的字符串与signature对⽐
    if signature == signatureString {
        return true, nil
    }
    return false, nil
}

检验 signature 的 PHP 示例代码:

function checkSignature($signature, $token, $timestamp, $eventId)
{
 $currentTimestamp = time();
 if ($currentTimestamp - $timestamp > 30) {
 return false;
 }
 $timestamp = (string)$timestamp;
 $eventId = (string)$eventId;
 $params = array($token, $timestamp, $eventId);
 sort($params, SORT_STRING);
 $str = implode('', $params);
 $requestSignature = hash('sha256', $str);
 return $signature === $requestSignature;
}

实例创建通知接⼝

请求参数

参数名 类型 是 否 必 须 描述
action string 取值: "createInstance"
orderId string 订单 ID, 仅包含数字且⻓度为14到20
accountId string 购买者账号 ID, 仅包含数字且⻓度为5到20
productId string 商品 ID
requestId string 接⼝口请求 ID
productInfo object json字符串串 - 商品信息
productInfo.productName string 购买的产品名称
productInfo.isTrial bool 是否为试⽤,true:是,false:否
productInfo.spec string 产品规格,是试⽤时为空
productInfo.timeSpan integer 购买时⻓,是试用时为空
productInfo.timeUnit string 购买时⻓长单位,取值:"y"、"m"、"d"、"h"、"t" 分别代表年、 月、日、时、次,是试用时为空
extendInfo object json字符串 - 订单扩展信息,⽤户同步IDaaS信息
extendInfo.applicationId string idaas应用id,和⽤户所购实例⼀一对应. 后续⽤户在单点登录时会再次带给服务商,以标识⽤用户所要登录的实例, 包含英⽂字符、数字、'-',⻓度限制40字符
extendInfo.certificate string idaas应⽤公钥,⽤于⽤户单点登录时服务商验证单点登录参数 id_token的合法性,从而保证登录的安全性。内容格式为x509 pem certificate
extendInfo.userId string 购买者userId,⼀般与accountId相同

返回参数:

参数名 类型 是 否 必 须 描述
signId string 实例标识 ID,服务商提供的唯⼀标识。不可为空,⻓度最长为64位。
appInfo object 实例信息
appInfo.website string 服务商官网地址
additionalInfo array of object 附加数据,⽤于免密登录。格式为[{"name":"","value":""}]
additionalInfo[i].name string 附加数据项的名称。必须有值: "ssoUrl": 免密登录地址
additionalInfo[i].value string 附加数据项的值

实例续费通知接⼝

接⼝说明:⽤户续费商品后,工业云将通过实例续费通知接口发送消息至发货 URL。该接⼝需要服务商⽴即返回响应。

请求参数

参数名 类型 是 否 必 须 描述
action string 取值: "renewInstance"
orderId string 订单 ID
accountId string 购买者账号 ID
productId string 商品 ID
requestId string 接⼝请求的 ID
signId string 实例标识 ID
instanceExpireTime string 新的实例到期时间,格式:yyyy-MM-dd HH:mm:ss

返回参数

参数名 类型 是 否 必 须 描述
success string 取值:"true"/"false"

实例过期通知接⼝

请求参数

参数名 类型 是 否 必 须 描述
action string 取值: "expireInstance"
accountId string 购买者账号 ID
productId string 商品 ID
requestId string 接⼝请求的 ID
signId string 实例标识 ID。服务商提供的唯一标识。⻓度最长为11位

返回参数

参数名 类型 是 否 必 须 描述
success string 取值:"true"/"false"

请求示例

curl -X POST 'http://isv/interface? signature=e3k9ierw&timestamp=1483944926&eventId=1780012140' --data '{"action":"expireInstance","accountId":"123545678","productId":"7c652d37- e12b-4b4f-aa65-6432d03f12f3","requestId":"ea372177-809d-4722-91d0- d6df4edf7bc9","signId":"kjsadkjhdskjh3k"}'

响应示例

{"success":"true"}

实例配置变更通知接⼝

接⼝说明:⽤户将实例从试⽤版转为正式版时或变更更规格时,工业云应用市场将通过实例配置变更通知接口发送消息至发货 URL。

请求参数

参数名 类型 是 否 必 须 描述
action string 取值: "modifyInstance"
orderId string 订单 ID
accountId string 购买者账号 ID
productId string 商品 ID
requestId string 接⼝请求的 ID
signId string 实例标识 ID
spec string 实例新规格
timeSpan string 购买时⻓,仅在试用版转为正式购买时传递
timeUnit string 购买时⻓单位(y、m、d、h、t 分别代表年、⽉、 ⽇、时、次),是试⽤时为空
instanceExpireTime string 新的实例到期时间,格式:yyyy-MM-dd HH:mm:ss

注意: 如果⽤户仅是配置变更,则参数中只会包含实例的新规格,⽽不会包含实例价格参数。 返回参数

参数名 类型 是 否 必 须 描述
success string 取值:"true"/"false"

请求示例

curl -X POST -H 'Content-Type: application/json' 'http://isv/interface? signature=e3k9ierw&timestamp=1483944926&eventId=1780012140' --data '{"action":"modifyInstance","orderId":"20170109199524","accountId":"123545678" ,"productId":"7c652d37-e12b-4b4f-aa65-6432d03f12f3","requestId":"1d8326b2- 9a94-4bf3-91ce-c7a94add99d3","signId":"kjsadkjhdskjh3k","spec":" ⾼高级 版","timeSpan":2,"timeUnit":"m"," instanceExpireTime":"2017-02-09 19:59:59" }'

响应示例

{"success":"true"}

实例销毁通知接⼝

接⼝说明:实例到期后(⽤户最后操作后的 instanceExpireTime ),工业云云市场将通过实例销毁通知接⼝发送消息⾄发货 URL。

请求参数

参数名 类型 是 否 必 须 描述
action string 取值: "destroyInstance"
orderId string 如正常过期销毁,则不带有此参数,如退款销毁,则为客户退款的订单 ID
accountId string 购买者账号 ID
productId string 商品 ID
requestId string 接⼝请求的 ID
signId string 实例标识 ID。服务商提供的唯⼀标识。⻓度最⻓为11位

返回参数

参数名 类型 是 否 必 须 描述
success string 取值:"true"/"false"

请求示例

curl -X POST 'http://isv/interface? signature=e3k9ierw&timestamp=1483944926&eventId=1780012140' --data '{"action":"destroyInstance","orderId":"20170109199524","accountId":"123545678","productId":1024,"requestId":"80b75030-6571-46a8-87ef-5b414f66dc39","signId":"kjsadkjhdskjh3k"}'

响应示例

{"success":"true"}

⾃测免密登录接口

请求参数

参数名 类型 是 否 必 须 描述
id_token string IDaaS id_token,格式为jwt, jwt格式详见jwt介绍

具体详情见免密登陆URL校验部分。

免密登陆URL校验

免密地址用于服务提供商发货后,用户进行免密登陆的验证。认证个人或者企业用户购买应用后,登陆地址云控制台,在本地应用列表找到购买的实例,通过进入应用按钮,跳转至免密登陆地址,跳转后,浏览器进入免密地址,调用服务商提供的服务,服务提供商对请求进行校验,验证通过,给用户提供服务,返回内容,验证不通过,拒绝服务。

img

⽤户在购买SaaS实例后,使用时期望能够免密登录应用。否则随着购买应用数量的增加,⽤户要输⼊多次账号密码,将极大影响用户体验。此外,⽤户购买应⽤后还希望分享授权给同事,协作使用应用。为此,创建实例例通知时,⼯业云会附加IDaaS信息,服务商需要保存IDaaS信息,并如下所示实现IDaaS规定的免密登录接⼝。

调试过程:

img

id_token格式为jwt, jwt格式详⻅见jwt介绍。base64解码id_token的payload部分,⼯业云payload参数只⽤到jwt预定义的参数

参数名 类型 是 否 必 须 描述
aud string idaas applicationId
sub string idaas userId
iat integer id_token创建时间戳
exp integer id_token过期时间戳

服务商根据解出的applicationId,反查出实例创建阶段保存的idaas公钥:certificate。然后根据服务商的语⾔,选择合适的开源库验证id_token签名是否合法。开源库有php, java, c, c++, go等众多资源,点击前往jwt开源库。如果 id_token不合法,服务商应忽略请求防⽌攻击。

校验python示例:

import jwt
from cryptography import x509
from cryptography.hazmat.backends import default_backend from cryptography.hazmat.primitives import serialization
def verify_id_token(id_token, certificate):
cert = x509.load_pem_x509_certificate(certificate, default_backend()) public_key = cert.public_key()
public_key_bytes = public_key.public_bytes(serialization.Encoding.PEM,
serialization.PublicFormat.SubjectPublicKeyInfo)
decoded = jwt.decode(id_token, key = public_key_bytes, algorithms =
'RS256')

服务商根据payload里的applicationId,userId,为⽤户提供服务。

自助调试

(1)SP身份登录控制台

img

(2)点击新建平台应用-->Saas应用

img

(3)填写商品信息后,点击“下一步进入调试”

img

(4)配置发货URL、发货Token在本地应⽤创建⻚⾯

img

(5)自测创建实例接口

img

(6)自测实例过期接口

img

(7)自测实例配置变更

img

(8)自测实例销毁接口

img

(9)自测实例续费接口

img

(10)自测免密登录接口

img

(11) 提交接⼊

在创建本地应用⻚,调试都通过后,点击“提交创建”,服务商的发货URL、发货Token将在对应环境生效。 此时说明服务商已具备自动交付和免密登录能⼒,能够用此发货URL、Token对去上架商品了。

发货通知逻辑

认证个人或者企业用户登陆地市云-->应用市场门户页-->本地应用,选择对应SaaS类应用进行购买,购买完成后,工业云调用发货接口,通知服务商进行发货,服务商收到过期请求后按如下逻辑进行处理,返回发货信息给工业云,即可完成整个购买流程。

接口完整传参查看应用开发API部分,具体调用过程如下:

img

即服务商在实例创建阶段,需要:

(1) 将⼊参extendInfo中的applicationId,certificate保存下来,并与服务商⽣产的实例 id( signId )关联起来。

(2)可选:将⼊参extendInfo中的userId保存下来,并创建一个对应的服务商账号。

续费通知逻辑

认证个人或者企业用户登陆地市云应用市场控制台,对之前购买的应用进行续费操作,用户点击续费,进行续费操作,工业云调用续费接口,通知服务商进行续费,服务商收到过期请求后按如下逻辑进行处理,返回续费结果信息给工业云,即可完成整个续费流程。

img

过期通知逻辑

认证个人或者企业用户购买应用后,当实例有效截止时间到达时,未进行续费操作,工业云通知服务商进行过期操作,服务商收到过期请求后按如下逻辑进行处理,返回过期结果信息给工业云,即可完成整个过期流程。

img

配置变更通知逻辑

认证个人或者企业用户登陆地市云应用市场控制台,对之前购买的应用进行升级操作,用户点击升级,选择配置后,进行升级,工业云调用配置变更接口,通知服务商进行配置变更,服务商收到过期请求后按如下逻辑进行处理,返回配置变更结果信息给工业云,即可完成整个升级流程。

img

免密登陆URL校验

免密地址用于服务提供商发货后,用户进行免密登陆的验证。认证个人或者企业用户购买应用后,登陆地址云控制台,在本地应用列表找到购买的实例,通过进入应用按钮,跳转至免密登陆地址,跳转后,浏览器进入免密地址,调用服务商提供的服务,服务提供商对请求进行校验,验证通过,给用户提供服务,返回内容,验证不通过,拒绝服务。

img

⽤户在购买SaaS实例后,使用时期望能够免密登录应用。否则随着购买应用数量的增加,⽤户要输⼊多次账号密码,将极大影响用户体验。此外,⽤户购买应⽤后还希望分享授权给同事,协作使用应用。为此,创建实例例通知时,⼯业云会附加IDaaS信息,服务商需要保存IDaaS信息,并如下所示实现IDaaS规定的免密登录接⼝。

调试过程:

img

id_token格式为jwt, jwt格式详⻅见jwt介绍。base64解码id_token的payload部分,⼯业云payload参数只⽤到jwt预定义的参数

参数名 类型 是 否 必 须 描述
aud string idaas applicationId
sub string idaas userId
iat integer id_token创建时间戳
exp integer id_token过期时间戳

服务商根据解出的applicationId,反查出实例创建阶段保存的idaas公钥:certificate。然后根据服务商的语⾔,选择合适的开源库验证id_token签名是否合法。开源库有php, java, c, c++, go等众多资源,点击前往jwt开源库。如果 id_token不合法,服务商应忽略请求防⽌攻击。

校验python示例:

import jwt
from cryptography import x509
from cryptography.hazmat.backends import default_backend from cryptography.hazmat.primitives import serialization
def verify_id_token(id_token, certificate):
cert = x509.load_pem_x509_certificate(certificate, default_backend()) public_key = cert.public_key()
public_key_bytes = public_key.public_bytes(serialization.Encoding.PEM,
serialization.PublicFormat.SubjectPublicKeyInfo)
decoded = jwt.decode(id_token, key = public_key_bytes, algorithms =
'RS256')

服务商根据payload里的applicationId,userId,为⽤户提供服务。

腾讯云应用

地市云OIDC统一认证标准

注意:地市云在SSO免登和统一认证时,使用了千帆玉符的能力。相关的支持由千帆玉符侧同事来给予支持。

对接方式

合作方应用需通过 OpenID Connect(简称 OIDC)协议与千帆玉符进行认证接入。

OIDC 是基于 OAuth 2.0 的可互操作的身份验证协议,作为一个开放授权标准,它允许用户让第三方应用访问该用户在某服务的特定私有资源但是不提供账号密码信息给第三方应用。OIDC 是目前对开发者最友好的身份认证协议之一,让开发者可以很轻松地进行集成。

单点登录(SSO)

流程图

img

流程说明:

  1. 合作方应用将用户浏览器重定向到千帆玉符,携带客户端标识、回调 URI;
  2. 用户登陆千帆玉符进行身份认证与授权;
  3. 千帆玉符返回身份令牌ID Token,以及访问令牌Access Token;
  4. 合作方应用使用Access Token向千帆玉符请求用户信息;
  5. 千帆玉符返回此次登陆的用户信息。
对接步骤

步骤1:用户未登录状态下,合作方应用需要重定向到千帆玉符的authorize_uri进行身份认证,并携带参数如下:

https://xxxx-idp.cig.tencentcs.com/xxx/authorize?response_type=code&client_id=xxxx&redirect_uri=https://xxxx.client.com/callback&scope=openid%20offline_access&state=xxxx

其中相关参数的含义如下 :

参数名 示例 含义
response_type code 固定为此值,表示为请求返回内容
scope openid offline_access 多值属性,以空格分割。表示需要请求的用户信息范围,使用 openid offline_access 即可,中间有空格;
state xxxx 非必传,CSRF安全参数,合作方应用客户端随机生成一串字符串,千帆玉符认证完会原封不动返回此参数
redirect_uri https://xxxx.client.com/callback 详见名词介绍

步骤2:用户登陆千帆玉符,点击授权,允许合作方应用获取用户信息,千帆玉符会跳转到合作方应用的回调地址redirect_uri,携带授权码 code。code 是由千帆玉符生成的随机字符串,若第一步携带了 state,也会返回原始 state。

https://xxxx.client.com/callback?code=xxx&state=xxxx

步骤3:合作方应用的回调地址接收到 code 之后,需要调用千帆玉符的 token 接口获取 access_token。

千帆玉符会提供一个 token 接口供合作方应用调用,此处为服务端之间的调用,浏览器不可见:

POST  https://xxxx-idp.cig.tencentcs.com/xxx/token 

Content-Type:  application/x-www-form-urlencoded 
Authorization: Basic {Base64:[client_id:client_secret]}

grant_type=authorization_code&code={code}&redirect_uri=https://xxxx.client.com/callback

其中涉及的参数含义如下:

参数名 示例 传入方式 含义
Authorization Basic {Base64:[client_id:client_secret]} header 合作方应用需要使用 BasicAuth 的方式,传入 client_id 和 client_secret。 具体操作方式为,将 client_id 加上“:”再加上 client_secret 拼接成字符串,进行 Base64 编码得到一个新的字符串,并在这串字符串前加上 Basic,中间留一个空格,得到最终需要的字符串。
grant_type authorization_code form表单 固定为此值,表示为授权码模式
code xxxx form表单 使用之前千帆玉符生成的 code
redirect_uri https://xxxx.client.com/callback form表单 详见名词介绍

步骤4:千帆玉符接收到请求 Token 后,会验证 client_id、client_secret 以及 code、redirect_uri,验证成功之后会返回 JSON 格式的 token,如下所示:

HTTP/1.1  200 OK 
 Content-Type: application/json 

{
    "id_token": "xxxx",
    "access_token": "xxxxxxx",
    "refresh_token": "xxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 3600
}

其中:

参数名 示例 含义
id_token xxxx 用户身份 token,JWT格式,可以用jwk_uri接口获取的公钥解密
access_token xxxx 请求 token,用于请求详细用户信息。
refresh_token xxxx 刷新token,access_token过期后可用于刷新access_token
token_type Bearer 固定为 Bearer,后续请求用户信息时需要使用此种验证方式
expires_in 3600 表示 token 过期时间,单位:秒

步骤5:合作方应用使用 access_token 向千帆玉符的 userinfo_uri 接口请求身份信息。此处为服务端之间的调用,请求如下所示:

GET  https://xxxx-idp.cig.tencentcs.com/xxx/userinfo 

Content-Type:  application/json 
Authorization: Bearer {access_token}

其中:

参数名 示例 传入方式 含义
Authorization Bearer {access_token} header 合作方应用需要使用Bearer的方式,将上一步获取的 access_token,在其前面加上 Bearer 和一个空格,得到一个新的字符串。

步骤6:千帆玉符接收到 UserInfo 的请求后,验证 access_token 成功之后,返回信息如下,合作方应用根据此处返回的用户信息,登陆对应的账号:

HTTP/1.1  200 OK 
Content-Type: application/json 

{
    "sub": "zhangsan",
    "name": "张三",
    "email":"zhangsan@tencent.com",
    "phoneNumber":"12345678901"
}

其中:

参数名 示例 含义
sub zhangsan 用户唯一 ID,可以作为合作方应用用户名
name 张三 用户在千帆玉符的显示名称
email zhangsan@tencent.com 用户在千帆玉符的邮箱
phoneNumber 12345678901 用户在千帆玉符的手机号

步骤7:合作方应用 access_token 过期之后,可以使用 refresh_token 向千帆玉符请求刷新access_token。此处为服务端之间的调用,请求如下所示:

POST  https://xxxx-idp.cig.tencentcs.com/xxx/token 
Content-Type:  application/x-www-form-urlencoded 
Authorization: Basic {Base64:[client_id:client_secret]}

grant_type=refresh_token
refresh_token={refresh_token}

返回体与获取token的接口格式一致

HTTP/1.1  200 OK 
Content-Type: application/json 

{
    "access_token": "xxxxxxx",
    "refresh_token":"xxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 3600   
}

单点登出(SLO)【可选】

流程介绍
  1. 合作方应用登出时,需要清除自身的会话,并将用户浏览器重定向到千帆玉符的登出地址logout_uri。
  2. 千帆玉符完成自身会话的清理功能,跳转回合作方应用。
  3. 千帆玉符向所有其他集成了SLO功能的合作方应用发送登出请求。
  4. 合作方应用接收到千帆玉符的登出请求时,将自身会话清除。

注意

1. 合作方应用自身需要实现界面点击登出功能,并重定向到千帆玉符。 
2. 合作方应用需要具备后台登出用户的能力,接收千帆玉符发送的登出请求,注意与界面登出功能区分开。 
3. 在下文的讨论中,根据登出行为的发起者不同,将这两种登出行为分为“由合作方应用发起的登出”和“由千帆玉符发起的登出”。合作方应用开发者需要区分这二者的区别。
由合作方应用发起的登出

步骤1:当用户在合作方应用的页面点击登出时,需要跳转到玉符logout_uri,如下所示:

https://xxxx-idp.cig.tencentcs.com/logout?return_to=https://xxx.client.com/logout

其中涉及的参数含义如下:

参数名 示例 含义
returnTo https://xxx.client.com/logout 合作方应用希望千帆玉符清除自身会话之后,跳转的地址,由合作方应用具体业务逻辑决定

步骤2:千帆玉符清除自身会话后,会跳转到合作方应用指定的跳转地址

https://xxx.client.com/logout
由千帆玉符发起的登出

步骤1:当千帆玉符登出后,会向实现了SLO功能的合作方应用发起如下请求,此请求为服务端间调用,浏览器不可见。

POST https://xxx.client.com/backchannel_logout HTTP/1.1
  Content-Type: application/x-www-form-urlencoded

  logout_token=eyJhbGci ... .eyJpc3Mi ... .T3BlbklE ...

其中涉及的参数含义如下:

参数名 示例 含义
logout_token eyJhbGci ... .eyJpc3Mi ... .T3BlbklE ... JWT格式,可以用jwk_uri接口获取的公钥解密

将token解密之后,其格式如下:

{
  "iss": "https://server.example.com",
  "sub": "sanzhang@demo.com",
  "sid": "xxx",
  "aud": "ai-xxx",
  "iat": 1577808000,
  "exp": 1577808600,
  "jti": "bWJq"
}

其中涉及的参数含义如下:

参数名 示例 含义
iss https://server.example.com 登出请求的签发者
sub sanzhang@demo.com 需要登出的用户名,sub和sid不会同时为空
sid xxx 需要登出的Session ID。同一个用户在不同浏览器使用千帆玉符登陆时,千帆玉符会提供不同的Session ID,当sub为空且sid不为空时,表示仅登出此会话ID。
aud ai-xxx 千帆玉符认证源对应的appInstance ID
iat 1577808000 请求签发的时间,Unix时间戳,单位秒
exp 1577808600 请求过期的时间,Unix时间戳,单位秒
jti bWJq 随机字符,可作为此次请求的唯一ID