用于在 Azure AD B2C 中注册 SAML 应用程序的选项Options for registering a SAML application in Azure AD B2C

本文介绍将 Azure Active Directory (Azure AD B2C) 与 SAML 应用程序连接时可用的配置选项。This article describes the configuration options that are available when connecting Azure Active Directory (Azure AD B2C) with your SAML application.

开始之前,请使用上面的选择器选择要配置的策略类型。Before you begin, use the selector above to choose the type of policy you’re configuring. Azure AD B2C 提供了两种定义用户如何与应用程序交互的方法:通过预定义的用户流,或者通过完全可配置的自定义策略Azure AD B2C offers two methods of defining how users interact with your applications: though predefined user flows, or through fully configurable custom policies. 对于每种方法,本文中所需的步骤都不同。The steps required in this article are different for each method.

此功能仅适用于自定义策略。This feature is available for custom policies only. 对于设置步骤,请选择上面的“自定义策略”。For setup steps, choose Custom policy above.

加密的 SAML 断言Encrypted SAML assertions

当应用程序要求 SAML 断言采用加密格式时,需要确保在 Azure AD B2C 策略中启用加密。When your application expects SAML assertions to be in an encrypted format, you need to make sure that encryption is enabled in the Azure AD B2C policy.

Azure AD B2C 使用服务提供程序的公钥证书来加密 SAML 断言。Azure AD B2C uses the service provider's public key certificate to encrypt the SAML assertion. 公钥必须存在于 SAML 应用程序的元数据终结点中,并将 KeyDescriptor“use”设置为“Encryption”,如以下示例中所示:The public key must exist in the SAML application's metadata endpoint with the KeyDescriptor 'use' set to 'Encryption', as shown in the following example:

<KeyDescriptor use="encryption">
  <KeyInfo xmlns="https://www.w3.org/2000/09/xmldsig#">
    <X509Data>
      <X509Certificate>valid certificate</X509Certificate>
    </X509Data>
  </KeyInfo>
</KeyDescriptor>

若要使 Azure AD B2C 发送加密的断言,请在信赖方技术配置文件中将 WantsEncryptedAssertion 元数据项设置为 trueTo enable Azure AD B2C to send encrypted assertions, set the WantsEncryptedAssertion metadata item to true in the relying party technical profile. 你也可以配置用于加密 SAML 断言的算法。You can also configure the algorithm used to encrypt the SAML assertion.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="SAML2"/>
    <Metadata>
      <Item Key="WantsEncryptedAssertions">true</Item>
    </Metadata>
   ..
  </TechnicalProfile>
</RelyingParty>

加密方法Encryption method

若要配置用于加密 SAML 断言数据的加密方法,请在信赖方中设置 DataEncryptionMethod 元数据密钥。To configure the encryption method used to encrypt the SAML assertion data, set the DataEncryptionMethod metadata key within the relying party. 可能的值为 Aes256 (默认)、Aes192Sha512Aes128Possible values are Aes256 (default), Aes192, Sha512, or Aes128. 此元数据控制 SAML 响应中 <EncryptedData> 元素的值。The metadata controls the value of the <EncryptedData> element in the SAML response.

若要配置用于加密密钥副本的加密方法(用于加密 SAML 断言数据),请在信赖方中设置 KeyEncryptionMethod 元数据密钥。To configure the encryption method used to encrypt the copy of the key, that was used to encrypt the SAML assertion data, set the KeyEncryptionMethod metadata key within the relying party. 可能的值是 Rsa15(默认值)- RSA 公钥加密标准 (PKCS) 版本 1.5 算法和 RsaOaep - RSA 最佳非对称加密填充 (OAEP) 加密算法。Possible values are Rsa15 (default) - RSA Public Key Cryptography Standard (PKCS) Version 1.5 algorithm, and RsaOaep - RSA Optimal Asymmetric Encryption Padding (OAEP) encryption algorithm. 此元数据控制 SAML 响应中 <EncryptedKey> 元素的值。The metadata controls the value of the <EncryptedKey> element in the SAML response.

下面的示例演示 SAML 断言的 EncryptedAssertion 部分。The following example shows the EncryptedAssertion section of a SAML assertion. 加密数据方法为 Aes128,加密密钥方法为 Rsa15The encrypted data method is Aes128, and the encrypted key method is Rsa15.

