通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在您的 API 中心授权对 API 的访问

可以配置设置以授权访问 API 中心内的 API。 这些设置：

  • 使用 API 密钥或 OAuth 2.0 授权启用 API 身份验证
  • 将特定身份验证方法与清单中的特定 API 版本相关联
  • 通过访问策略，指定用户或群组管理对 API 版本的身份验证
  • 允许授权用户直接在 API 中心门户中测试 API

注释

此功能目前处于预览状态。

先决条件

  • Azure 订阅中的 API 中心。 如果尚未创建 API 中心，请参阅快速入门：创建 API 中心。

  • 在 API 中心至少注册一个 API。 有关详细信息，请参阅 教程：在 API 清单中注册 API。

  • 为 API 配置环境和部署。 有关详细信息，请参阅 教程：为 API 添加环境和部署。

  • 设置 API 中心门户。 有关详细信息，请参阅 设置 API 中心门户。

  • 用于存储 API 密钥或 OAuth 2.0 客户端机密的 Azure 密钥保管库。 有关创建密钥保管库的步骤，请参阅 “创建密钥保管库”。 密钥保管库应使用 Azure 基于角色的访问控制（RBAC）权限模型。

  • （对于使用 Microsoft Entra ID 的 OAuth 2.0 授权）在与 Azure 订阅关联的 Microsoft Entra 租户中创建应用注册的权限。

选项 1：配置 API 密钥身份验证的设置

对于支持 API 密钥身份验证的 API，请按照以下步骤在 API 中心配置设置。

1. 在 Azure Key Vault 中存储 API 密钥

若要安全地管理 API 密钥，请将其存储在 Azure Key Vault 中，并使用 API 中心的托管标识访问密钥保管库。

若要将 API 密钥存储为密钥保管库中的机密，请参阅 在 Key Vault 中设置和检索机密。

在 API 中心中启用托管标识

对于此方案，API 中心使用 托管标识 访问密钥保管库。 根据你的需要，启用一个系统分配的托管标识或一个或多个用户分配的托管标识。

以下示例演示如何使用 Azure 门户启用系统分配的托管标识。 概括而言，配置步骤与用户分配的托管标识类似。

  1. 在门户中，导航到你的 API 中心。
  2. 在左侧菜单中，在“安全性”下，选择“托管标识”。
  3. 选择“系统已分配”，并将状态设置为“开”。
  4. 选择“保存”。

向托管标识分配“密钥保管库机密用户”角色

在你的密钥保管库中为你的 API 中心的托管标识分配“密钥保管库机密用户”角色。 以下步骤使用 Azure 门户。

  1. 在门户中导航到你的密钥保管库。
  2. 在左侧菜单中，选择“访问控制(IAM)”。
  3. 选择“+ 添加角色分配”。
  4. 在“添加角色分配”页面上，按如下所示设置值：
    1. 在“角色”选项卡上，选择“密钥保管库机密用户”。
    2. 在“ 成员 ”选项卡上的 “分配访问权限”中，选择 “托管标识>+ 选择成员”。
    3. 在“选择托管标识”页上，选择你在上一部分中添加的 API 中心的系统分配托管标识。 单击“选择”。
    4. 选择“查看 + 分配”两次。

2. 在 API 中心中添加 API 密钥配置

  1. 在门户中，导航到你的 API 中心。

  2. 在左侧菜单中的 “治理”下，选择“ 授权”（预览版）>+ 添加配置。

  3. 在 “添加配置 ”页中，按如下所示设置值： 在门户中配置 API 密钥的屏幕截图。

    设置 说明
    标题 输入授权的名称。
    说明 （可选）输入授权的说明。
    安全方案 选择 API 密钥。
    API 密钥位置 选择 API 请求中密钥的显示方式。 可用值为 标头 （请求标头）和 查询（查询 参数）。
    API 密钥参数名称 输入包含 API 密钥的 HTTP 标头或查询参数的名称。 示例：x-api-key
    API 密钥保管库机密参考 单击 “选择” 并选择存储的订阅、密钥保管库和机密。 示例：https://<key-vault-name>.vault.azure.net/secrets/<secret-name>

  4. 选择 创建。

选项 2：配置 OAuth 2.0 授权的设置

对于支持 OAuth 2.0 授权的 API，请按照以下步骤在 API 中心配置身份验证设置。 可以为以下一个或两个 OAuth 2.0 授权流配置设置：

  • 使用 PKCE（代码交换的证明密钥）授权代码流 - 建议在浏览器中（例如在 API 中心门户中）对用户进行身份验证。
  • 客户端凭据流 - 对于不需要特定用户访问数据权限的应用程序，建议使用此流。

