在 Azure Cosmos DB 中配置 IP 防火墙Configure IP firewall in Azure Cosmos DB

适用于: SQL API Cassandra API Gremlin API 表 API Azure Cosmos DB API for MongoDB

为了保护帐户中存储的数据,Azure Cosmos DB 支持基于机密的授权模型,该模型利用强大的基于哈希的消息身份验证代码 (HMAC)。To secure the data stored in your account, Azure Cosmos DB supports a secret based authorization model that utilizes a strong Hash-based Message Authentication Code (HMAC). 此外,Azure Cosmos DB 支持使用基于 IP 的访问控制来提供入站防火墙支持。Additionally, Azure Cosmos DB supports IP-based access controls for inbound firewall support. 此模型与传统数据库系统的防火墙规则类似,并且为帐户提供额外级别的安全性。This model is similar to the firewall rules of a traditional database system and provides an additional level of security to your account. 利用防火墙,可以配置为仅允许从一组已批准的计算机和/或云服务访问你的 Azure Cosmos 帐户。With firewalls, you can configure your Azure Cosmos account to be accessible only from an approved set of machines and/or cloud services. 从这些已批准的计算机和服务访问 Azure Cosmos 数据库中存储的数据仍需调用方提供有效的授权令牌。Access to data stored in your Azure Cosmos database from these approved sets of machines and services will still require the caller to present a valid authorization token.

IP 访问控制IP access control

默认情况下,只要请求附有有效的授权令牌,即可从 Internet 访问你的 Azure Cosmos 帐户。By default, your Azure Cosmos account is accessible from internet, as long as the request is accompanied by a valid authorization token. 若要配置基于 IP 策略的访问控制,用户必须提供 CIDR(无类域间路由)格式的、要作为客户端 IP 允许列表包含的 IP 地址或 IP 地址范围集,这样才能访问给定的 Azure Cosmos 帐户。To configure IP policy-based access control, the user must provide the set of IP addresses or IP address ranges in CIDR (Classless Inter-Domain Routing) form to be included as the allowed list of client IPs to access a given Azure Cosmos account. 应用此配置后,源自此允许列表外部的计算机的所有请求将收到 403(禁止访问)响应。Once this configuration is applied, any requests originating from machines outside this allowed list receive 403 (Forbidden) response. 使用 IP 防火墙时,我们建议允许 Azure 门户访问你的帐户。When using IP firewall, it is recommended to allow Azure portal to access your account. 需有相应的访问权限才能允许使用数据资源管理器,以及检索 Azure 门户中显示的帐户指标。Access is required to allow use of data explorer as well as to retrieve metrics for your account that show up on the Azure portal. 使用数据资源管理器时,除了要允许 Azure 门户访问你的帐户,还需更新防火墙设置,将当前 IP 地址添加到防火墙规则中。When using data explorer, in addition to allowing Azure portal to access your account, you also need to update your firewall settings to add your current IP address to the firewall rules. 请注意,防火墙更改可能需要多达 15 分钟才能传播,在此期间防火墙可能会呈现出不一致的行为。Note that firewall changes may take up to 15 minutes to propagate and the firewall may exhibit an inconsistent behavior during this period.

可将基于 IP 的防火墙与子网和 VNET 访问控制结合使用。You can combine IP-based firewall with subnet and VNET access control. 将这两种策略相结合,可以限制访问具有某个公共 IP 的任何源,和/或从 VNET 中的特定子网访问任何源。By combining them, you can limit access to any source that has a public IP and/or from a specific subnet within VNET. 若要详细了解如何使用基于子网和 VNET 的访问控制,请参阅从虚拟网络访问 Azure Cosmos DB 资源To learn more about using subnet and VNET-based access control see Access Azure Cosmos DB resources from virtual networks.

总而言之,始终需要提供授权令牌才能访问 Azure Cosmos 帐户。To summarize, authorization token is always required to access an Azure Cosmos account. 如果未设置 IP 防火墙和 VNET 访问控制列表 (ACL),可以使用授权令牌访问 Azure Cosmos 帐户。If IP firewall and VNET Access Control List (ACLs) are not set up, the Azure Cosmos account can be accessed with the authorization token. 在 Azure Cosmos 帐户中设置 IP 防火墙和/或 VNET ACL 后,只有源自指定的源(并且具有授权令牌)的请求才能收到有效的响应。After the IP firewall or VNET ACLs or both are set up on the Azure Cosmos account, only requests originating from the sources you have specified (and with the authorization token) get valid responses.

