通过

单一登录 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>
参数 类型 描述
ID 必填 Microsoft Entra ID 使用此属性填充返回的响应的 InResponseTo 属性。 ID 不得以数字开头，因此常见的策略是将字符串（如“ID”）追加到 GUID 的字符串表示形式。 例如，id6c1c178c166d486687be4aaf5e482730 是有效的 ID。
Version 必填 此参数应设置为 2.0。
IssueInstant 必填 这是一个具有 UTC 值的 DateTime 字符串，往返格式（“o”）。 Microsoft Entra ID 需要此类型的 DateTime 值，但不计算或使用该值。
AssertionConsumerServiceURL 自选 如果提供此参数，则此参数必须与 Microsoft Entra ID 中的云服务 RedirectUri 匹配。
ForceAuthn 自选 这是一个布尔值。 如果为 true，则表示用户将强制重新进行身份验证，即使用户具有具有Microsoft Entra ID 的有效会话也是如此。
IsPassive 自选 这是一个布尔值，该值指定Microsoft Entra ID 是否应在无提示的情况下使用会话 Cookie（如果存在）以无提示方式对用户进行身份验证。 如果为 true，Microsoft Entra ID 会尝试使用会话 Cookie 对用户进行身份验证。

所有其他 AuthnRequest 属性（如 Consent、Destination、AssertionConsumerServiceIndex、AttributeConsumerServiceIndex和 ProviderName）将被忽略。

Microsoft Entra ID 还会忽略 AuthnRequest中的 Conditions 元素。

发行

AuthnRequest 中的 Issuer 元素必须与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。

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 元素，因为它们不受支持。

签名

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

主题

不要包含 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.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/</Issuer>
  <ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
    ...
  </ds:Signature>
  <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.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/</Issuer>
    <ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
      ...
    </ds:Signature>
    <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 设置 Response 元素中的 ID、Version 和 IssueInstant 值。 它还设置以下属性：

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

发行

Microsoft Entra ID 将 Issuer 元素设置为 https://sts.windows.net/<TenantIDGUID>/，其中 <TenantIDGUID> 是 Microsoft Entra 租户的租户 ID。

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

<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion"> https://sts.windows.net/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.windows.net/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>

断言

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

发行

这设置为 https://sts.windows.net/<TenantIDGUID>/其中 <TenantIDGUID> 是Microsoft Entra 租户的租户 ID。

<Issuer>https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/</Issuer>

签名

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

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

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

主题

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

SubjectConfirmation 元素的 Method 属性始终设置为 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>

条件

此元素指定定义 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>

NotBefore 和 NotOnOrAfter 属性指定断言有效间隔。

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

观众

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

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

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

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>
  • 名称声明 - Name 属性（http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name）的值是经过身份验证的用户的用户主体名称，例如 testuser@managedtenant.com。
  • ObjectIdentifier Claim - ObjectIdentifier 属性（http://schemas.microsoft.com/identity/claims/objectidentifier）的值是表示Microsoft Entra ID 中经过身份验证的用户的目录对象的 ObjectId。 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>