<saml:EncryptedAssertion>
  <xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"
    xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" Type="http://www.w3.org/2001/04/xmlenc#Element">
    <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc" />
    <dsig:KeyInfo>
      <xenc:EncryptedKey>
        <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5" />
        <xenc:CipherData>
          <xenc:CipherValue>...</xenc:CipherValue>
        </xenc:CipherData>
      </xenc:EncryptedKey>
    </dsig:KeyInfo>
    <xenc:CipherData>
      <xenc:CipherValue>...</xenc:CipherValue>
    </xenc:CipherData>
  </xenc:EncryptedData>
</saml:EncryptedAssertion>

可以更改加密断言的格式。You can change the format of the encrypted assertions. 若要配置加密格式,请在信赖方中设置 UseDetachedKeys 元数据密钥。To configure the encryption format, set the UseDetachedKeys metadata key within the relying party. 可能的值:truefalse(默认值)。Possible values: true, or false (default). 如果将值设置为 true ,则已分离的键会将加密断言添加为 EncrytedAssertion(而不是 EncryptedData)的子级。When the value is set to true, the detached keys add the encrypted assertion as a child of the EncrytedAssertion as opposed to the EncryptedData.

配置加密方法和格式,使用信赖方技术配置文件中的元数据密钥:Configure the encryption method and format, use the metadata keys within the relying party technical profile:

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="SAML2"/>
    <Metadata>
      <Item Key="DataEncryptionMethod">Aes128</Item>
      <Item Key="KeyEncryptionMethod">Rsa15</Item>
      <Item Key="UseDetachedKeys">false</Item>
    </Metadata>
   ..
  </TechnicalProfile>
</RelyingParty>

启动的身份提供程序流Identity provider-initiated flow

如果应用程序需要在不首先向标识提供程序发送 SAML AuthN 请求的情况下接收 SAML 断言,则必须为标识提供程序启动的流配置 Azure AD B2C。When your application expects to receive a SAML assertion without first sending a SAML AuthN request to the identity provider, you must configure Azure AD B2C for identity provider-initiated flow.

在标识提供程序发起的流中,登录过程由标识提供者 (Azure AD B2C) 发起,该过程将未经请求的 SAML 响应发送到服务提供程序(你的信赖方应用程序)。In identity provider-initiated flow, the sign-in process is initiated by the identity provider (Azure AD B2C), which sends an unsolicited SAML response to the service provider (your relying party application).

目前尚不支持发起标识提供程序是使用 Azure AD B2C 进行联合身份验证的外部标识提供程序的场景,例如 AD-FSSalesforceWe don't currently support scenarios where the initiating identity provider is an external identity provider federated with Azure AD B2C, for example AD-FS, or Salesforce. 仅支持 Azure AD B2C 本地帐户身份验证。It is only supported for Azure AD B2C local account authentication.

若要启用标识提供程序发起的流启动的流程,请在信赖方技术配置文件中将 IdpInitiatedProfileEnabled 元数据项设置为 trueTo enable identity provider-initiated flow, set the IdpInitiatedProfileEnabled metadata item to true in the relying party technical profile.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="SAML2"/>
    <Metadata>
      <Item Key="IdpInitiatedProfileEnabled">true</Item>
    </Metadata>
   ..
  </TechnicalProfile>
</RelyingParty>

若要通过标识提供程序发起的流使用户登录或将用户注册,请使用以下 URL:To sign in or sign up a user through identity provider-initiated flow, use the following URL:

https://<tenant-name>.b2clogin.cn/<tenant-name>.partner.onmschina.cn/<policy-name>/generic/login?EntityId=app-identifier-uri 

请替换以下值:Replace the following values:

  • 将 tenant-name 替换为你的租户名称tenant-name with your tenant name
  • 将 policy-name 替换为你的 SAML 信赖方策略名称policy-name with your SAML relying party policy name
  • 将 app-identifier-uri 替换为元数据文件中的 identifierUris,例如 https://contoso.partner.onmschina.cn/app-nameapp-identifier-uri with the identifierUris in the metadata file, such as https://contoso.partner.onmschina.cn/app-name

示例策略Sample policy