可以使用 IP 防火墙保护存储在 Azure Cosmos DB 帐户中的数据。You can secure the data stored in your Azure Cosmos DB account by using IP firewalls. Azure Cosmos DB 支持使用基于 IP 的访问控制来提供入站防火墙支持。Azure Cosmos DB supports IP-based access controls for inbound firewall support. 可通过以下方法之一为 Azure Cosmos DB 帐户设置 IP 防火墙:You can set an IP firewall on the Azure Cosmos DB account by using one of the following ways:

  • 通过 Azure 门户From the Azure portal
  • 通过使用 Azure 资源管理器模板来以声明方式进行配置Declaratively by using an Azure Resource Manager template
  • 通过更新 ipRangeFilter 属性并借助 Azure CLI 或 Azure PowerShell 来以编程方式进行配置Programmatically through the Azure CLI or Azure PowerShell by updating the ipRangeFilter property

使用 Azure 门户配置 IP 防火墙Configure an IP firewall by using the Azure portal

若要在 Azure 门户中设置 IP 访问控制策略,请转到 Azure Cosmos DB 帐户页,然后在导航菜单中选择“防火墙和虚拟网络”。 To set the IP access control policy in the Azure portal, go to the Azure Cosmos DB account page and select Firewall and virtual networks on the navigation menu. 将“允许从以下位置访问”值更改为“选定的网络”,然后选择“保存”。 Change the Allow access from value to Selected networks, and then select Save.

此屏幕截图显示了如何在 Azure 门户中打开“防火墙”页

启用 IP 访问控制后,可在 Azure 门户中指定 IP 地址、IP 地址范围和开关。When IP access control is turned on, the Azure portal provides the ability to specify IP addresses, IP address ranges, and switches. 使用开关可以访问其他 Azure 服务和 Azure 门户。Switches enable access to other Azure services and the Azure portal. 以下部分提供了有关这些开关的详细信息。The following sections give details about these switches.

备注

为 Azure Cosmos DB 帐户启用 IP 访问控制策略后,将拒绝从 IP 地址范围允许列表外部的计算机向 Azure Cosmos DB 帐户发出的所有请求。After you enable an IP access control policy for your Azure Cosmos DB account, all requests to your Azure Cosmos DB account from machines outside the allowed list of IP address ranges are rejected. 此外,还会阻止通过门户浏览 Azure Cosmos DB 资源,以确保访问控制的完整性。Browsing the Azure Cosmos DB resources from the portal is also blocked to ensure the integrity of access control.

允许来自 Azure 门户的请求Allow requests from the Azure portal

以编程的方式启用 IP 访问控制策略时,需将 Azure 门户的 IP 地址添加到 ipRangeFilter 属性以维持访问。 When you enable an IP access control policy programmatically, you need to add the IP address for the Azure portal to the ipRangeFilter property to maintain access. 门户 IP 地址是:The portal IP addresses are:

区域Region IP 地址IP address
中国China 139.217.8.252139.217.8.252

可以通过选择“允许从 Azure 门户访问” 选项,允许请求访问 Azure 门户,如以下屏幕截图所示:You can enable requests to access the Azure portal by selecting the Allow access from Azure portal option, as shown in the following screenshot:

此屏幕截图显示了如何启用对 Azure 门户的访问

允许来自多区域的 Azure 数据中心或 Azure 中的其他源的请求Allow requests from multiple-regional Azure datacenters or other sources within Azure

如果通过不提供静态 IP 的服务(例如 Azure 流分析和 Azure Functions)访问 Azure Cosmos DB 帐户,仍可使用 IP 防火墙来限制访问。If you access your Azure Cosmos DB account from services that don't provide a static IP (for example, Azure Stream Analytics and Azure Functions), you can still use the IP firewall to limit access. 要想允许从 Azure 中的其他源进行访问,可以选择“接受来自 Azure 数据中心内部的连接”选项,如以下屏幕截图所示 :You can enable access from other sources within the Azure by selecting the Accept connections from within Azure datacenters option, as shown in the following screenshot:

屏幕截图,演示如何接受来自 Azure 数据中心的连接

如果启用此选项,则会将 IP 地址 0.0.0.0 添加到允许的 IP 地址列表中。When you enable this option, the IP address 0.0.0.0 is added to the list of allowed IP addresses. 0.0.0.0 IP 地址仅限从 Azure 数据中心 IP 范围向 Azure Cosmos DB 帐户发送请求。The 0.0.0.0 IP address restricts requests to your Azure Cosmos DB account from Azure datacenter IP range. 此设置不允许任何其他 IP 范围访问 Azure Cosmos DB 帐户。This setting does not allow access for any other IP ranges to your Azure Cosmos DB account.

