在 Azure Active Directory B2C 自定義原則中定義 SAML 識別提供者技術配置檔

發行項
11/25/2024

注意

在 Azure Active Directory B2C 中，自定義原則的設計主要是為了解決複雜的案例。在大部分情況下，我們建議您使用內建的使用者流程。如果您尚未這麼做，請了解開始使用 Active Directory B2C 中的自定義原則入門套件。

Azure Active Directory B2C （Azure AD B2C）提供 SAML 2.0 識別提供者的支援。本文說明與支援此標準化通訊協定之宣告提供者互動的技術配置文件細節。透過 SAML 技術設定檔，您可以與 SAML 型身分識別提供者同盟，例如 ADFS 和 Salesforce。此同盟可讓使用者使用其現有的社交或企業身分識別登入。

元數據交換

元數據是 SAML 通訊協定中用來公開 SAML 合作對象組態的資訊，例如服務提供者或識別提供者。元數據會定義服務的位置，例如登入和註銷、憑證、登入方法等等。識別提供者會使用元數據來瞭解如何與 Azure AD B2C 通訊。元數據是以 XML 格式設定，而且可以使用數位簽名簽署，讓對方可以驗證元數據的完整性。當 Azure AD B2C 與 SAML 識別提供者同盟時，它會做為起始 SAML 要求的服務提供者，並等候 SAML 回應。而且，在某些情況下，接受未經請求的 SAML 驗證，也稱為起始的識別提供者。

這兩方都可以將元數據設定為「靜態元數據」或「動態元數據」。在靜態模式中，您會從一方複製整個元數據，並在另一方進行設定。在動態模式中，您會將URL設定為元數據，而對方則會動態讀取組態。原則相同，您會在識別提供者中設定 Azure AD B2C 技術配置檔的元數據，並在 Azure AD B2C 中設定識別提供者的元數據。

每個 SAML 識別提供者都有不同的步驟來公開和設定服務提供者，在此案例中為 Azure AD B2C，並在識別提供者中設定 Azure AD B2C 元數據。請查看身分識別提供者的檔，以取得如何執行此動作的指引。

下列範例顯示 Azure AD B2C 技術設定檔之 SAML 元數據的 URL 位址：

https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com/your-policy/samlp/metadata?idptp=your-technical-profile

取代下列值：

您的租用戶名稱 與租用戶名稱，例如 fabrikam.b2clogin.com。
具有原則名稱的your-policy 。使用您設定 SAML 提供者技術配置文件的原則，或繼承自該原則的原則。
your-technical-profile with your SAML identity provider technical profile name.

數位簽名憑證交換

若要在 Azure AD B2C 與 SAML 識別提供者之間建立信任，您必須提供有效的 X509 憑證與私鑰。您將具有私鑰的憑證（.pfx 檔案）上傳至 Azure AD B2C 原則金鑰存放區。 Azure AD B2C 會使用您提供的憑證，以數位方式簽署 SAML 登入要求。

憑證會以下列方式使用：

Azure AD B2C 會使用憑證的 Azure AD B2C 私鑰來產生並簽署 SAML 要求。 SAML 要求會傳送至識別提供者，此提供者會使用憑證的 Azure AD B2C 公鑰來驗證要求。 Azure AD B2C 公開憑證可透過技術配置檔元數據存取。或者，您可以手動將.cer檔案上傳至 SAML 識別提供者。
識別提供者會使用識別提供者的憑證私鑰來簽署傳送至 Azure AD B2C 的數據。 Azure AD B2C 會使用識別提供者的公開憑證來驗證數據。每個識別提供者都有不同的設定步驟，請查看身分識別提供者的檔，以取得如何執行此動作的指引。在 Azure AD B2C 中，您的原則需要使用識別提供者的元數據來存取憑證公鑰。