我们提供了一个完整示例策略,可用于通过 SAML 测试应用进行测试。We provide a complete sample policy that you can use for testing with the SAML test app.

  1. 下载 SAML-SP 启动的登录示例策略Download the SAML-SP-initiated login sample policy.
  2. 更新 TenantId 以匹配租户名称,例如 contoso.b2clogin.cn。Update TenantId to match your tenant name, for example contoso.b2clogin.cn.
  3. 保留策略名称 B2C_1A_signup_signin_saml。Keep the policy name B2C_1A_signup_signin_saml.

SAML 响应签名算法SAML response signature algorithm

可以配置对 SAML 断言进行签名的签名算法。You can configure the signature algorithm used to sign the SAML assertion. 可能的值为 Sha256Sha384Sha512Sha1Possible values are Sha256, Sha384, Sha512, or Sha1. 请确保技术配置文件和应用程序使用相同的签名算法。Make sure the technical profile and application use the same signature algorithm. 仅使用证书支持的算法。Use only the algorithm that your certificate supports.

使用信赖方元数据元素中的 XmlSignatureAlgorithm 元数据密钥配置签名算法。Configure the signature algorithm using the XmlSignatureAlgorithm metadata key within the relying party Metadata element.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="SAML2"/>
    <Metadata>
      <Item Key="XmlSignatureAlgorithm">Sha256</Item>
    </Metadata>
   ..
  </TechnicalProfile>
</RelyingParty>

SAML 响应生存期SAML response lifetime

可以配置 SAML 响应保持有效的时长。You can configure the length of time the SAML response remains valid. 使用 TokenLifeTimeInSeconds SAML 令牌颁发者技术配置文件中的元数据项设置生存期。Set the lifetime using the TokenLifeTimeInSeconds metadata item within the SAML Token Issuer technical profile. 此值是在令牌颁发时计算的 NotBefore 时间戳经过的秒数。This value is the number of seconds that can elapse from the NotBefore timestamp calculated at the token issuance time. 默认生存期是 300 秒(5 分钟)。The default lifetime is 300 seconds (5 minutes).

<ClaimsProvider>
  <DisplayName>Token Issuer</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="Saml2AssertionIssuer">
      <DisplayName>Token Issuer</DisplayName>
      <Protocol Name="SAML2"/>
      <OutputTokenFormat>SAML2</OutputTokenFormat>
      <Metadata>
        <Item Key="TokenLifeTimeInSeconds">400</Item>
      </Metadata>
      ...
    </TechnicalProfile>

SAML 响应从偏差开始有效SAML response valid from skew

可以配置应用于 SAML 响应 NotBefore 时间戳的时间偏差。You can configure the time skew applied to the SAML response NotBefore timestamp. 此配置可确保在两个平台之间的时间不同步时,SAML 断言在此时间偏差内仍将被视为有效。This configuration ensures that if the times between two platforms aren't in sync, the SAML assertion will still be deemed valid when within this time skew.

使用 TokenNotBeforeSkewInSeconds SAML 令牌颁发者技术配置文件中的元数据项设置时间偏差。Set the time skew using the TokenNotBeforeSkewInSeconds metadata item within the SAML Token Issuer technical profile. 偏差值以秒为单位,默认值为 0。The skew value is given in seconds, with a default value of 0. 最大值为 3600(1 小时)。The maximum value is 3600 (one hour).

例如,如果 TokenNotBeforeSkewInSeconds 设置为 120 秒:For example, when the TokenNotBeforeSkewInSeconds is set to 120 seconds:

  • 令牌在 13:05:10 UTC 颁发The token is issued at 13:05:10 UTC
  • 令牌从 13:03:10 UTC 开始有效The token is valid from 13:03:10 UTC
<ClaimsProvider>
  <DisplayName>Token Issuer</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="Saml2AssertionIssuer">
      <DisplayName>Token Issuer</DisplayName>
      <Protocol Name="SAML2"/>
      <OutputTokenFormat>SAML2</OutputTokenFormat>
      <Metadata>
        <Item Key="TokenNotBeforeSkewInSeconds">120</Item>
      </Metadata>
      ...
    </TechnicalProfile>

从日期和时间中删除毫秒Remove milliseconds from date and time

