API令牌（STS）¶

最后更新：2021-12-02

1. 概述¶

本文档主要覆盖一个API应用，如何通过单点登录协议OAuth, OIDC等，从IDP到这个应用的安全令牌操作。
注：多数情况下标准的OAuth 协议等足够，如果是希望提供一个IDP的应用模版JAR, 不在本文档讨论范围内，请参考【应用模版】插件开发。
为了将众多的API数据源快速安全整合起来，客户可以通过我们的 STS（Security Token Service，安全令牌服务）服务， API令牌STS是使用 OIDC协议 实现的API认证与授权解决方案，它将API认证授权集成到我们的IDP平台，生成密钥对后，即可快速导出公钥，更可以设定不同的认证方式，让移动及API应用的认证与授权更安全。

OIDC协议：OIDC协议是基于OAuth2.0授权协议基础上的由Google，微软，Facebook等公司于2014年发布的最新的认证授权协议，具有更高的安全性，灵活性，并符合未来安全发展的趋势。在该协议中，使用令牌id_token替换 OAuth2的access_token，id_token生成时使用私钥进行签名，使用时用公钥进行校验。使用JSON数据格式进行传输，并支持各类加密算法（如RSA）。

立刻获得基于token的身份校验方式，让自己的应用拥有和我们一样的身份安全等级。拥抱安全，告别长期不变的密码，或是固定设备ID等容易被捕获重放的认证方式。

2. 实现原理¶

STS服务要求开发的应用端和服务器端做出相应的修改。应用端(Web)不再直接向服务器端发送认证请求或索取资源，而是先往IDP的认证服务器（AS, Authentication Server）发送账号验证请求，IDaaS在向你的服务器验证成功后，会返回一个id_token作为身份令牌。向服务器（RS，Resource Server）发出请求的时候，就需要携带这个令牌以验证身份。

2.1. 获取 id_token¶

IDP的认证平台负责id_token的分发

步骤分解：

应用携带appKey,appSecret使用API向IDP发出id_token申请
IDP校验信息返回id_token

2.2. 使用 id_token¶

开发者需要对服务器需要被id_token保护起来的接口添加一个过滤器（filter）。只有通过了该过滤器验证的才可以访问。具体服务器端实现流程如下：

获取keyID：每次应用请求的时候会携带id_token，服务器的过滤器取得id_token。
解密验证：使用公钥进行解密，如果成功的话，那么认证即成功，请求可以通过。

步骤分解：

开发的应用向应用服务器请求资源，携带从IDP认证服务器获取到的id_token。
应用服务器使用公钥id_token进行解密，在验证后通过过滤器，继续放行想要请求的资源，并返回给应用。

2.3. 刷新 id_token¶

如果添加的API令牌已经启用了Refresh Token功能，当id_token过期的时候，可以通过refresh_token去刷新换取一个新的id_token。
如果没有启用Refresh Token功能，那么过期后需要按照获取id_token的方式重新用身份认证信息去IDP获取。

步骤分解：

应用携带refresh_token向IDP进行刷新id_token请求
IDP返回新的id_token给应用

3. 申请 STS 应用¶

STS标准应用目前只能由 IT 管理员在应用添加菜单中添加。下面是 IT 管理员的应用添加流程。如果希望使用 STS应用，可以请管理员进行协助添加和配置。

以IT管理员身份登录 IDaaS ，点击添加应用,找到 JWT STS(附网关保护)，点击添加应用

如未找到 JWT STS(附网关保护) ,请联系IDaaS项目交付团队提供插件集成

填写应用信息。如下图（填写内容的解说在图片下方）：

表单字段名称	说明
应用名称	代表改业务系统的名称
ID Token有效期	ID Token有效期，单位: 秒，默认7200(2小时)
Refresh Token有效期	Refresh Token有效期, 单位: 天, 默认30
启用Refresh Token	是否启用Refresh Token有效期

保存应用，查看应用详情获取参数信息

应用状态需为启用状态
点击详细查看添加的STS应用的详细信息。如下图：

4. API¶

文档中的“IDaaS-Base-URL”需要替换为当前访问地址的主域，文中接口地址前也都需要替换主域地址；接口地址中的版本号以当前使用系统版本为准，也可以查看开发者文档中右侧菜单顶部的接口版本。

我们为开发者提供了服务器端对id_token进行解码校验的演示代码，可以在底部的相关下载中下载。
applicationUuid为应用详情中应用的uuid

4.1. 获取id_token¶

应用端使用，用于从IDP认证服务器获取 OIDC 的 id_token。

Request URI： POST /api/public/bff/v1.2/application/plugin_jwt_sts/retrieve_id_token/{applicationUuid}
Content-Type: application/json

请求参数：

参数名	类型	备注
appKey	String	应用中的 appKey
appSecret	String	应用中的 appSecret

请求Body示例：

{ 
  "appKey":"a26abc61154e62cbe800e497c7556021EddePLV2SkZ",
  "appSecret":"6RFBJh7RWfQZBwnTCBYUNYB4j2csUGzft4go17DMz6"
}

响应：

参数名	类型	备注
success	boolean	调用是否成功（true为成功否则为失败）
code	String	200为成功，其他为失败
message	String	若失败会返回失败原因
id_token	String	返回的IDToken，提供给第三方客户端使用
refresh_token	String	用户刷新IDToken,若应用不启用RefreshToken则不返回此字段

{
    "success": true,
    "code": "200",
    "message": null,
    "data": {
        "refresh_token": "xxxxxxxxx",
        "id_token": "xxxxxxxx"
    }
}

4.2. 刷新id_token¶

应用端使用，用于从IDP通过refresh_token获取id_token

请求URI： POST /api/public/bff/v1.2/application/plugin_jwt_sts/refresh_id_token/{applicationUuid}
Content-Type: application/json

请求参数：

参数名	类型	备注
appKey	String	应用中的 appKey
refresh_token	String	获取IDToken时返回

请求Body示例：

{
  "appKey":"a26abc61154e62cbe800e497c7556021EddePLV2SkZ",
  "refresh_token":"xxxxxxxxxxxxx"
}

响应：

{
    "success": true,
    "code": "200",
    "message": null,
    "data": {
        "id_token": "xxxxxxxxxxxxxxxxxx"
    }
}

4.3. 校验id_token¶

使用应用详情内的公钥(Publickey)对id_token进行校验
具体代码示例可参考【单点登录SSO】中【插件式SSO（JWT）】中的解析令牌模块

返回上级