备注

该选项将防火墙配置为允许来自 Azure 的所有请求,包括来自 Azure 中部署的其他客户的订阅的请求。This option configures the firewall to allow all requests from Azure, including requests from the subscriptions of other customers deployed in Azure. 此选项允许的 IP 地址较为广泛,因为限制了防火墙策略的有效性。The list of IPs allowed by this option is wide, so it limits the effectiveness of a firewall policy. 仅当请求并非来自虚拟网络中的静态 IP 或子网时,才使用此选项。Use this option only if your requests don't originate from static IPs or subnets in virtual networks. 选择此选项将自动允许从 Azure 门户进行访问,因为 Azure 门户在 Azure 中部署。Choosing this option automatically allows access from the Azure portal because the Azure portal is deployed in Azure.

来自当前 IP 的请求Requests from your current IP

为简化开发,Azure 门户将帮助你识别客户端计算机的 IP 并将其添加到允许列表中。To simplify development, the Azure portal helps you identify and add the IP of your client machine to the allowed list. 然后,计算机上运行的应用可以访问你的 Azure Cosmos DB 帐户。Apps running your machine can then access your Azure Cosmos DB account.

门户将自动检测客户端 IP 地址。The portal automatically detects the client IP address. 它可能是计算机的客户端 IP 地址,也可能是网络网关的 IP 地址。It might be the client IP address of your machine, or the IP address of your network gateway. 请务必在将工作负荷置于生产环境之前删除此 IP 地址。Make sure to remove this IP address before you take your workloads to production.

若要将当前 IP 添加到 IP 列表,请选择“添加当前 IP”。 To add your current IP to the list of IPs, select Add my current IP. 再选择“保存” 。Then select Save.

此屏幕截图显示了如何为当前 IP 配置防火墙设置

来自云服务的请求Requests from cloud services

在 Azure 中,云服务是一种使用 Azure Cosmos DB 托管中间层服务逻辑的常用方法。In Azure, cloud services are a common way for hosting middle-tier service logic by using Azure Cosmos DB. 若要从云服务启用对 Azure Cosmos DB 帐户的访问,必须通过配置 IP 访问控制策略,将云服务的公共 IP 地址添加到与 Azure Cosmos DB 帐户关联的 IP 地址的允许列表中。To enable access to your Azure Cosmos DB account from a cloud service, you must add the public IP address of the cloud service to the allowed list of IP addresses associated with your Azure Cosmos DB account by configuring the IP access control policy. 这可确保云服务的所有角色实例都有权访问 Azure Cosmos DB 帐户。This ensures that all role instances of cloud services have access to your Azure Cosmos DB account.

如以下屏幕截图所示,可以在 Azure 门户中检索云服务的 IP 地址:You can retrieve IP addresses for your cloud services in the Azure portal, as shown in the following screenshot:

该屏幕截图显示在 Azure 门户中显示的云服务的公共 IP 地址

通过添加角色实例横向扩展云服务时,这些新的实例会自动获得 Azure Cosmos DB 帐户的访问权限,因为它们属于同一云服务。When you scale out your cloud service by adding role instances, those new instances will automatically have access to the Azure Cosmos DB account because they're part of the same cloud service.

来自虚拟机的请求Requests from virtual machines

还可以使用虚拟机虚拟机规模集通过 Azure Cosmos DB 托管中间层服务。You can also use virtual machines or virtual machine scale sets to host middle-tier services by using Azure Cosmos DB. 要配置 Cosmos DB 帐户使其允许从虚拟机访问,必须将虚拟机和/或虚拟机规模集的公共 IP 地址配置为你的 Azure Cosmos DB 帐户允许的一个 IP 地址,方法是配置 IP 访问控制策略To configure your Cosmos DB account such that it allows access from virtual machines, you must configure the public IP address of the virtual machine and/or virtual machine scale set as one of the allowed IP addresses for your Azure Cosmos DB account by configuring the IP access control policy.

如以下屏幕截图所示,可以在 Azure 门户中检索虚拟机的 IP 地址:You can retrieve IP addresses for virtual machines in the Azure portal, as shown in the following screenshot:

显示在 Azure 门户中显示的虚拟机的公共 IP 地址的屏幕截图

