重要
自 2025 年 5 月 1 日起,Azure AD B2C 将不再可供新客户购买。 在我们的常见问题解答中了解详细信息。
在本文中,了解如何将安全断言标记语言 (SAML) 应用程序(服务提供商)连接到 Azure Active Directory B2C (Azure AD B2C) 进行身份验证。
在开始之前,请使用此页面顶部的 “选择策略类型 选择器”来选择要设置的策略类型。 Azure Active Directory B2C 提供了两种定义用户如何与应用程序交互的方法:通过预定义的用户流,或者通过可完全配置的自定义策略。 对于每种方法,本文中所需的步骤都不同。
此功能仅适用于自定义策略。 对于设置步骤,请在前面的选择器中选择“自定义策略”。
使用 Azure AD B2C 作为其客户标识和访问管理解决方案的组织可能需要与使用 SAML 协议进行身份验证的应用程序集成。 下图显示了 Azure AD B2C 如何充当 标识提供者 (IdP) 来实现基于 SAML 的应用程序的单一登录 (SSO)。
- 应用程序会创建一个 SAML AuthN 请求,该请求将发送到 Azure AD B2C 的 SAML 登录终结点。
- 用户可以使用 Azure AD B2C 本地帐户或任何其他联合标识提供者(如果已配置)进行身份验证。
- 如果用户使用联合标识提供者登录,则会向 Azure AD B2C 发送令牌响应。
- Azure AD B2C 生成 SAML 断言并将其发送到应用程序。
对于本文中的方案,您需要:
- 自定义策略初学者包中的 SocialAndLocalAccounts 自定义策略。 完成 Azure AD B2C 中的自定义策略入门中的步骤。
- 对 SAML 协议有基本的了解,并熟悉应用程序的 SAML 实施。
- 一个已配置为 SAML 应用程序的应用程序。 它必须能够发送 SAML AuthN 请求,以及接收、解码和验证来自 Azure AD B2C 的 SAML 响应。 SAML 应用程序也称为信赖方应用程序或服务提供商。
- SAML 应用程序的公开可用 SAML 元数据终结点或 XML 文档。
- Azure AD B2C 租户。
如果您还没有 SAML 应用程序和关联的元数据终端节点,则可以使用我们已提供的 SAML 测试应用程序 进行测试。
若要在应用程序和 Azure AD B2C 之间建立信任关系,这两个服务必须能够创建和验证彼此的签名。 在应用程序和 Azure AD B2C 中配置 X509 证书。
应用程序证书
用法 | 必选 | DESCRIPTION |
---|---|---|
SAML 请求签名 | 否 | 一个证书,其中包含存储在 Web 应用程序中的私钥。 应用程序使用证书对发送到 Azure AD B2C 的 SAML 请求进行签名。 Web 应用程序必须通过其 SAML 元数据端点公开公钥。 Azure AD B2C 使用应用程序元数据中的公钥验证 SAML 请求签名。 |
SAML 断言加密 | 否 | 一个证书,其中包含存储在 Web 应用程序中的私钥。 Web 应用程序必须通过其 SAML 元数据端点公开公钥。 Azure AD B2C 可以使用公钥加密应用程序的断言。 应用程序使用私有密钥解密断言。 |
Azure AD B2C 证书
用法 | 必选 | DESCRIPTION |
---|---|---|
SAML 响应签名 | 是的 | 具有存储在 Azure AD B2C 中的私钥的证书。 Azure AD B2C 使用此证书对发送到应用程序的 SAML 响应进行签名。 应用程序读取 Azure AD B2C 中的元数据公钥,以验证 SAML 响应的签名。 |
SAML 断言签名 | 是的 | 具有存储在 Azure AD B2C 中的私钥的证书。 Azure AD B2C 使用此证书对 <saml:Assertion> SAML 响应的部分进行签名。 |
在生产环境中,我们建议使用公有证书颁发机构颁发的证书。 但您也可以使用自签名证书完成此过程。
若要在应用程序和 Azure AD B2C 之间建立信任关系,请为 SAML 响应创建签名证书。 Azure AD B2C 使用此证书对发送到应用程序的 SAML 响应进行签名。 应用程序读取 Azure AD B2C 的元数据公钥以验证 SAML 响应的签名。
提示
您可以将此策略密钥用于其他目的,例如对 SAML 断言进行签名。
如果你还没有证书,则可以使用自签名证书。 自签名证书是未由证书颁发机构 (CA) 签署的安全证书,不提供由 CA 签名的证书的安全保障。
在 Windows 上,可在 PowerShell 中使用 New-SelfSignedCertificate cmdlet 来生成证书。
运行以下 PowerShell 命令来生成自签名证书。 根据应用程序和 Azure AD B2C 租户名称修改
-Subject
参数,如contosowebapp.contoso.partner.onmschina.cn
。 还可调整-NotAfter
日期,为证书指定不同的过期日期。New-SelfSignedCertificate ` -KeyExportPolicy Exportable ` -Subject "CN=yourappname.yourtenant.partner.onmschina.cn" ` -KeyAlgorithm RSA ` -KeyLength 2048 ` -KeyUsage DigitalSignature ` -NotAfter (Get-Date).AddMonths(12) ` -CertStoreLocation "Cert:\CurrentUser\My"
在 Windows 计算机上,搜索并选择“管理用户证书”
在“证书 - 当前用户”下,选择个人>证书>yourappname.yourtenant.partner.onmschina.cn。
选择该证书,然后依次选择“操作”“所有任务”>“导出”。
选择“下一步”“是,导出私钥”>“下一步” 。
接受“导出文件格式”的默认值,然后选择“下一步” 。
启用“密码”选项,输入证书的密码,然后选择“下一步” 。
若要指定保存证书的位置,请选择“浏览”并导航到所选的目录。
在“另存为”窗口中,输入文件名,然后选择“保存” 。
选择“下一步”>“完成”。
要让 Azure AD B2C 接受 .pfx 文件密码,必须在 Windows 证书存储导出实用工具中使用 TripleDES-SHA1 选项,而不是 AES256-SHA256 对此密码进行加密。
需要在 Azure AD B2C 租户中存储证书。
- 登录到 Azure 门户。
- 如果有权访问多个租户,请选择顶部菜单中的“设置”图标,从“目录 + 订阅”菜单切换到你的 Azure AD B2C 租户。
- 选择 Azure 门户左上角的“ 所有服务 ”,然后搜索并选择“ Azure AD B2C”。
- 在“概述”页上,选择“Identity Experience Framework”。
- 选择“策略密钥”,然后选择“添加”。
- 对于选项,选择上传。
- 对于 Name (名称),输入策略密钥的名称。 例如,输入 SamlIdpCert。 前缀 B2C_1A_ 会自动地被添加到您的密钥名称中。
- 浏览到证书 .pfx 文件并使用私钥选择证书。
- 选择 创建。
若要连接到 SAML 应用程序,Azure AD B2C 必须能够创建 SAML 响应。
打开自定义策略入门包中的 SocialAndLocalAccounts\TrustFrameworkExtensions.xml。
找到该 <ClaimsProviders>
部分并添加以下 XML 代码段以实施 SAML 响应生成器:
<ClaimsProvider>
<DisplayName>Token Issuer</DisplayName>
<TechnicalProfiles>
<!-- SAML Token Issuer technical profile -->
<TechnicalProfile Id="Saml2AssertionIssuer">
<DisplayName>Token Issuer</DisplayName>
<Protocol Name="SAML2"/>
<OutputTokenFormat>SAML2</OutputTokenFormat>
<Metadata>
<Item Key="IssuerUri">https://issuerUriMyAppExpects</Item>
</Metadata>
<CryptographicKeys>
<Key Id="SamlAssertionSigning" StorageReferenceId="B2C_1A_SamlIdpCert"/>
<Key Id="SamlMessageSigning" StorageReferenceId="B2C_1A_SamlIdpCert"/>
</CryptographicKeys>
<InputClaims/>
<OutputClaims/>
<UseTechnicalProfileForSessionManagement ReferenceId="SM-Saml-issuer"/>
</TechnicalProfile>
<!-- Session management technical profile for SAML-based tokens -->
<TechnicalProfile Id="SM-Saml-issuer">
<DisplayName>Session Management Provider</DisplayName>
<Protocol Name="Proprietary" Handler="Web.TPEngine.SSO.SamlSSOSessionProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>
</TechnicalProfile>
</TechnicalProfiles>
</ClaimsProvider>
您可以在 SAML 令牌颁发者技术配置文件中更改元数据项的值 IssuerUri
。 此更改反映在 issuerUri
来自 Azure AD B2C 的 SAML 响应中返回的属性中。 将您的应用程序配置为在 SAML 响应验证期间接受相同的 IssuerUri
值。
<ClaimsProvider>
<DisplayName>Token Issuer</DisplayName>
<TechnicalProfiles>
<!-- SAML Token Issuer technical profile -->
<TechnicalProfile Id="Saml2AssertionIssuer">
<DisplayName>Token Issuer</DisplayName>
<Protocol Name="SAML2"/>
<OutputTokenFormat>SAML2</OutputTokenFormat>
<Metadata>
<Item Key="IssuerUri">https://issuerUriMyAppExpects</Item>
</Metadata>
...
</TechnicalProfile>
现在,您的策略可以创建 SAML 响应,您必须将策略配置为向您的应用程序发出 SAML 响应,而不是默认的 JWT 响应。
在 Starter Pack 的工作目录中创建 SignUpOrSignin.xml 文件的副本,并使用新名称保存它。 本文以 SignUpOrSigninSAML.xml 为例。 此文件是您为信赖方准备的策略文件。 它配置为默认发出 JWT 响应。
在首选编辑器中打开 SignUpOrSigninSAML.xml 文件。
更改以下各项的值:
PolicyId
至B2C_1A_signup_signin_saml
PublicPolicyUri
至http://<tenant-name>.partner.onmschina.cn/B2C_1A_signup_signin_saml
。 将<tenant-name>
占位符替换为 Azure AD B2C 租户域名的子域。 例如,如果租户主域名是contoso.partner.onmschina.cn
,请使用contoso
。 如果您没有租户名称,请了解如何 阅读您的租户详细信息。
<TrustFrameworkPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/online/cpim/schemas/2013/06" PolicySchemaVersion="0.3.0.0" TenantId="<tenant-name>.partner.onmschina.cn" PolicyId="B2C_1A_signup_signin_saml" PublicPolicyUri="http://<tenant-name>.partner.onmschina.cn/B2C_1A_signup_signin_saml">
用户旅程结束时,Azure AD B2C 将包含
SendClaims
步骤。 此步骤引用令牌颁发者技术配置文件。 若要发出 SAML 响应而不是默认 JWT 响应,请修改步骤SendClaims
以引用新的 SAML 令牌颁发者技术配置文件Saml2AssertionIssuer
。
在元素前面 <RelyingParty>
添加以下 XML 代码片段。 此 XML 覆盖 SignUpOrSignIn 用户旅程中的编排步骤 7。
如果您是从启动包中的不同文件夹开始,或者通过添加或删除编排步骤来自定义用户旅程,请确保 order
元素中的编号与用户旅程中令牌颁发者步骤指定的编号相符。 例如,在其他初学者包文件夹中,相应的步骤编号为 4 对应 LocalAccounts
,6 对应 SocialAccounts
,以及 9 对应 SocialAndLocalAccountsWithMfa
。
<UserJourneys>
<UserJourney Id="SignUpOrSignIn">
<OrchestrationSteps>
<OrchestrationStep Order="7" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="Saml2AssertionIssuer"/>
</OrchestrationSteps>
</UserJourney>
</UserJourneys>
信赖方元素确定应用程序使用的协议。 默认值为 OpenId
。 元素 Protocol
必须更改为 SAML
。 输出声明将创建到 SAML 断言的声明映射。
将 <TechnicalProfile>
元素中的整个 <RelyingParty>
元素替换为以下技术配置文件 XML。
<TechnicalProfile Id="PolicyProfile">
<DisplayName>PolicyProfile</DisplayName>
<Protocol Name="SAML2"/>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="displayName" />
<OutputClaim ClaimTypeReferenceId="givenName" />
<OutputClaim ClaimTypeReferenceId="surname" />
<OutputClaim ClaimTypeReferenceId="email" DefaultValue="" />
<OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="" />
<OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="objectId"/>
</OutputClaims>
<SubjectNamingInfo ClaimType="objectId" ExcludeAsClaim="true"/>
</TechnicalProfile>
信赖方的最终策略文件应类似于以下 XML 代码:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TrustFrameworkPolicy
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://schemas.microsoft.com/online/cpim/schemas/2013/06"
PolicySchemaVersion="0.3.0.0"
TenantId="contoso.partner.onmschina.cn"
PolicyId="B2C_1A_signup_signin_saml"
PublicPolicyUri="http://contoso.partner.onmschina.cn/B2C_1A_signup_signin_saml">
<BasePolicy>
<TenantId>contoso.partner.onmschina.cn</TenantId>
<PolicyId>B2C_1A_TrustFrameworkExtensions</PolicyId>
</BasePolicy>
<UserJourneys>
<UserJourney Id="SignUpOrSignIn">
<OrchestrationSteps>
<OrchestrationStep Order="7" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="Saml2AssertionIssuer"/>
</OrchestrationSteps>
</UserJourney>
</UserJourneys>
<RelyingParty>
<DefaultUserJourney ReferenceId="SignUpOrSignIn" />
<TechnicalProfile Id="PolicyProfile">
<DisplayName>PolicyProfile</DisplayName>
<Protocol Name="SAML2"/>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="displayName" />
<OutputClaim ClaimTypeReferenceId="givenName" />
<OutputClaim ClaimTypeReferenceId="surname" />
<OutputClaim ClaimTypeReferenceId="email" DefaultValue="" />
<OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="" />
<OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="objectId"/>
</OutputClaims>
<SubjectNamingInfo ClaimType="objectId" ExcludeAsClaim="true"/>
</TechnicalProfile>
</RelyingParty>
</TrustFrameworkPolicy>
备注
您可以按照相同的过程来实现其他类型的用户流(例如:登录、密码重置或配置文件编辑流)。
保存更改并将新的 TrustFrameworkExtensions.xml 和 SignUpOrSigninSAML.xml 策略文件上传到 Azure 门户。
上传策略文件后,Azure AD B2C 使用配置信息生成应用程序将使用的标识提供者的 SAML 元数据文档。 SAML 元数据文档包含服务的位置,例如登录方法、注销方法和证书。
Azure AD B2C 策略元数据在以下 URL 中提供:
https://<tenant-name>.b2clogin.cn/<tenant-name>.partner.onmschina.cn/<policy-name>/samlp/metadata
将 <tenant-name>
替换为 Azure AD B2C 租户的名称。 将 <policy-name>
替换为策略的名称(ID)。 下面是一个示例:
https://contoso.b2clogin.cn/contoso.partner.onmschina.cn/B2C_1A_signup_signin_saml/samlp/metadata
为了让 Azure AD B2C 信任您的应用程序,请创建一个 Azure AD B2C 应用程序注册。 注册包含配置信息,例如应用程序的元数据终结点。
- 登录到 Azure 门户。
- 如果有权访问多个租户,请选择顶部菜单中的“设置”图标,从“目录 + 订阅”菜单切换到你的 Azure AD B2C 租户。
- 在左侧菜单中,选择 Azure AD B2C。 或者,选择 “所有服务 ”,然后搜索并选择 “Azure AD B2C”。
- 选择“应用注册”,然后选择“新建注册”。
- 为应用程序输入名称。 例如,输入 SAMLApp1。
- 在“支持的帐户类型”下,选择“仅此组织目录中的帐户”。
- 在 Redirect URI (重定向 URI) 下,选择 Web ,然后输入
https://localhost
。 稍后会在应用程序注册的清单中修改此值。 - 选择“注册”。
对于 SAML 应用程序,您需要在应用程序注册的清单中配置多个属性。
- 在 Azure 门户中,转到在上一节中创建的应用程序注册。
- 在“ 管理”下,选择“ 清单 ”以打开清单编辑器。 然后修改以下部分中描述的属性。
当 SAML 应用程序向 Azure AD B2C 发出请求时,SAML AuthN 请求包含一个 Issuer
属性。 此属性的值通常与应用程序的元数据 entityID
值相同。 Azure AD B2C 使用此值在目录中查找应用程序注册并读取配置。 要使此查找成功,应用程序注册中的 identifierUri
必须填入与 Issuer
属性匹配的值。
在注册清单中,找到 identifierURIs
参数并添加相应的值。 此值将与在应用程序的 SAML AuthN 请求中为 EntityId
配置的值,以及应用程序元数据中的 entityID
值相同。 还需要找到参数 accessTokenAcceptedVersion
并将值设置为 2
。
重要
如果不将 accessTokenAcceptedVersion
更新为 2
,则会收到一条需要已验证域的错误消息。
以下示例显示了 entityID
SAML 元数据中的值:
<EntityDescriptor ID="id123456789" entityID="https://samltestapp2.chinacloudsites.cn" validUntil="2099-12-31T23:59:59Z" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
该 identifierUris
属性仅接受域 tenant-name.partner.onmschina.cn
上的 URL 。
"identifierUris":"https://tenant-name.partner.onmschina.cn/app-name",
按其 identifierUri
值加载应用程序注册后,Azure AD B2C 使用应用程序的元数据来验证 SAML AuthN 请求并确定如何响应。
我们建议您的应用程序公开可公开访问的元数据终端节点。
如果在 SAML 元数据 URL 和应用程序注册的清单中 都 指定了属性,则会 合并这些属性。 首先处理元数据 URL 中指定的属性,并优先处理这些属性。
以 SAML 测试应用程序为例,您将在应用程序清单中为 samlMetadataUrl
使用以下值:
"samlMetadataUrl":"https://samltestapp2.chinacloudsites.cn/Metadata",
可以配置 Azure AD B2C 要向其发送 SAML 响应的回复 URL。 可以在应用程序清单中配置回复 URL。 当您的应用程序不公开可公开访问的元数据终端节点时,此配置非常有用。
SAML 应用程序的回复 URL 是应用程序预期接收 SAML 响应的终端节点。 应用程序通常在元数据文档中提供此 URL 作为 Location
元素的属性 AssertionConsumerService
,如以下示例所示:
<SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
...
<AssertionConsumerService index="0" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://samltestapp2.chinacloudsites.cn/SP/AssertionConsumer" />
</SPSSODescriptor>
如果应用程序的 metadata AssertionConsumerService
元件缺失,或者您想要覆盖它,请配置应用注册清单文件的 replyUrlsWithType
属性。 Azure AD B2C 使用 replyUrlsWithType
在用户使用 HTTP-POST
绑定类型登录后将用户重定向。
以 SAML 测试应用程序为例,您需要将url
属性设置为以下 JSON 代码段中replyUrlsWithType
所示的值:
"replyUrlsWithType":[
{
"url":"https://samltestapp2.chinacloudsites.cn/SP/AssertionConsumer",
"type":"Web"
}
],
注销 URL 定义在注销请求后将用户重定向到何处。 应用程序通常在元数据文档中提供此 URL 作为 Location
元素的属性 SingleLogoutService
,如以下示例所示:
<SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://samltestapp2.chinacloudsites.cn/logout" ResponseLocation="https://samltestapp2.chinacloudsites.cn/logout" />
</SPSSODescriptor>
如果缺少应用程序的元数据 SingleLogoutService
元素,请配置应用程序注册清单 logoutUrl
属性。 Azure AD B2C 使用 logoutURL
在用户使用 HTTP-Redirect
绑定类型注销后将用户重定向。
以 SAML 测试应用程序为例,您将该 logoutUrl
属性设置为 https://samltestapp2.chinacloudsites.cn/logout
:
"logoutUrl": "https://samltestapp2.chinacloudsites.cn/logout",
备注
如果选择在应用程序清单中配置回复 URL 和注销 URL,而不通过 samlMetadataUrl
属性填充应用程序的元数据终结点,则 Azure AD B2C 不会验证 SAML 请求签名。 它也不会加密 SAML 响应。
最后一步是在 SAML 应用程序中将 Azure AD B2C 启用为 SAML IdP。 每个应用程序都不同,步骤也不同。 有关详细信息,请参阅应用的文档。
元数据可以在应用程序中配置为 静态元数据 或 动态元数据。 在静态模式下,从 Azure AD B2C 策略元数据复制全部或部分元数据。 在动态模式下,提供元数据的 URL,并允许应用程序动态读取元数据。
通常需要满足以下部分或全部要求:
元数据:使用格式
https://<tenant-name>.b2clogin.cn/<tenant-name>.partner.onmschina.cn/<policy-name>/Samlp/metadata
.颁发者:SAML 请求的值
issuer
必须与应用程序注册清单的元素中identifierUris
配置的 URI 之一匹配。 如果 SAML 请求的名称issuer
不存在于元素identifierUris
中,请将其添加到应用程序注册清单中。 例如:https://contoso.partner.onmschina.cn/app-name
。登录 URL、SAML 终结点、SAML URL:检查 Azure AD B2C SAML 策略元数据文件中的 XML 元素
<SingleSignOnService>
所包含的值。证书:此证书 B2C_1A_SamlIdpCert,但没有私钥。 要获取证书的公钥,请执行以下作:
- 转到之前指定的元数据网址。
- 复制元素中的
<X509Certificate>
值。 - 将其粘贴到文本文件中。
- 将文本文件另存为 .cer 文件。
您可以使用我们的 SAML 测试应用程序 来测试您的配置:
- 更新租户名称。
- 更新策略名称。 例如,使用 B2C_1A_signup_signin_saml。
- 指定颁发者 URI。 使用在应用程序注册清单中的
identifierUris
元素中找到的 URI 之一。 例如,使用https://contoso.partner.onmschina.cn/app-name
。
选择 Login (登录),此时应显示用户登录屏幕。 登录后,将发送 SAML 响应回示例应用程序。
可通过你自己的元数据终结点支持以下 SAML 应用程序方案:
- 在应用程序或服务主体对象中,为注销 URL 指定多个地址或为其设置 POST 绑定。
- 指定签名密钥以验证应用程序或服务主体对象中的信赖方请求。
- 在应用程序或服务主体对象中指定令牌加密密钥。
- 指定 IdP 发起的登录,其中标识提供者为 Azure AD B2C。
- 从 Azure AD B2C GitHub 社区存储库获取 SAML 测试 Web 应用。
- 请参阅 用于在 Azure AD B2C 中注册 SAML 应用程序的选项。
- 了解如何 通过开发人员最佳做法构建复原能力。