1.创建 OAuth 2.0 应用

对于 OAuth 2.0 授权，在标识提供者（例如与 Azure 订阅关联的 Microsoft Entra 租户）中创建应用注册。 确切的创建步骤取决于使用的标识提供者。

以下示例演示如何在 Microsoft Entra ID 中创建应用注册。

  1. 使用租户中具有足够权限的帐户登录到 Azure 门户 。
  2. 导航到 Microsoft Entra ID>+ 新注册。
  3. 在 “注册应用程序 ”页中，输入应用程序注册设置：
    1. 在 “名称”中，输入应用的有意义的名称。
    2. 在支持的帐户类型中，选择适合你的场景的选项，例如，仅此组织目录中的帐户（单一租户）。
    3. （对于授权代码流）在 重定向 URI 中，选择 单页应用程序（SPA） 并设置 URI。 输入 API 中心门户部署的 URI，格式如下：https://<service-name>.portal.<location>.azure-api-center.ms.。将 <service name> 和 <location> 替换为 API 中心的名称以及部署位置。例如：https://myapicenter.portal.eastus.azure-api-center.ms
    4. 选择“注册”。
  4. 在左侧菜单中的“ 管理”下，选择“ 证书和机密”，然后选择“ + 新建客户端密码”。
    1. 输入说明。
    2. 为 “过期”选择一个选项。
    3. 选择 并添加。
    4. 在离开页面之前复制客户端密码 的值 。 在下一部分中需要用到它。
  5. （可选）在应用注册中添加 API 范围。 有关详细信息，请参阅配置应用程序以公开 Web API。

在 API 中心配置 OAuth 2.0 授权时，需要应用注册中的以下值：

  • 应用注册的“概述”页中的应用程序（客户端）ID 以及之前复制的客户端密码。
  • 应用注册的“概述”“终结点”页上的以下终结点 URL：>
    • OAuth2.0 授权终结点 （v2） - Microsoft Entra ID 的授权终结点
    • OAuth 2.0 令牌终结点 (v2) - 用于 Microsoft Entra ID 的令牌终结点和令牌刷新终结点
  • 在应用注册中配置的任何 API 范围。

2. 在 Azure Key Vault 中存储客户端机密

若要安全地管理机密，请将其存储在 Azure Key Vault 中，并使用 API 中心的托管标识访问密钥保管库。

若要将 API 密钥存储为密钥保管库中的机密，请参阅 在 Key Vault 中设置和检索机密。

在 API 中心中启用托管标识

对于此方案，API 中心使用 托管标识 访问密钥保管库。 根据你的需要，启用一个系统分配的托管标识或一个或多个用户分配的托管标识。

以下示例演示如何使用 Azure 门户启用系统分配的托管标识。 概括而言，配置步骤与用户分配的托管标识类似。

  1. 在门户中，导航到你的 API 中心。
  2. 在左侧菜单中，在“安全性”下，选择“托管标识”。
  3. 选择“系统已分配”，并将状态设置为“开”。
  4. 选择“保存”。

向托管标识分配“密钥保管库机密用户”角色

在你的密钥保管库中为你的 API 中心的托管标识分配“密钥保管库机密用户”角色。 以下步骤使用 Azure 门户。

  1. 在门户中导航到你的密钥保管库。
  2. 在左侧菜单中，选择“访问控制(IAM)”。
  3. 选择“+ 添加角色分配”。
  4. 在“添加角色分配”页面上，按如下所示设置值：
    1. 在“角色”选项卡上，选择“密钥保管库机密用户”。
    2. 在“ 成员 ”选项卡上的 “分配访问权限”中，选择 “托管标识>+ 选择成员”。
    3. 在“选择托管标识”页上，选择你在上一部分中添加的 API 中心的系统分配托管标识。 单击“选择”。
    4. 选择“查看 + 分配”两次。

