API令牌（STS）

API令牌（STS）概述 v1.2

为了将众多的API数据源快速安全整合起来，客户可以通过我们的STS（SecurityToken Service，安全令牌服务）服务， API令牌STS是使用OIDC协议实现的API认证与授权解决方案，它将API认证授权集成到我们的IDaaS平台，生成密钥对后，即可快速导出公钥，更可以设定不同的认证方式，让移动及API应用的认证与授权更安全。

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

实现原理

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

获取id_token

IDaaS的认证平台负责id_token的分发，需要进行认证的账号已经在IDaaS平台的情况下，也可以对用户的身份进行自己认证；如果IDaaS没有用户信息，不能自己进行认证，则需要传递到开发者的应用服务器，由应用服务器进行身份认证，并返回结果给IDaaS。具体流程如下图：

步骤分解：应用携带账号认证信息向IP

1. IDaaS发出id_token申请，认证信息可以使用户名+密码，也可以是证书。

2. IDaaS如果可以自行校验，直接根据情况返回校验结果以及id_token。如果不能自行校验，会将信息传递到应用服务器开发的接口，请求应用服务器对认证信息进行验证。

3. 应用服务器验证完认证信息返回结果。

4. IDaaS从应用服务器接收到验证成功或失败的结果，并根据情况返回id_token给应用。

使用id_token

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

1. 获取keyID：每次应用请求的时候会携带id_token，服务器的过滤器需要对其进行初步解析并获得keyID。

2. 获取publicKey：keyID是密钥的全局唯一标识，我们需要使用这个keyID对应的公钥，来对id_token进行解密。如果这个keyID对应的公钥在应用服务器上有保存的话，无须再次申请直接使用。没有存储记录的话，那么需要用携带该keyID向IDaaS认证服务器请求得到公钥publicKey，并安全地保存到本地。

3. 解密验证：使用公钥进行解密，如果成功的话，那么认证即成功，请求可以通过。

步骤分解：

1. 开发的应用向应用服务器请求资源，携带从IDaaS认证服务器获取到的id_token。

2. 应用服务器对id_token进行解析获得keyID，如果应用服务器本地没有与keyID对应的公钥，那么向IDaaS认证服务器请求。

3. 应用服务器得到公钥。

4. 应用服务器对id_token进行解密，在验证后通过过滤器，继续放行想要请求的资源，并返回给应用。

刷新id_token

如果添加的API令牌已经启用了Refresh Token功能，当id_token过期的时候，可以通过refresh_token去刷新换取一个新的id_token。

如果没有启用Refresh Token功能，那么过期后需要按照获取id_token的方式重新用身份认证信息去IDaaS获取。

步骤分解：

1. 应用携带refresh_token向IDaaS进行刷新id_token请求

2. IDaaS返回新的id_token给应用

申请STS应用

在开发之前，我们需要先申请一个STS应用，对应我们要开发的STS功能。

添加STS应用只能使用开发者角色进行创建，访问开发者。

1. 在开发者的后台管理系统中，选择左侧的列表中选择API令牌（STS），选择添加API令牌（STS）。如下图：

   

2. 填写STS应用信息。如下图：

   

   表单字段名称	说明
   应用ID	默认生成的，应用的唯一标识
   OIDC KeyId	默认生成的唯一标识，在服务器端向IDaaS认证服务器请求获取公钥的时候会使用到
   应用名称	选择要添加的应用
   ID Token有效期	ID Token有效期，单位: 秒，默认7200(2小时)
   Refresh Token有效期	Refresh Token有效期, 单位: 天, 默认30
   启用Refresh Token	是否启用Refresh Token有效期
   可授权范围	接口可获取的参数
   备注信息	可选项，可以备注应用的相关信息

3. 添加应用完成后，在操作中选择启用，确定后即可集成使用STS服务。如下图：

   

4. 点击详细查看添加的STS应用的详细信息。如下图：

   

API