将虚拟机实例添加到组时,这些实例会自动获得 Azure Cosmos DB 帐户的访问权限。When you add virtual machine instances to the group, they automatically receive access to your Azure Cosmos DB account.

来自 Internet 的请求Requests from the internet

从 Internet 上的计算机访问 Azure Cosmos DB 帐户时,必须将客户端 IP 地址或计算机的 IP 地址范围添加到帐户 IP 地址的允许列表中。When you access your Azure Cosmos DB account from a computer on the internet, the client IP address or IP address range of the machine must be added to the allowed list of IP addresses for your account.

将出站规则添加到防火墙Add outbound rules to the firewall

若要访问要添加到防火墙设置的当前出站 IP 范围的列表,请参阅下载 Azure IP 范围和服务标记To access a current list of outbound IP ranges to add to your firewall settings, please see Download Azure IP Ranges and Service Tags.

若要自动执行此列表,请参阅使用服务标记发现 API(公共预览版)To automate the list, please see Use the Service Tag Discovery API (public preview).

使用资源管理器模板配置 IP 防火墙Configure an IP firewall by using a Resource Manager template

若要配置对 Azure Cosmos DB 帐户的访问控制,请确保资源管理器模板使用允许的 IP 范围数组指定 ipRules 属性。To configure access control to your Azure Cosmos DB account, make sure that the Resource Manager template specifies the ipRules property with an array of allowed IP ranges. 如果将 IP 防火墙配置为已部署的 Cosmos 帐户,请确保 locations 数组与当前部署的位置匹配。If configuring IP Firewall to an already deployed Cosmos account, ensure the locations array matches what is currently deployed. 不能同时修改 locations 数组和其他属性。You cannot simultaneously modify the locations array and other properties. 有关用于 Azure Cosmos DB 的 Azure 资源管理器模板的详细信息和示例,请参阅用于 Azure Cosmos DB 的 Azure 资源管理器模板For more information and samples of Azure Resource Manager templates for Azure Cosmos DB see, Azure Resource Manager templates for Azure Cosmos DB

重要

ipRules 属性已随 API 版本 2020-04-01 引入。The ipRules property has been introduced with API version 2020-04-01. 之前的版本公开的是 ipRangeFilter 属性,该属性是以逗号分隔的 IP 地址的列表。Previous versions exposed an ipRangeFilter property instead, which is a list of comma-separated IP addresses.

下面的示例演示如何在 API 2020-04-01 或更高版本中公开 ipRules 属性:The example below shows how the ipRules property is exposed in API version 2020-04-01 or later:

{
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "name": "[variables('accountName')]",
  "apiVersion": "2020-04-01",
  "location": "[parameters('location')]",
  "kind": "GlobalDocumentDB",
  "properties": {
    "consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
    "locations": "[variables('locations')]",
    "databaseAccountOfferType": "Standard",
    "enableAutomaticFailover": "[parameters('automaticFailover')]",
    "ipRules": [
      {
        "ipAddressOrRange": "139.217.8.252"
      }
    ]
  }
}

下面是适用于 2020-04-01 之前的任何 API 版本的同一示例:Here's the same example for any API version prior to 2020-04-01:

{
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "name": "[variables('accountName')]",
  "apiVersion": "2019-08-01",
  "location": "[parameters('location')]",
  "kind": "GlobalDocumentDB",
  "properties": {
    "consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
    "locations": "[variables('locations')]",
    "databaseAccountOfferType": "Standard",
    "enableAutomaticFailover": "[parameters('automaticFailover')]",
    "ipRangeFilter":"139.217.8.252"
  }
}

使用 Azure CLI 配置 IP 访问控制策略Configure an IP access control policy by using the Azure CLI

以下命令演示如何创建具有 IP 访问控制的 Azure Cosmos DB 帐户:The following command shows how to create an Azure Cosmos DB account with IP access control:

# Create a Cosmos DB account with default values and IP Firewall enabled
resourceGroupName='MyResourceGroup'
accountName='mycosmosaccount'
ipRangeFilter='192.168.221.17,183.240.196.255,139.217.8.252'

# Make sure there are no spaces in the comma-delimited list of IP addresses or CIDR ranges.
az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --locations regionName='China North 2' failoverPriority=0 isZoneRedundant=False \
    --locations regionName='China East 2' failoverPriority=1 isZoneRedundant=False \
    --ip-range-filter $ipRangeFilter

使用 PowerShell 配置 IP 访问控制策略Configure an IP access control policy by using PowerShell

