AssumeRoleWithSAML - 基于SAML进行角色扮演--访问控制-火山引擎

文档中心

导航

AssumeRoleWithSAML - 基于SAML进行角色扮演

最近更新时间：2025.06.30 20:45:10首次发布时间：2025.06.30 20:39:41

通过 SAML 协议扮演 IAM 角色。

请求说明

该接口请求无需进行签名，建议使用 POST 方法调用，请求头 Content-Type 设置为 application/x-www-form-urlencoded，参数通过 URL 编码后以表单形式提交在请求体中。

请求地址：https://sts.volcengineapi.com

限流：每个账号200/s

请求参数

参数	类型	是否必填	示例值	描述
RoleTrn	String	是	trn:iam::2000012345:role/my_role	需要扮演的角色Trn，格式为`trn:iam::${AccountId}:role/${RoleName}`。其中`${AccountId}`需要填入角色所属的主账号ID，`${RoleName}`需要填入实际的角色名称。例如账号ID为2000012345的账号内角色名为myRole的角色对应的RoleTrn为`trn:iam::2000012345:role/myRole`
SAMLProviderTRN	String	是	trn:iam::2000000001:saml-provider/my_idp	SAML 外部身份提供商 TRN。格式为`trn:iam::${AccountId}:saml-provider/${ProviderName}`
SAMLResp	String	是	base64_encoded_saml_assertion	Base64 编码后的 SAML 断言。
Policy	String	否	{"Statement":[{"Effect":"Allow","Action":["iam:GetUser"],"Resource":["*"]}]}	角色内联策略，用于进一步限制临时凭证的权限。长度不超过2048字符。如果内联权限策略不为空，则临时凭证的实际权限为所扮演角色的权限策略与内联权限策略的交集。策略语法格式同普通的IAM策略，可参考策略语法介绍。
DurationSeconds	Integer	否	3600	临时密钥有效时长（单位：秒），最短可设为900秒，最长可设为角色最大会话时长值（在角色信息中配置），默认值为3600秒。

返回参数

参数	类型	示例值	描述
SAMLAssertionInfo	Object	请参考数据结构内具体参数示例值。	SAML 断言中的部分信息。
AssumedRoleUser	Object	请参考数据结构内具体参数示例值。	角色扮演的基本信息。
Credentials	Object	请参考数据结构内具体参数示例值。	角色扮演产生的临时安全凭证。

请求示例

POST /?Action=AssumeRoleWithSAML&Version=2018-01-01 HTTP/1.1
Host: sts.volcengineapi.com
Content-Type: application/x-www-form-urlencoded
User-Agent: curl/7.64.1

RoleTrn%3Dtrn%3Aiam%3A%3A2000012345%3Arole%2Fmy_role%26SAMLProviderTrn%3Dtrn%3Aiam%3A%3A2000000001%3Asaml-provider%2Fmy_idp%26SAMLResp%3DeIv934JD

返回示例

{
  "ResponseMetadata": {
    "RequestId": "2025063019011211816709818655381C",
    "Action": "AssumeRoleWithSAML",
    "Version": "2018-01-01",
    "Service": "sts",
    "Region": "cn-beijing"
  },
  "Result": {
    "SAMLAssertionInfo": {
      "SubjectType": "xThA",
      "Subject": "LUYDlf7g",
      "Issuer": "TRL",
      "Recipient": "M2"
    },
    "AssumedRoleUser": {
      "Trn": "trn:sts::2000000001:assumed-role/AdminRole/bob",
      "AssumedRoleId": "2*********:bob"
    },
    "Credentials": {
      "CurrentTime": "2021-04-12T10:57:09+08:00",
      "Expiration": "2021-04-12T11:57:09+08:00",
      "AccessKeyId": "AKTPODg0MzV**2ZDcxMDg",
      "SecretAccessKey": "TVRNN*********************Q==",
      "SessionToken": "IYfYjE0"
    }
  }
}

错误码

状态码	错误码	错误信息	说明
400	SAMLRespSignNotMatch	The SAML response signature does not match.	SAML Response 中的签名无效。
400	MalformedSAMLRespDoc	The SAML response document is malformed.	SAML Response 格式无效。
400	InvalidIssueInstant	The SAML response issue instant is too old or in the future.	SAML Response 中的 Issue Instant 无效。
400	InvalidSessionName	The SAML session name is invalid.	SAML Response 中的 Session Name 属性无效。
400	InvalidSAMLAssertion	The SAML assertion is invalid.	SAML Response 的 Assertion 无效。
400	RoleNotExist	Role '{{.Role}}' does not exist.	角色不存在。
403	SigningCertDateInvalid	This SAML signing certificate is not yet valid or has expired.	SAML 签名证书已过期或尚未生效。
403	NoPermission	This SAML Response cannot be exchanged for temporary credentials for the target identity TRN.	SAML Response 中的目标身份与参数不匹配。