• 获取id_token

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

  Request URI: /api/public/bff/v1.2/sts/retrieve_id_token POSTREST

  Content-Type:application/json

  请求参数：

  参数名	参数值	备注
  appKey	{appKey}	STS应用中的 appKey
  appSecret	{appSecret}	STS应用中的 appSecret
  username	{username}	IDaaS账户名
  password	{password}	IDaaS账户密码

  响应示例：

  {"statusCode":0,"errors":[],"id_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjY2...","refresh_token":"Z0zGd07UFFcAL6AgOYGn...","successful": true}

  statusCode为0表示成功，HTTP响应码为401(Unauthorized)则表示失败，具体为:400表示请求参数错误，483表示系统未找到refresh_token数据，484表示refresh_token已过期，501表示账户名错误，479表示应用不再支持 refresh_token 操作。

• 通过refresh_token刷新id_token

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

  Request URI: /api/public/bff/v1.2/sts/refresh_id_token POST

  Content-Type: application/json

  请求参数：

  参数名	参数值	备注
  username	{username}	IDaaS账户名
  refresh_token	{refresh_token}	获取id_token时返回的refresh_token

  请求Body示例：

  {"username":"zhangsan","refresh_token":"dK4ljtYf9TWTQX7Mgwi39Ol9p5H4md88kcgnL5nl2cChNdAn14mGNelA8CRLgHJK"}

  响应：

  {"statusCode":0,"errors":[],"id_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjY2...","refresh_token":"Z0zGd07UFFcAL6AgOYGn...","successful": true}

  statusCode为0表示成功，HTTP响应码为401(Unauthorized)则表示失败，具体为:400表示请求参数错误，483表示系统未找到refresh_token数据，484表示refresh_token已过期，501表示账户名错误，479表示应用不再支持 refresh_token 操作。

• 通过keyId获取OIDC Public Key

应用服务器端使用，用于从IDaaS通过keyId获取OIDC Public Key公钥。

Request URI: /api/public/bff/v1.2/sts/public_key_{keyId} GET

请求参数：

请求示例：

http://sz.idp-local.com/api/public/sts/public_key_d037e0cbf59042d09ed4609127a37ff5pbb8c5dwEn8

响应：

{"statusCode":0,"errors":[],"publicKey":"eyJrdHkiOiJSNjd2NE5ZbtZDRBbzRZaUVFBUTMtRGdTaVB0ekdtRkZ...","successful":true}

statusCode为0表示成功，HTTP响应码为401(Unauthorized)则表示失败，具体为: 233表示未找到对应的keyId，482表示应用尚未启用。

常见问题

1. 场景：登录时，通过IDaaS接口进行验证流程

使用STS安全令牌的获取id_token的接口，用户在应用页面输入完信息后， sp转发请求给IDaaS做验证，IDaaS正常返回id_token代表验证用户成功 。接口：/api/public/bff/v1.2/sts/retrieve_id_token

2. 场景：应用是前后端分离，使用IDaaS接口做认证后，前端和后端交互流程

如移动端APP 需要访问SP的rest资源，可以集成STS令牌进行接口保护。 当用户在APP中输入账户和密码后，APP调用IDaaS接口获取id_token, APP携带id_token向SP发送请求， SP需要先通过在STS应用上复制的keyId获取public_key, 并使用public_key 校验APP请求中带的id_token，id_token校验通过，则认证通过。public_key校验的demo需要到开发者中下载

SP验证APP身份后，后续APP 向SP发送请求，使用什么凭据：方案1： 仍然使用id_token，每次请求带上id_token向SP发送请求。因为id_token有时效性， 过期可以通过refresh_token获取新的id_token。方案2： 使用SP自己生成的token，app获取SP颁发的新token进行访问，灵活控制有效性。

3. 下载解析token的demo

开发者访问方式：https://help.aliyun.com/document_detail/147490.html

下载解析token的demo

4. 当使用接口refresh_id_token刷新id token后，为什么生成的refresh token还是原来的

当刷新id token后，新生成的id token重新开始计算有效期，但是refresh token在有效期内是不变的，可以多次用于刷新id token。

可以在STS应用详情中查看refresh token有效期。