可以指定是否将从 SAML 响应中的日期/时间值(包括 IssueInstant、NotBefore、NotOnOrAfter 和 AuthnInstant)中删除毫秒值。You can specify whether the milliseconds will be removed from datetime values within the SAML response (these include IssueInstant, NotBefore, NotOnOrAfter, and AuthnInstant). 若要删除毫秒,请在信赖方中设置 RemoveMillisecondsFromDateTime 元数据密钥。To remove the milliseconds, set the RemoveMillisecondsFromDateTime metadata key within the relying party. 可能的值:false(默认值)或 truePossible values: false (default) or true.

<ClaimsProvider>
  <DisplayName>Token Issuer</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="Saml2AssertionIssuer">
      <DisplayName>Token Issuer</DisplayName>
      <Protocol Name="SAML2"/>
      <OutputTokenFormat>SAML2</OutputTokenFormat>
      <Metadata>
        <Item Key="RemoveMillisecondsFromDateTime">true</Item>
      </Metadata>
      ...
    </TechnicalProfile>

Azure AD B2C 证书颁发者 IDAzure AD B2C issuer ID

如果有多个依赖于不同 entityID 值的 SAML 应用程序,可以重写信赖方文件中的 issueruri 值。If you have multiple SAML applications that depend on different entityID values, you can override the issueruri value in your relying party file. 如需替代证书颁发者 URI,请从基础文件复制 ID 为“Saml2AssertionIssuer”的技术配置文件,重写 issueruri 值。To override the issuer URI, copy the technical profile with the "Saml2AssertionIssuer" ID from the base file and override the issueruri value.

提示

从基础文件中复制 <ClaimsProviders> 节,并在声明提供程序中保留这些元素:<DisplayName>Token Issuer</DisplayName><TechnicalProfile Id="Saml2AssertionIssuer"><DisplayName>Token Issuer</DisplayName>Copy the <ClaimsProviders> section from the base and preserve these elements within the claims provider: <DisplayName>Token Issuer</DisplayName>, <TechnicalProfile Id="Saml2AssertionIssuer">, and <DisplayName>Token Issuer</DisplayName>.

示例:Example:

   <ClaimsProviders>   
    <ClaimsProvider>
      <DisplayName>Token Issuer</DisplayName>
      <TechnicalProfiles>
        <TechnicalProfile Id="Saml2AssertionIssuer">
          <DisplayName>Token Issuer</DisplayName>
          <Metadata>
            <Item Key="IssuerUri">customURI</Item>
          </Metadata>
        </TechnicalProfile>
      </TechnicalProfiles>
    </ClaimsProvider>
  </ClaimsProviders>
  <RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpInSAML" />
    <TechnicalProfile Id="PolicyProfile">
      <DisplayName>PolicyProfile</DisplayName>
      <Protocol Name="SAML2" />
      <Metadata>
     …

会话管理Session management

可以使用 UseTechnicalProfileForSessionManagement 元素和 SamlSSOSessionProvider 管理 Azure AD B2C 和 SAML 信赖方应用之间的会话。You can manage the session between Azure AD B2C and the SAML relying party application using the UseTechnicalProfileForSessionManagement element and the SamlSSOSessionProvider.

调试 SAML 协议Debug the SAML protocol

若要帮助配置和调试与服务提供程序的集成,可以使用 SAML 协议的浏览器扩展,例如 Chrome 的 SAML DevTools 扩展、FireFox 的 SAML 跟踪程序Edge 或 IE 开发人员工具To help configure and debug the integration with your service provider, you can use a browser extension for the SAML protocol, for example, SAML DevTools extension for Chrome, SAML-tracer for FireFox, or Edge or IE Developer tools.

使用这些工具,可以检查应用程序和 Azure AD B2C 之间的集成。Using these tools, you can check the integration between your application and Azure AD B2C. 例如:For example:

  • 检查 SAML 请求是否包含签名,并确定用于登录授权请求的算法。Check whether the SAML request contains a signature and determine what algorithm is used to sign in the authorization request.
  • 检查 Azure AD B2C 是否返回错误消息。Check if Azure AD B2C returns an error message.
  • 检查断言部分是否已加密。Check it the assertion section is encrypted.

后续步骤Next steps