3. 在 API 中心中添加 OAuth 2.0 授权

  1. 在门户中，导航到你的 API 中心。

  2. 在左侧菜单中的 “治理”下，选择“ 授权”（预览版）>+ 添加配置。

  3. 在 “添加配置 ”页中，按如下所示设置值：

    门户中配置 OAuth 2.0 的屏幕截图。

    注释

    根据之前在标识提供者中创建的应用注册配置设置。 如果使用 Microsoft Entra ID，请查找应用注册“概述”页上的客户端 ID，并在“概述>终结点”页上找到 URL 端点。

    设置 说明
    标题 输入授权的名称。
    说明 （可选）输入授权的说明。
    安全方案 选择 OAuth2。
    客户端 ID 输入在标识提供者中创建的应用的客户端 ID (GUID)。
    客户端密码 单击 “选择” 并选择存储的订阅、密钥保管库和客户端密码。

    示例：https://<key-vault-name>.vault.azure.net/secrets/<secret-name>
    授权 URL 输入标识提供者的 OAuth 2.0 授权终结点。

    Microsoft Entra ID 的示例： https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorize
    令牌 URL 输入身份提供者的 OAuth 2.0 令牌端点。

    Microsoft Entra ID 的示例： https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
    刷新 URL 输入标识提供者的 OAuth 2.0 令牌刷新终结点。 对于大多数标识提供者，与令牌 URL 相同

    Microsoft Entra ID 的示例： https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
    OAuth2 流 选择要使用的一个或两个 OAuth 2.0 流。 可用值为 授权代码（PKCE） 和 客户端凭据。
    范围 输入为您的 API 配置的一个或多个 API 作用域，用空格分隔。 如果未配置作用域，请输入 .default。

  4. 选择“创建”以保存配置。

将身份验证配置添加到 API 版本

为 API 密钥或 OAuth 2.0 流配置设置后，将 API 密钥或 OAuth 2.0 配置添加到 API 中心的 API 版本。

  1. 在门户中，导航到你的 API 中心。
  2. 在左侧菜单中“资产”下，选择“API”。
  3. 选择要将授权配置与的 API 相关联。
  4. 在左侧菜单中的“ 详细信息”下，选择“ 版本”。
  5. 选择要向其添加身份验证配置的 API 版本。
  6. 在左侧菜单中的“ 详细信息”下，选择“ 管理访问”（预览版）>+ 添加身份验证。
  7. 在 “添加身份验证 ”页中，选择要关联的可用 身份验证配置 。
  8. 选择 创建。

注释

可以将多个身份验证配置添加到 API 版本。 例如，如果 API 支持，可以将 API 密钥和 OAuth 2.0 配置添加到同一 API 版本。 同样，可以将相同的配置添加到多个 API 版本。

管理特定用户或组的访问权限

可以管理组织中特定用户或组对 API 版本的身份验证配置的访问权限。 为此，可以配置一个访问策略，该策略分配用户或组 API 中心凭据访问读取者 角色，该角色的范围限定为 API 版本中的特定身份验证配置。 例如，如果只想允许特定用户使用 API 密钥或 OAuth 2.0 流在 API 中心门户中测试 API，这非常有用。

  1. 在门户中，导航到你的 API 中心。

  2. 导航到已向其添加身份验证配置的 API 版本（请参阅上一部分）。

  3. 在左侧菜单中的“ 详细信息”下，选择“ 管理访问权限”（预览版）。

  4. 在要管理其访问权限的身份验证配置行末尾，选择编辑访问策略下拉列表。 在门户中添加访问策略的屏幕截图。

  5. 在 “管理访问 ”页中，选择“ + 添加 > 用户 ”或 “添加 > 组”。

  6. 搜索并选择要添加的用户（或组）。 可以选择多个项。

  7. 单击“选择”。

小窍门

还可以从访问策略中删除用户或组。 在 “管理访问 ”页中，在用户或组的上下文（...）菜单中选择 “删除 ”。

API 中心门户中的测试 API

可以使用 API 中心门户测试为身份验证和用户访问配置的 API。

小窍门

除了允许特定用户在 API 中心门户中测试特定 API 之外，还可以配置 API 的可见性设置 。 门户中的可见性设置控制哪些 API 会显示给所有已登录用户。

  1. 在门户中，导航到你的 API 中心。

  2. 在左侧菜单中的 “API 中心门户”下，选择 “门户设置”。

  3. 选择 “查看 API 中心门户”。

  4. 在 API 中心门户中，选择要测试的 API。

  5. 选择配置了身份验证方法的 API 版本。

  6. 在 “选项”下，选择“ 查看文档”。 API 中心门户中 API 详细信息的屏幕截图。

  7. 在 API 中选择一个操作，然后选择试用此 API。

  8. 在打开的窗口中，查看身份验证设置。 如果有权访问 API，请选择“ 发送 ”以尝试该 API。 在 API 中心门户的测试控制台中测试 API 的屏幕截图。

  9. 如果作成功，则会看到 200 OK 响应代码和响应正文。 如果作失败，则会看到一条错误消息。

相关内容