通过

单一登录 SAML 协议

本文介绍 SAML 2.0 身份验证请求和响应，Microsoft Entra ID 支持单一登录 （SSO）。

以下协议关系图描述了单一登录序列。 云服务（服务提供商）使用 HTTP 重定向绑定将（身份验证请求）元素传递给 AuthnRequest Microsoft Entra ID（标识提供者）。 Microsoft Entra ID 然后使用 HTTP post 绑定将元素发布到 Response 云服务。

单个 Sign-On（SSO）工作流的屏幕截图。

注释

本文讨论如何使用 SAML 进行单一登录。 有关处理单一登录的其他方法的详细信息（例如，使用 OpenID Connect 或集成 Windows 身份验证），请参阅 Microsoft Entra ID 中的应用程序单一登录。

AuthnRequest

若要请求用户身份验证，云服务将元素 AuthnRequest 发送到 Microsoft Entra ID。 示例 SAML 2.0 AuthnRequest 如以下示例所示：

<samlp:AuthnRequest
  xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
  ID="C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w"
  Version="2.0" IssueInstant="2013-03-18T03:28:54.1839884Z"
  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
  <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://www.contoso.com</Issuer>
</samlp:AuthnRequest>
参数 类型 Description
ID 必选 Microsoft Entra ID 使用此属性填充 InResponseTo 返回的响应的属性。 ID 的开头不能是数字，因此常见的策略是在 GUID 的字符串表示形式前面加上类似于“ID”的字符串。 例如， id6c1c178c166d486687be4aaf5e482730 是有效的 ID。
Version 必选 此参数应设置为 2.0.
IssueInstant 必选 这是具有 UTC 值和 往返格式（“o”）的 DateTime 字符串。 Microsoft Entra ID 需要此类型的 DateTime 值，但不计算或使用该值。
AssertionConsumerServiceURL 可选 如果提供此参数，则此参数必须与 Microsoft Entra ID 中的云服务匹配 RedirectUri 。 如果条目 ID 存在于 SAML 请求中，则会遵循 ACS URL。
ForceAuthn 可选 这是一个布尔值。 如果为 true，则表示用户将强制重新进行身份验证，即使用户具有具有Microsoft Entra ID 的有效会话也是如此。
IsPassive 可选 这是一个布尔值，该值指定Microsoft Entra ID 是否应在无提示的情况下使用会话 Cookie（如果存在）以无提示方式对用户进行身份验证。 如果为 true，Microsoft Entra ID 会尝试使用会话 Cookie 对用户进行身份验证。

所有其他AuthnRequest属性（例如Consent，Destination）将被ProviderName忽略。

Microsoft Entra ID 中也会忽略元素ConditionsAuthnRequest。

发行人

元素IssuerAuthnRequest必须与Microsoft Entra ID 中的云服务中的 ServicePrincipalNames 完全匹配。 通常，这设置为在应用程序注册期间指定的 应用 ID URI 。

包含元素的 Issuer SAML 摘录如以下示例所示：

<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://www.contoso.com</Issuer>

NameIDPolicy

此元素在响应中请求特定的名称 ID 格式，在发送到 Microsoft Entra ID 的元素中 AuthnRequest 是可选的。

元素 NameIdPolicy 如以下示例所示：

<NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"/>

如果 NameIDPolicy 已提供，可以包含其可选 Format 属性。 该 Format 属性只能具有以下值之一;任何其他值都会导致错误。

  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent：Microsoft Entra ID 以 NameID 成对标识符的形式颁发声明。
  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress：Microsoft Entra ID 以电子邮件地址格式颁发 NameID 声明。
  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified：此值允许Microsoft Entra ID 选择声明格式。 Microsoft Entra ID 以 NameID 成对标识符的形式颁发声明。
  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient：Microsoft Entra ID 将 NameID 声明作为随机生成的值颁发，该值对于当前 SSO作是唯一的。 这意味着该值是临时的，不能用于标识身份验证用户。

