通过

保护在 Microsoft Entra 外部 ID 自助注册用户流中用作 API 连接器的 API

  • 项目

适用于：带白色勾号的绿色圆圈。 员工租户 带灰色 X 号的白色圆圈。 外部租户（了解详细信息）

在 Microsoft Entra 外部 ID 自助注册用户流中集成 REST API 时，必须使用身份验证来保护 REST API 终结点。 REST API 身份验证可确保只有具备适当凭据的服务（例如 Microsoft Entra ID）可以调用该终结点。 本文探讨如何保护 REST API。

先决条件

完成演练：向注册用户流添加 API 连接器指南中的步骤。

可以使用 HTTP 基本身份验证或 HTTPS 客户端证书身份验证来保护 API 终结点。 对于这两种情况，都要提供凭据，供 Microsoft Entra ID 在调用 API 终结点时使用。 然后，API 终结点将检查凭据并执行授权决策。

HTTP 基本身份验证

提示

本文中的步骤可能因开始使用的门户而略有不同。

HTTP 基本身份验证在 RFC 2617 中进行定义。 基本身份验证的工作方式如下：Microsoft Entra ID 使用 Authorization 头中的客户端凭据（username 和 password）发送 HTTP 请求。 凭据的格式是 base64 编码的字符串 username:password。 然后，API 负责检查这些值以执行其他授权决策。

若要为 API 连接器配置 HTTP 基本身份验证，请执行下列步骤：

  1. 至少以用户管理员身份登录到 Microsoft Entra 管理中心。
  2. 浏览到“标识”>“外部标识”>“概述”。
  3. 选择“所有 API 连接器”，然后选择要配置的“API 连接器”。
  4. 对于“身份验证类型”，请选择“基本”。
  5. 提供 REST API 终结点的“用户名”和“密码”。 API 连接器基本身份验证配置的屏幕截图。
  6. 选择“保存”。

HTTPS 客户端证书身份验证

客户端证书身份验证是一种基于证书的相互身份验证，其中客户端 Microsoft Entra ID 向服务器提供客户端证书来证明自己的身份。 此操作在 SSL 握手期间发生。 API 负责验证属于有效客户端（例如 Microsoft Entra ID）的证书，并执行授权决策。 客户端证书是一种 X.509 数字证书。

重要

在生产环境中，证书必须由证书颁发机构进行签名。

创建证书

若要创建证书，可以使用 Azure 密钥保管库，其中提供了适用于自签名证书的选项，以及与证书颁发者提供程序相集成以便为证书签名的选项。 建议的设置包括：

  • 使用者：CN=<yourapiname>.<tenantname>.onmicrosoft.com
  • 内容类型：PKCS #12
  • 生存期操作类型：Email all contacts at a given percentage lifetime 或 Email all contacts a given number of days before expiry
  • 密钥类型：RSA
  • 密钥大小：2048
  • 可导出的私钥：Yes（以便能够导出 .pfx 文件）

然后，你可以导出该证书。

选项 2：使用 PowerShell 准备自签名证书

如果你还没有证书，则可以使用自签名证书。 自签名证书是未由证书颁发机构 (CA) 签署的安全证书，不提供由 CA 签名的证书的安全保障。

在 Windows 上，可在 PowerShell 中使用 New-SelfSignedCertificate cmdlet 来生成证书。

  1. 运行以下 PowerShell 命令来生成自签名证书。 根据应用程序和 Azure AD B2C 租户名称修改 -Subject 参数，如 contosowebapp.contoso.onmicrosoft.com。 还可调整 -NotAfter 日期，为证书指定不同的过期日期。

    New-SelfSignedCertificate `
    -KeyExportPolicy Exportable `
    -Subject "CN=yourappname.yourtenant.onmicrosoft.com" `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -KeyUsage DigitalSignature `
    -NotAfter (Get-Date).AddMonths(12) `
    -CertStoreLocation "Cert:\CurrentUser\My"

  2. 在 Windows 计算机上，搜索并选择“管理用户证书”

  3. 在“证书 - 当前用户”下，选择“个人”>“证书”>“yourappname.yourtenant.onmicrosoft.com” 。

  4. 选择该证书，然后依次选择“操作”>“所有任务”>“导出”。

  5. 选择“下一步”>“是，导出私钥”>“下一步” 。

  6. 接受“导出文件格式”的默认值，然后选择“下一步” 。

  7. 启用“密码”选项，输入证书的密码，然后选择“下一步” 。

  8. 若要指定保存证书的位置，请选择“浏览”并导航到所选的目录。

  9. 在“另存为”窗口中，输入文件名，然后选择“保存” 。

  10. 选择“下一步”>“完成”。

要让 Azure AD B2C 接受 .pfx 文件密码，必须在 Windows 证书存储导出实用工具中使用 TripleDES-SHA1 选项，而不是 AES256-SHA256 对此密码进行加密。

配置 API 连接器

若要为 API 连接器配置客户端证书身份验证，请执行下列步骤：

  1. 至少以用户管理员身份登录到 Microsoft Entra 管理中心。
  2. 浏览到“标识”>“外部标识”>“概述”。
  3. 选择“所有 API 连接器”，然后选择要配置的“API 连接器”。
  4. 对于“身份验证类型”，请选择“证书”。
  5. 在“上传证书”框中，选择包含私钥的证书 .pfx 文件。
  6. 在“输入密码”框中，键入证书的密码。 API 连接器证书身份验证配置的屏幕截图。
  7. 选择“保存”。

执行授权决策

API 必须根据发送的客户端证书实现授权，以便保护 API 终结点。 对于 Azure 应用服务和 Azure Functions，请参阅配置 TLS 相互身份验证来了解如何通过 API 代码启用和验证证书。 也可以将 Azure API 管理用作任何 API 服务前面的层，以根据所需值检查客户端证书属性。

续订证书

建议针对证书过期时间设置提醒警报。 当所使用的证书即将到期时，需要生成新的证书并重复上述步骤。 为了“滚动”使用新证书，API 服务可以在部署新证书期间继续暂时接受新旧证书。

若要将新证书上传到现有 API 连接器，请在“API 连接器”下选择该 API 连接器，然后选择“上传新证书”。 Microsoft Entra ID 将自动使用最近上传的未过期但已超过开始日期的证书。

新证书（如果已存在）的屏幕截图。

API 密钥身份验证

某些服务使用“API 密钥”机制，要求调用方包含一个唯一密钥作为 HTTP 头或 HTTP 查询参数，以模糊处理在开发过程中对 HTTP 端点的访问。 对于 Azure Functions，可以通过在 API 连接器的“终结点 URL”中将 code 添加为查询参数来实现此目的。 例如 https://contoso.azurewebsites.net/api/endpoint?code=0123456789。

在生产环境中不应单独使用此机制。 因此，始终需要基本身份验证或证书身份验证的配置。 如果你不希望出于开发目的实现任何身份验证方法（不建议），可以在 API 连接器配置中选择“基本”身份验证，并对 username 和 password 使用临时值，API 在实现适当的授权时可忽略这些值。

后续步骤