大部分情況下都可以接受自我簽署憑證。針對生產環境，建議使用證書頒發機構單位所簽發的 X509 憑證。此外，如本檔稍後所述，針對非生產環境，您可以停用這兩端的 SAML 簽署。

下圖顯示元數據和憑證交換：

數位加密

若要加密 SAML 回應判斷提示，識別提供者一律會在 Azure AD B2C 技術配置檔中使用加密憑證的公鑰。當 Azure AD B2C 需要解密數據時，它會使用加密憑證的私人部分。

若要加密 SAML 回應判斷提示：

將具有私鑰的有效 X509 憑證上傳至 Azure AD B2C 原則金鑰存放區。
將具有標識符SamlAssertionDecryption的 CryptographicKey 元素新增至 Technical Profile CryptographicKeys 集合。將 StorageReferenceId 設定為您在步驟 1 中建立的原則密鑰名稱。
將技術設定檔元資料 WantsEncryptedAssertions 設定為 true。
使用新的 Azure AD B2C 技術配置檔元數據更新識別提供者。您應該會看到 KeyDescriptor ，並將 use 屬性設定為 encryption 包含您憑證的公鑰。

下列範例顯示用於加密的 SAML 元資料的金鑰描述元區段：

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

通訊協定

Protocol 元素的 Name 屬性必須設定為 SAML2。

輸入宣告

InputClaims 元素是用來在 SAML AuthN 要求主體內傳送 NameId。若要達成此目的，請將 PartnerClaimType 設定為的輸入宣告新增，subject如下所示。

<InputClaims>
	<InputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="subject" />
</InputClaims>

輸出宣告

OutputClaims 元素包含區段下 AttributeStatement SAML 識別提供者所傳回的宣告清單。您可能需要將原則中定義的宣告名稱對應至識別提供者中定義的名稱。您也可以包含只要設定屬性，識別提供者就不會傳回的 DefaultValue 宣告。

主體名稱輸出宣告

若要將 Subject 中的 SAML 判斷提示 NameId 讀取為標準化宣告，請將宣告 PartnerClaimType 設定為屬性的值SPNameQualifier。 SPNameQualifier如果未顯示屬性，請將宣告 PartnerClaimType 設定為屬性的值NameQualifier。

SAML 判斷提示：

<saml:Subject>
  <saml:NameID SPNameQualifier="http://your-idp.com/unique-identifier" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">david@contoso.com</saml:NameID>
  <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
    <SubjectConfirmationData InResponseTo="_cd37c3f2-6875-4308-a9db-ce2cf187f4d1" NotOnOrAfter="2020-02-15T16:23:23.137Z" Recipient="https://your-tenant.b2clogin.com/your-tenant.onmicrosoft.com/B2C_1A_TrustFrameworkBase/samlp/sso/assertionconsumer" />
    </SubjectConfirmation>
  </saml:SubjectConfirmation>
</saml:Subject>

輸出宣告：

<OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="http://your-idp.com/unique-identifier" />

如果 SAML 判斷提示中未顯示這兩個 SPNameQualifier 或 NameQualifier 屬性，請將宣告 PartnerClaimType 設定為 assertionSubjectName。請確定 NameId 是判斷提示 XML 中的第一個值。當您定義多個判斷提示時，Azure AD B2C 會從最後一個判斷提示中挑選主旨值。

下列範例顯示 SAML 識別提供者所傳回的宣告：

issuerUserId 宣告會對應至 assertionSubjectName 宣告。
first_name宣告會對應至 givenName 宣告。
last_name宣告會對應至姓氏宣告。
displayName 宣告會對應至名稱宣告。
沒有名稱對應的電子郵件宣告。

技術配置檔也會傳回識別提供者未傳回的宣告：

包含識別提供者名稱的 identityProvider 宣告。
具有 socialIdpAuthentication 預設值的 authenticationSource 宣告。

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="assertionSubjectName" />
  <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="first_name" />
  <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="last_name" />
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email"  />
  <OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="contoso.com" />
  <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="socialIdpAuthentication" />