如果 SPNameQualifier 指定，则Microsoft Entra ID 在响应中包含相同的 SPNameQualifier ID。

Microsoft Entra ID 将忽略该 AllowCreate 属性。

RequestedAuthnContext

该 RequestedAuthnContext 元素指定所需的身份验证方法。 它在发送到 Microsoft Entra ID 的元素中 AuthnRequest 是可选的。

注释

如果 SAML 请求中包含该 RequestedAuthnContext 元素，则必须将 Comparison 元素设置为 exact。

Microsoft Entra ID 支持以下 AuthnContextClassRef 值。

身份验证方法 身份验证上下文类 URI
Kerberos urn：oasis：names：tc：SAML：2.0：ac：classes：Kerberos
用户名和密码 urn:oasis:names:tc:SAML:2.0:ac:classes:Password
PGP 公钥基础结构 urn：oasis：names：tc：SAML：2.0：ac：classes：PGP
保护远程密码 urn：oasis：names：tc：SAML：2.0：ac：classes：SecureRemotePassword
XML 数字签名 urn：oasis：names：tc：SAML：2.0：ac：classes：XMLDSig
简单的公钥基础结构 urn：oasis：names：tc：SAML：2.0：ac：classes：SPKI
智能卡 urn：oasis：names：tc：SAML：2.0：ac：classes：Smartcard
带封闭私钥和 PIN 的智能卡 urn：oasis：names：tc：SAML：2.0：ac：classes：SmartcardPKI
传输层安全性 (TLS) 客户端 urn：oasis：names：tc：SAML：2.0：ac：classes：TLSClient
未指定 urn：oasis：names：tc：SAML：2.0：ac：classes：Unspecified
X.509 证书 urn：oasis：names：tc：SAML：2.0：ac：classes：X509
Windows 集成身份验证 urn：federation：authentication：windows

范围

元素 Scoping （包括标识提供者列表）在发送到 Microsoft Entra ID 的元素中 AuthnRequest 是可选的。

如果提供，则不包括 ProxyCount 属性 IDPListOption 或 RequesterID 元素，因为它们不受支持。

Signature

Signature 元素中的 AuthnRequest 元素是可选的。 Microsoft Entra ID 可配置为强制实施已签名身份验证请求的要求。 如果启用，则仅接受已签名的身份验证请求，否则请求者验证仅通过响应已注册的断言使用者服务 URL 来提供。

Subject

不要包含 Subject 元素。 Microsoft Entra ID 不支持指定主题， AuthnRequest 如果提供了主题，将返回错误。

通过将参数添加到单一 login_hint 登录 URL（主题的 NameID 作为参数值），可以改为提供主题。

响应

请求的登录成功完成后，Microsoft Entra ID 会发布对云服务的响应。 成功登录尝试的响应如以下示例所示：