以下脚本演示如何使用 IP 访问控制创建 Azure Cosmos DB 帐户:The following script shows how to create an Azure Cosmos DB account with IP access control:

# Create a Cosmos DB account with default values and IP Firewall enabled
$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"
$ipRules = @("192.168.221.17","183.240.196.255","139.217.8.252")

$locations = @(
    @{ "locationName"="China North 2"; "failoverPriority"=0; "isZoneRedundant"=False },
    @{ "locationName"="China East 2"; "failoverPriority"=1, "isZoneRedundant"=False }
)

# Make sure there are no spaces in the comma-delimited list of IP addresses or CIDR ranges.
$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$locations;
    "ipRules"=$ipRules
}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2020-04-01" -ResourceGroupName $resourceGroupName `
    -Name $accountName -PropertyObject $CosmosDBProperties

排查 IP 访问控制策略的问题Troubleshoot issues with an IP access control policy

可使用以下选项排查 IP 访问控制策略的问题:You can troubleshoot issues with an IP access control policy by using the following options:

Azure 门户Azure portal

为 Azure Cosmos DB 帐户启用 IP 访问控制策略后,将阻止从 IP 地址范围的允许列表外部的计算机向帐户发出的所有请求。By enabling an IP access control policy for your Azure Cosmos DB account, you block all requests to your account from machines outside the allowed list of IP address ranges. 若要启用门户数据平面操作,例如浏览容器和查询文档,需要使用门户中的“防火墙”窗格显式允许访问 Azure 门户 。To enable portal data-plane operations like browsing containers and querying documents, you need to explicitly allow Azure portal access by using the Firewall pane in the portal.

SDKSDKs

使用不在允许列表内的计算机访问 Azure Cosmos DB 资源时,将返回一般的“403 禁止访问”响应,但不提供其他任何详细信息 。When you access Azure Cosmos DB resources by using SDKs from machines that are not in the allowed list, a generic 403 Forbidden response is returned with no additional details. 验证帐户的允许 IP 列表并确保 Azure Cosmos DB 帐户中应用了正确的策略配置。Verify the allowed IP list for your account, and make sure that the correct policy configuration is applied to your Azure Cosmos DB account.

受阻止请求中的源 IPSource IPs in blocked requests

对 Azure Cosmos DB 帐户启用诊断日志记录。Enable diagnostic logging on your Azure Cosmos DB account. 这些日志显示每个请求和响应。These logs show each request and response. 会记录带有 403 返回代码的防火墙相关消息。The firewall-related messages are logged with a 403 return code. 通过筛选这些消息,可以查看已阻止请求的源 IP。By filtering these messages, you can see the source IPs for the blocked requests. 请参阅 Azure Cosmos DB 诊断日志记录See Azure Cosmos DB diagnostic logging.

来自已启用 Azure Cosmos DB 服务终结点的子网的请求Requests from a subnet with a service endpoint for Azure Cosmos DB enabled

来自虚拟网络中已启用 Azure Cosmos DB 服务终结点的子网的请求向 Azure Cosmos DB 帐户发送虚拟网络和子网标识。Requests from a subnet in a virtual network that has a service endpoint for Azure Cosmos DB enabled sends the virtual network and subnet identity to Azure Cosmos DB accounts. 这些请求不包含源的公共 IP,因此 IP 筛选器将拒绝它们。These requests don't have the public IP of the source, so IP filters reject them. 若要允许从虚拟网络中的特定子网进行访问,请添加如何为 Azure Cosmos DB 帐户配置基于虚拟网络和子网的访问中所述的访问控制列表。To allow access from specific subnets in virtual networks, add an access control list as outlined in How to configure virtual network and subnet-based access for your Azure Cosmos DB account. 应用防火墙规则可能需要多达 15 分钟,在此期间防火墙可能会呈现出不一致的行为。It can take up to 15 minutes for firewall rules to apply and the firewall may exhibit an inconsistent behavior during this period.

允许的地址列表中的专用 IP 地址Private IP addresses in list of allowed addresses

使用包含专用 IP 地址的允许地址列表创建或更新 Azure Cosmos 帐户会失败。Creating or updating an Azure Cosmos account with a list of allowed addresses containing private IP addresses will fail. 请确保未在列表中指定专用 IP 地址。Make sure that no private IP address is specified in the list.

后续步骤Next steps

若要为 Azure Cosmos DB 帐户配置虚拟网络服务终结点,请参阅以下文章:To configure a virtual network service endpoint for your Azure Cosmos DB account, see the following articles: