You need to enable JavaScript to run this app.
导航
旧版本SAMLResponse参数配置说明
最近更新时间:2023.10.26 16:04:30首次发布时间:2022.12.14 15:28:09

说明

为了提供更好的服务,火山引擎进行了SAML SSO的升级改版。如您在2023-08-17前已经接入火山引擎的SAML SSO,您可以继续使用IAM控制台上提供的旧版本SP元数据,并通过原身份提供商完成SSO登录,不需进行任何改动。
如您是2023-08-17之后准备接入SAML SSO的客户,请您参考用户SSO概述角色SSO概述进行新版本的配置,火山引擎已为您全面升级SAML SSO服务。
此文档继续为您提供旧版本的SAML相应配置示例。更多问题,请提工单联系我们。

旧版本SAMLResponse示例

按照SAML 2.0协议标准,需要IDP侧发送到火山引擎进行解析的SAML Response示例如下:

<samlp:Response IssueInstant="2022-01-01T00:00:00.000Z">
    <saml:Issuer>...</saml:Issuer>
    <ds:Signature>
        ...
    </ds:Signature>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"></samlp:StatusCode>
    </samlp:Status>
    <saml:Assertion>
        <saml:Issuer>...</saml:Issuer>
        <ds:Signature>
            ...
        </ds:Signature>
        <saml:Subject>
            <saml:NameID>${NameID}</saml:NameID>
            <saml:SubjectConfirmation>
                <saml:SubjectConfirmationData NotOnOrAfter="2022-01-01T00:00:00.000Z" Recipient="${Recipient}"></saml:SubjectConfirmationData>
            </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions>
            <saml:AudienceRestriction>
                <saml:Audience>{$Audience}</saml:Audience>
            </saml:AudienceRestriction>
        </saml:Conditions>
        <saml:AuthnStatement>
            ...
        </saml:AuthnStatement>
        <saml:AttributeStatement>
            <saml:Attribute Name="https://www.volcengine.com/SAML/Attributes/Identity">
                <saml:AttributeValue>trn:iam::${AccountID}:role/${RoleName},trn:iam::${AccountID}:saml-provider/${SAMLProviderName}</saml:AttributeValue>
                <saml:AttributeValue>trn:iam::${AccountID}:user/${UserName},trn:iam::${AccountID}:saml-provider/${SAMLProviderName}</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="https://www.volcengine.com/SAML/Attributes/SessionName">
                <saml:AttributeValue>${SessionName}</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="https://www.volcengine.com/SAML/Attributes/SessionDuration">
                <saml:AttributeValue>${SessionDuration}</saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>

SAMLResponse中的字段说明

火山引擎对SAMLResponse字段要求详细如下(在主流IdP处必须完成的基本配置项加粗展示):

字段说明
IssueInstantSAMLResponse生成的UTC时间
IssuerIssuer的值需要与火山引擎的IDP Metadata中的EntityID一致

Signature

出于安全目的,必须在SAMLResponse进行签名,在SP侧进行验签。Signature中必须包含签名值、签名算法等信息。
请注意,目前对于X509证书的签名支持sha1、sha256、sha512三种算法,请确保SAML Response使用上述算法之一进行加签。

Subject

  • NameID字段。NameID字段可以作为指定登录用户身份的一种方式,如果使用该字段进行SSO身份映射,则支持且仅支持一个火山引擎账号下的一个IAM用户身份,此时NameID字段中需要包含的格式为:{$UserName}@{$AccountID}。其中{$UserName}是火山引擎IAM用户名,{$AccountID}是火山引擎账号ID。
  • SubjectConfirmationData字段。断言中必须包含一个该字段。
    • 该字段的NotOnOrAfter属性用于指定断言有效期,UTC时间。
    • 该字段的Recipient属性用于指定断言接收方,取值必须为:https://signin.volcengine.com/saml/sso
Audience该字段用于指定断言受众,必须包含一个固定的值:https://signin.volcengine.com/saml/sso

AttributeStatement

SAML断言中必须包含一些自定义属性用于向火山引擎传递要进行SSO登录的身份、会话名,会话时长等信息。自定义属性配置时需要配置属性名称和属性值,如下:

  • 身份属性。该属性可以作为指定登录用户身份的一种方式,用于向火山引擎传递当前登陆用户允许登陆的火山引擎身份集合,如果选择该方式进行SSO身份映射,则必须至少包含一个该属性。
    • 属性的名称为固定值:https://www.volcengine.com/SAML/Attributes/Identity
    • 属性的值用于声明允许登陆的火山引擎身份,至少包含一个属性值,可包含多个属性值。允许登陆的身份根据SSO的场景不同(用户SSO/角色SSO)而不同其中:
      • 角色SSO的格式为trn:iam::${AccountID}:role/${RoleName},trn:iam::${AccountID}:saml-provider/${SAMLProviderName}。
      • 用户SSO的格式为trn:iam::${AccountID}:user/${UserName},trn:iam::${AccountID}:saml-provider/${SAMLProviderName}。
          其中AccountID为您的火山引擎账号ID,RoleName为IAM角色名称,UserName为IAM用户名称,SAMLProviderName为身份提供商名称。
  • 会话名称属性。必须包含一个该属性。
    • 属性的Name为固定值https://www.volcengine.com/SAML/Attributes/SessionName
    • 属性的值用于指定会话名称。必须包含一个属性值,仅用作展示和审计记录。(请注意,在roleSSO中,将使用“账号名称-SessionName”用作当前登录的角色的展示名。)
  • 会话时长属性。可选包含该属性,且至多包含一个。
    • 属性的Name为固定值https://www.volcengine.com/SAML/Attributes/SessionDuration

    • 属性的值用于指定角色登录态时长。如不传递该属性,则默认角色的最大登录时长为3600秒。如传递该属性,则必须包含一个属性值,属性值需要在900-43200秒之间,用于指定角色的登录态时长。

AttributeStatement元素的示例:

<saml:AttributeStatement>
   <saml:Attribute Name="https://www.volcengine.com/SAML/Attributes/Identity" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">trn:iam::${AccountID}:user/user1,trn:iam::${AccountID}:saml-provider/onelogin</saml:AttributeValue>
   </saml:Attribute>
   <saml:Attribute Name="https://www.volcengine.com/SAML/Attributes/SessionName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">sessionNameForRole</saml:AttributeValue>
   </saml:Attribute>
   <saml:Attribute Name="https://www.volcengine.com/SAML/Attributes/SessionDuration" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">7200</saml:AttributeValue>
   </saml:Attribute>
  </saml:AttributeStatement>

SAMLResponse中的身份映射规则

请注意,火山引擎支持两个方式进行SSO身份映射,两个方式有不同优先级:

  1. 火山引擎推荐使用AttributeStatement中的身份属性进行身份映射。
    a. 使用该方式,支持配置多条身份属性,即支持一个IDP身份SSO到多个火山引擎账号上的多个身份(用户/角色),且同时支持角色SSO和用户SSO;
    b. 使用该方式,则对IDP侧的用户字段无要求,火山引擎也不会读取您的IDP中任何的用户信息。

  2. 火山引擎同时支持使用NameID进行身份映射。
    a. 使用该方式,仅支持用户SSO,即只能登录到火山引擎的IAM用户上。同时一个IDP身份仅支持登录到一个火山引擎账号上的一个IAM用户上;
    b. 使用该方式,适用于“通过IDP的用户名等字段匹配IAM用户名的字段来完成身份映射”的场景,则对IDP的字段有要求,需要保证用于映射到IAM用户名的IDP字段在IDP唯一且不随会话改变。

请注意

  1. 若同时配置了有效的AttributeStatement中的身份属性,则优先解析该数据,忽略NameID的解析。