<samlp:Response ID="_a4958bfd-e107-4e67-b06d-0d85ade2e76a" Version="2.0" IssueInstant="2013-03-18T07:38:15.144Z" Destination="https://contoso.com/identity/inboundsso.aspx" InResponseTo="C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
  <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion"> https://login.partner.microsoftonline.cn/aaaabbbb-0000-cccc-1111-dddd2222eeee/</Issuer>
  <SignatureValue xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
    ...
  </SignatureValue>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
  </samlp:Status>
  <Assertion ID="_bf9c623d-cc20-407a-9a59-c2d0aee84d12" IssueInstant="2013-03-18T07:38:15.144Z" Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
    <Issuer>https://login.partner.microsoftonline.cn/aaaabbbb-0000-cccc-1111-dddd2222eeee/</Issuer>
    <SignatureValue xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
      ...
    </SignatureValue>
    <Subject>
      <NameID>Uz2Pqz1X7pxe4XLWxV9KJQ+n59d573SepSAkuYKSde8=</NameID>
      <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <SubjectConfirmationData InResponseTo="id758d0ef385634593a77bdf7e632984b6" NotOnOrAfter="2013-03-18T07:43:15.144Z" Recipient="https://contoso.com/identity/inboundsso.aspx" />
      </SubjectConfirmation>
    </Subject>
    <Conditions NotBefore="2013-03-18T07:38:15.128Z" NotOnOrAfter="2013-03-18T08:48:15.128Z">
      <AudienceRestriction>
        <Audience>https://www.contoso.com</Audience>
      </AudienceRestriction>
    </Conditions>
    <AttributeStatement>
      <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
        <AttributeValue>testuser@contoso.com</AttributeValue>
      </Attribute>
      <Attribute Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
        <AttributeValue>3F2504E0-4F89-11D3-9A0C-0305E82C3301</AttributeValue>
      </Attribute>
      ...
    </AttributeStatement>
    <AuthnStatement AuthnInstant="2013-03-18T07:33:56.000Z" SessionIndex="_bf9c623d-cc20-407a-9a59-c2d0aee84d12">
      <AuthnContext>
        <AuthnContextClassRef> urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
      </AuthnContext>
    </AuthnStatement>
  </Assertion>
</samlp:Response>

响应

该 Response 元素包括授权请求的结果。 Microsoft Entra ID 设置IDVersion元素中的Response值和IssueInstant值。 它还设置以下属性：

  • Destination：登录成功完成后，会设置为 RedirectUri 服务提供商（云服务）。
  • InResponseTo：设置为 ID 启动响应的 AuthnRequest 元素的属性。

发行人

Microsoft Entra ID 将 Issuer 元素设置为 https://sts.chinacloudapi.cn/<TenantIDGUID>/<TenantIDGUID> Microsoft Entra 租户的租户 ID 的位置。

例如，具有 Issuer 元素的响应可能如以下示例所示：

<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion"> https://sts.chinacloudapi.cn/aaaabbbb-0000-cccc-1111-dddd2222eeee/</Issuer>

状态

该 Status 元素传达登录的成功或失败。 它包括一 StatusCode 个元素，其中包含一个代码或一组表示请求状态的嵌套代码。 它还包括该 StatusMessage 元素，其中包含在登录过程中生成的自定义错误消息。

以下示例是对登录尝试失败的 SAML 响应。

<samlp:Response ID="_f0961a83-d071-4be5-a18c-9ae7b22987a4" Version="2.0" IssueInstant="2013-03-18T08:49:24.405Z" InResponseTo="iddce91f96e56747b5ace6d2e2aa9d4f8c" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
  <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://sts.chinacloudapi.cn/aaaabbbb-0000-cccc-1111-dddd2222eeee/</Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester">
      <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:RequestUnsupported" />
    </samlp:StatusCode>
    <samlp:StatusMessage>AADSTS75006: An error occurred while processing a SAML2 Authentication request. AADSTS90011: The SAML authentication request property 'NameIdentifierPolicy/SPNameQualifier' is not supported.
    Trace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333
    Timestamp: 2013-03-18 08:49:24Z</samlp:StatusMessage>
    </samlp:Status>
</samlp:Response>

断言

除了和IDIssueInstantVersion，Microsoft Entra ID 在响应的元素中Assertion设置以下元素。

发行人

这设置为https://sts.chinacloudapi.cn/<TenantIDGUID>/<TenantIDGUID>Microsoft Entra 租户的租户 ID 的位置。

<Issuer>https://sts.chinacloudapi.cn/aaaabbbb-0000-cccc-1111-dddd2222eeee/</Issuer>

Signature

Microsoft Entra ID 对断言进行签名，以响应成功的登录。 该 Signature 元素包含一个数字签名，云服务可用于对源进行身份验证以验证断言的完整性。

若要生成此数字签名，Microsoft Entra ID 在其元数据文档的元素中使用 IDPSSODescriptor 签名密钥。

<SignatureValue xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
  digital_signature_here
