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
IDaaS发出id_token申请,认证信息可以使用户名+密码,也可以是证书。
IDaaS如果可以自行校验,直接根据情况返回校验结果以及id_token。如果不能自行校验,会将信息传递到应用服务器开发的接口,请求应用服务器对认证信息进行验证。
应用服务器验证完认证信息返回结果。
IDaaS从应用服务器接收到验证成功或失败的结果,并根据情况返回id_token给应用。
如果在创建STS应用的时候启用了Refresh Token,那么在最后一步从IDaaS认证服务器还会返回一个refresh_token给应用。应用可以将其存储起来,用来进行id_token过期并需要刷新的请求。
使用id_token
开发者需要对服务器需要被id_token保护起来的接口添加一个过滤器(filter)。只有通过了该过滤器验证的才可以访问。具体服务器端实现流程如下:
获取keyID:每次应用请求的时候会携带id_token,服务器的过滤器需要对其进行初步解析并获得keyID。
获取publicKey:keyID是密钥的全局唯一标识,我们需要使用这个keyID对应的公钥,来对id_token进行解密。如果这个keyID对应的公钥在应用服务器上有保存的话,无须再次申请直接使用。没有存储记录的话,那么需要用携带该keyID向IDaaS认证服务器请求得到公钥publicKey,并安全地保存到本地。
解密验证:使用公钥进行解密,如果成功的话,那么认证即成功,请求可以通过。
步骤分解:
开发的应用向应用服务器请求资源,携带从IDaaS认证服务器获取到的id_token。
应用服务器对id_token进行解析获得keyID,如果应用服务器本地没有与keyID对应的公钥,那么向IDaaS认证服务器请求。
应用服务器得到公钥。
应用服务器对id_token进行解密,在验证后通过过滤器,继续放行想要请求的资源,并返回给应用。
刷新id_token
如果添加的API令牌已经启用了Refresh Token功能,当id_token过期的时候,可以通过refresh_token去刷新换取一个新的id_token。
如果没有启用Refresh Token功能,那么过期后需要按照获取id_token的方式重新用身份认证信息去IDaaS获取。
步骤分解:
应用携带refresh_token向IDaaS进行刷新id_token请求
IDaaS返回新的id_token给应用
申请STS应用
在开发之前,我们需要先申请一个STS应用,对应我们要开发的STS功能。
添加STS应用只能使用开发者角色进行创建,访问开发者。
在开发者的后台管理系统中,选择左侧的列表中选择API令牌(STS),选择添加API令牌(STS)。如下图:
填写STS应用信息。如下图:
表单字段名称
说明
应用ID
默认生成的,应用的唯一标识
OIDC KeyId
默认生成的唯一标识,在服务器端向IDaaS认证服务器请求获取公钥的时候会使用到
应用名称
选择要添加的应用
ID Token有效期
ID Token有效期,单位: 秒,默认7200(2小时)
Refresh Token有效期
Refresh Token有效期, 单位: 天, 默认30
启用Refresh Token
是否启用Refresh Token有效期
可授权范围
接口可获取的参数
备注信息
可选项,可以备注应用的相关信息
添加应用完成后,在操作中选择启用,确定后即可集成使用STS服务。如下图:
点击详细查看添加的STS应用的详细信息。如下图:
API
文档中的“IDaaS-Base-URL”需要替换为当前访问地址的主域,文中接口地址前也都需要替换主域地址;接口地址中的版本号以当前使用系统版本为准,也可以查看开发者文档中右侧菜单顶部的接口版本。
获取id_token
应用端使用,用于从IDaaS认证服务器获取 OIDC 的 id_token。
Request URI: /api/public/bff/v1.2/sts/retrieve_id_token
POST
REST
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
请求参数:
参数名 | 参数值 | 备注 |
---|---|---|
keyId | {keyId} | API应用的 keyId |
请求示例:
http://sz.idp-local.com/api/public/sts/public_key_d037e0cbf59042d09ed4609127a37ff5pbb8c5dwEn8
响应:
{"statusCode":0,"errors":[],"publicKey":"eyJrdHkiOiJSNjd2NE5ZbtZDRBbzRZaUVFBUTMtRGdTaVB0ekdtRkZ...","successful":true}
提示: 返回的publicKey是Base64 Encoded,使用时需要先调用Base64 Decoded。
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有效期。
在文档使用中是否遇到以下问题
更多建议
匿名提交