</OutputClaims>

OutputClaimsTransformations 元素可能包含 OutputClaimsTransformation 元素的集合，這些元素可用來修改輸出宣告或產生新的宣告。

中繼資料

屬性	必要	描述
PartnerEntity	Yes	SAML 識別提供者元數據的 URL。或複製識別提供者元數據，並將其內嵌在 CDATA 元素 `<![CDATA[Your IDP metadata]]>`內。不建議內嵌識別提供者元數據。識別提供者可能會變更設定，或更新憑證。如果識別提供者元數據已變更，請取得新的元數據，並使用新的元數據更新您的原則。
WantsSignedRequests	No	指出技術配置檔是否需要簽署所有傳出驗證要求。可能的值： `true` 或 `false`。預設值是 `true`。當值設定為 `true`時，必須指定 SamlMessageSigning 密碼編譯密鑰，並簽署所有傳出驗證要求。如果值設定為 `false`，則會從要求省略 SigAlg 和 Signature 參數（查詢字串或 post 參數）。此元數據也會控制元數據 AuthnRequestsSigned 屬性，這是與識別提供者共用之 Azure AD B2C 技術配置檔元數據中的輸出。如果技術配置檔元數據中的 WantSignedRequests 值設定為 `false` ，且識別提供者元數據 WantAuthnRequestsSigned 設定為`false`或未指定，Azure AD B2C 就不會簽署要求。
XmlSignatureAlgorithm	No	Azure AD B2C 用來簽署 SAML 要求的方法。此元數據會控制 SAML 要求中的 SigAlg 參數值（查詢字串或 post 參數）。可能的值： `Sha256`、 `Sha384`、 `Sha512`、或 `Sha1` （預設值）。請確定您在兩端都使用相同的值來設定簽章演算法。只使用憑證支持的演算法。
WantsSignedAssertions	No	指出技術配置檔是否需要簽署所有傳入判斷提示。可能的值： `true` 或 `false`。預設值是 `true`。如果值設定為 `true`，則識別提供者傳送至 Azure AD B2C 的所有判斷提示區段 `saml:Assertion` 都必須簽署。如果值設定為 `false`，則識別提供者不應該簽署判斷提示，但即使這樣做，Azure AD B2C 也不會驗證簽章。此元數據也會控制元數據旗標 WantsAssertionsSigned，這是與識別提供者共用之 Azure AD B2C 技術配置檔元數據中的輸出。如果您停用判斷提示驗證，您可能也想要停用回應簽章驗證（如需詳細資訊，請參閱 ResponsesSigned）。
ResponsesSigned	No	可能的值： `true` 或 `false`。預設值是 `true`。如果值設定為 `false`，則識別提供者不應該簽署 SAML 回應，但即使這樣做，Azure AD B2C 也不會驗證簽章。如果值設定為 `true`，則識別提供者傳送至 Azure AD B2C 的 SAML 回應會簽署，且必須經過驗證。如果您停用 SAML 回應驗證，您可能也想要停用判斷提示簽章驗證（如需詳細資訊，請參閱 WantSignedAssertions）。
WantsEncryptedAssertions	No	指出技術配置檔是否需要加密所有傳入判斷提示。可能的值： `true` 或 `false`。預設值是 `false`。如果值設定為 `true`，則識別提供者傳送至 Azure AD B2C 的判斷提示必須簽署，而且必須指定 SamlAssertionDecryption 密碼編譯密鑰。如果值設定為 `true`，則 Azure AD B2C 技術配置檔的元數據會包含加密區段。識別提供者會讀取元數據，並使用 Azure AD B2C 技術配置檔元數據中提供的公鑰來加密 SAML 回應判斷提示。如果您啟用判斷提示加密，您可能也需要停用回應簽章驗證（如需詳細資訊，請參閱 ResponsesSigned）。
NameIdPolicyFormat	No	指定要用來表示所要求主旨之名稱標識符的條件約束。如果省略，可以使用所要求主體的識別提供者所支援的任何類型的標識碼。例如： `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` 。 NameIdPolicyFormat 可以搭配 NameIdPolicyAllowCreate 使用。請查看識別提供者的檔，以取得支援哪些名稱標識符原則的指引。
NameIdPolicyAllowCreate	No	使用 NameIdPolicyFormat 時，您也可以指定 `AllowCreate` NameIDPolicy 的屬性。此元數據的值是 `true` 或 `false` ，指出識別提供者是否允許在登入流程期間建立新的帳戶。請查看身分識別提供者的檔，以取得如何執行此動作的指引。
AuthenticationRequestExtensions	No	Azure AD B2C 與識別提供者之間同意的選擇性通訊協定訊息擴充元素。延伸模組會以 XML 格式呈現。您可以在 CDATA 元素 `<![CDATA[Your IDP metadata]]>`內新增 XML 資料。請檢查您的識別提供者檔，以查看是否支援延伸模組專案。
IncludeAuthnContextClassReferences	No	指定識別驗證內容類別的一或多個 URI 參考。例如，若要允許使用者僅以使用者名稱和密碼登入，請將值設定為 `urn:oasis:names:tc:SAML:2.0:ac:classes:Password`。若要允許透過受保護工作階段的使用者名稱和密碼登入（SSL/TLS），請指定 `PasswordProtectedTransport`。請查看識別提供者的檔，以取得支援的 AuthnContextClassRef URI 相關指引。將多個 URI 指定為逗號分隔清單。
IncludeKeyInfo	No	指出當系結設定 `HTTP-POST`為時，SAML 驗證要求是否包含憑證的公鑰。可能的值： `true` 或 `false`。
IncludeClaimResolvingInClaimsHandling	No	針對輸入和輸出宣告，指定宣告解析是否包含在技術配置檔中。可能的值： `true`、或 `false` （預設值）。如果您要在技術設定檔中使用宣告解析程式，請將此設定為 `true`。
SingleLogoutEnabled	No	指出在登入期間，技術配置檔是否嘗試從同盟識別提供者註銷。如需詳細資訊，請參閱 Azure AD B2C 會話註銷。可能的值： `true` （預設值），或 `false`。
ForceAuthN	No	在 SAML 驗證要求中傳遞 ForceAuthN 值，以判斷外部 SAML IDP 是否會強制提示使用者進行驗證。根據預設，Azure AD B2C 會在初始登入時將 ForceAuthN 值設定為 false。如果工作階段接著重設（例如，使用 `prompt=login` OIDC 中的），則 ForceAuthN 值會設定為 `true`。設定元數據專案，如下所示，將會強制所有對外部IDP的要求值。可能的值： `true` 或 `false`。
ProviderName	No	在 SAML 驗證要求中傳遞 ProviderName 值。

密碼編譯金鑰

CryptographicKeys 元素包含下列屬性：

屬性	必要	描述
SamlMessageSigning	Yes	用來簽署SAML訊息的 X509 憑證（RSA 金鑰集）。 Azure AD B2C 會使用此金鑰來簽署要求，並將其傳送至識別提供者。
SamlAssertionDecryption	不*	X509 憑證（RSA 金鑰集）。 SAML 識別提供者會使用憑證的公用部分來加密 SAML 回應的判斷提示。 Azure AD B2C 會使用憑證的私人部分來解密判斷提示。 * 如果外部 IDP 加密 SAML 判斷提示，則為必要項。
MetadataSigning	No	用來簽署 SAML 元數據的 X509 憑證（RSA 金鑰集）。 Azure AD B2C 會使用此金鑰來簽署元數據。

下一步

如需在 Azure AD B2C 中使用 SAML 識別提供者的範例，請參閱下列文章：

共用方式為