</SignatureValue>

Subject

这指定了断言中语句的主题的原则。 它包含表示 NameID 经过身份验证的用户的元素。 该值 NameID 是一个目标标识符，仅定向到作为令牌访问群体的服务提供程序。 它是永久性的 - 可以吊销，但永远不会重新分配。 它还不透明，因为它不显示有关用户的任何内容，不能用作属性查询的标识符。

元素 Method 的属性 SubjectConfirmation 始终设置为 urn:oasis:names:tc:SAML:2.0:cm:bearer.

<Subject>
  <NameID>Uz2Pqz1X7pxe4XLWxV9KJQ+n59d573SepSAkuYKSde8=</NameID>
  <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
    <SubjectConfirmationData InResponseTo="id758d0ef385634593a77bdf7e632984b6" NotOnOrAfter="2013-03-18T07:43:15.144Z" Recipient="https://contoso.com/identity/inboundsso.aspx" />
  </SubjectConfirmation>
</Subject>

Conditions

此元素指定定义 SAML 断言可接受的使用的条件。

<Conditions NotBefore="2013-03-18T07:38:15.128Z" NotOnOrAfter="2013-03-18T08:48:15.128Z">
  <AudienceRestriction>
    <Audience>https://www.contoso.com</Audience>
  </AudienceRestriction>
</Conditions>

属性NotBeforeNotOnOrAfter指定断言有效间隔。

  • 属性的值NotBefore等于或略低于元素属性IssueInstantAssertion的值（小于秒）。 Microsoft Entra ID 不考虑自身与云服务（服务提供商）之间的任何时间差异，并且不会在此时间添加任何缓冲区。
  • 属性的值 NotOnOrAfter 比特性的值 NotBefore 晚 70 分钟。

观众

这包含标识预期受众的 URI。 Microsoft Entra ID 将此元素的值设置为启动登录的AuthnRequest元素的值Issuer。 若要评估 Audience 该值，请使用在应用程序注册期间指定的值 App ID URI 。

<AudienceRestriction>
  <Audience>https://www.contoso.com</Audience>
</AudienceRestriction>

Issuer与值一样，Audience该值必须与表示Microsoft Entra ID 中的云服务的服务主体名称之一完全匹配。 但是，如果元素的值 Issuer 不是 URI 值， Audience 则响应中的值是 Issuer 前缀 spn:的值。

AttributeStatement

这包含有关主题或用户的声明。 以下摘录包含示例 AttributeStatement 元素。 省略号指示该元素可以包含多个属性和属性值。

<AttributeStatement>
  <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
    <AttributeValue>testuser@contoso.com</AttributeValue>
  </Attribute>
  <Attribute Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
    <AttributeValue>3F2504E0-4F89-11D3-9A0C-0305E82C3301</AttributeValue>
  </Attribute>
  ...
</AttributeStatement>
  • 名称声明 - 属性 （http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name） 的值Name是经过身份验证的用户的用户主体名称，例如testuser@managedtenant.com。
  • ObjectIdentifier Claim - 属性 （http://schemas.microsoft.com/identity/claims/objectidentifier） 的值ObjectIdentifier是ObjectId表示Microsoft Entra ID 中经过身份验证的用户的目录对象。 ObjectId 是经过身份验证的用户的不可变、全局唯一且重用安全标识符。

AuthnStatement

此元素断言断言该断言使用者在特定时间通过特定方式进行身份验证。

  • 该 AuthnInstant 属性指定用户使用 Microsoft Entra ID 进行身份验证的时间。
  • 该 AuthnContext 元素指定用于对用户进行身份验证的身份验证上下文。
<AuthnStatement AuthnInstant="2013-03-18T07:33:56.000Z" SessionIndex="_bf9c623d-cc20-407a-9a59-c2d0aee84d12">
  <AuthnContext>
    <AuthnContextClassRef> urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
  </AuthnContext>
</AuthnStatement>
  • Last updated on