应用、API 密钥和Azure Key Vault机密

Azure Key Vault是保护加密密钥、机密和证书的Azure服务。它为 API 密钥等敏感信息提供了一个集中、安全且高度可用的存储库。避免直接在应用程序的源代码中嵌入 API 密钥的不安全做法的一种方法是将应用配置为安全地与存储在Azure Key Vault中的 API 密钥进行交互。

本文介绍如何创建Key Vault实例，将 API 密钥作为机密添加到此key vault，然后使用最佳做法配置key vault。这些最佳实践包括使用基于角色的 Azure 访问控制 (Azure RBAC) 来限制访问、启用监视以及限制网络访问。

创建和保护Azure Key Vault实例

Azure Key Vault允许安全地存储加密密钥、机密和证书。你应针对不同环境（开发、暂存、生产）和应用程序部署单独的密钥保管库。

创建资源组和密钥保管库实例

若要创建密钥保管库实例，可以从Azure CLI或Azure PowerShell使用以下命令：

Azure CLI
Azure PowerShell

使用 az group create 命令以创建资源组：
```
az group create --name "myResourceGroup" --location "ChinaEast"
```
如果愿意，可以将“ChinaEast”更改为离你更近的位置。
使用 az keyvault create 创建密钥保管库：
```
az keyvault create --name "<vault-name>" --resource-group "myResourceGroup" --enable-rbac-authorization true --enable-purge-protection true
```
将 <vault-name> 替换为在所有Azure中唯一的名称。通常使用个人或公司名称以及其他数字和标识符。

使用 New-AzResourceGroup 命令以创建资源组：
```
New-AzResourceGroup -Name "myResourceGroup" -Location "ChinaEast"
```
如果愿意，可以将“ChinaEast”更改为离你更近的位置。
使用 New-AzKeyVault 创建密钥保管库：
```
New-AzKeyVault -Name "<vault-name>" -ResourceGroupName "myResourceGroup" -Location "ChinaEast" -EnableRbacAuthorization $true -EnablePurgeProtection
```
将 <vault-name> 替换为在所有Azure中唯一的名称。通常使用个人或公司名称以及其他数字和标识符。

将 API 密钥作为机密添加到Azure Key Vault

创建Azure Key Vault实例后，可以将 API 密钥作为机密添加到此Azure Key Vault实例。

Azure CLI
Azure PowerShell

下面使用 Azure CLI az keyvault secret set 命令以设置将名为 MyApiKey 的机密添加到密钥库，并将其设置为在 180 天后过期：

az keyvault secret set \
    --vault-name "<vault-name>" \
    --name "MyApiKey" \
    --value "<secret-value>"
    --expires "$(date -u -d '+180 days' +'%Y-%m-%dT%H:%M:%SZ')"

下面使用 Azure PowerShell Set-AzKeyVaultSecret cmdlet 将名为 MyApiKey 的机密添加到 keyvault，并将机密设置为在 180 天后过期：

$secret = ConvertTo-SecureString -String "<secret-value>" -AsPlainText -Force
Set-AzKeyVaultSecret -VaultName "<vault-name>" -Name "MyApiKey" -SecretValue $secret -Expires (Get-Date).AddDays(180)

你应定期轮换 API 密钥。根据你所在组织的安全需求，你选择的密钥轮换频率可以高于或低于每 180 天一次。你可以为“SecretNearExpiry”事件配置一个事件网格订阅，以此作为接收有关即将过期的 API 密钥机密通知的一种方法。

使用 Azure RBAC 限制对Key Vault的访问

可以限制对Azure Key Vault实例的访问，以便只有应用程序的标识有权访问Azure Key Vault。

Azure CLI
Azure PowerShell

为此，请使用 Azure CLI 命令 az role assignment create 来配置 Azure 基于角色的访问控制 (Azure RBAC) 角色。

az role assignment create --role "Key Vault Secrets User" \
  --assignee <object-id-of-app-or-user> \
  --scope /subscriptions/<subscription-id>/resourcegroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>

为此，请使用 Azure Azure PowerShell New-AzRoleAssignment cmdlet 配置基于角色的访问控制（Azure RBAC）角色：

New-AzRoleAssignment -RoleDefinitionName "Key Vault Secrets User" `
    -ObjectId <object-id-of-app-or-user> `
    -Scope "/subscriptions/<subscription-id>/resourcegroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>"

启用Key Vault日志记录和警报

应启用Key Vault实例上的日志记录和警报，作为检测潜在可疑活动的方法。

Azure CLI
Azure PowerShell

若要启用Azure Key Vault日志记录和警报，请使用 Azure CLI az monitor diagnostic-settings create 命令：

az monitor diagnostic-settings create \
    --name myDiagnosticSettings \
    --resource <key-vault-resource-id> \
    --logs '[{"category": "AuditEvent","enabled": true}]' \
    --workspace <log-analytics-workspace-id>

若要启用Azure Key Vault日志记录和警报，请使用 Azure PowerShell Set-AzDiagnosticSetting cmdlet：

Set-AzDiagnosticSetting -Name "myDiagnosticSettings" `
    -ResourceId <key-vault-resource-id> `
    -WorkspaceId <log-analytics-workspace-id> `
    -Category "AuditEvent" `
    -Enabled $true

此命令创建名为 myDiagnosticSettings 的诊断设置，为指定的Azure Key Vault配置它，启用 AuditEvent 日志类别，该类别跟踪安全和访问相关的事件，并将日志发送到指定的Log Analytics工作区进行监视、分析和警报。这样一来，你便能监视访问模式，检测未经授权的访问尝试，并针对关键安全事件配置警报（例如，有人试图在无适当权限的情况下访问机密）。

Azure CLI
Azure PowerShell

可以运行 Azure CLI az monitor scheduled-query create 命令，来监视指定 Log Analytics 工作区中的日志，以检测对 Azure Key Vault 机密的未经授权访问尝试，并在检测到任何匹配的未经授权访问尝试时触发警报：

az monitor scheduled-query create \
    --name "Suspicious Access Alert" \
    --resource-group <resource-group> \
    --scopes <log-analytics-workspace-resource-id> \
    --condition "AzureDiagnostics | where ResourceType == 'VAULTS' | where OperationName == 'SecretGet' | where ResultSignature == 'Unauthorized'"

可以使用 Azure PowerShell New-AzScheduledQueryRule cmdlet 来监视指定 Log Analytics 工作区中的日志，检测是否存在对 Azure Key Vault 机密的未经授权访问尝试，并在找到任何匹配的未经授权访问尝试时触发警报：

New-AzScheduledQueryRule -ResourceGroupName "<resource-group>" `
    -Location "chinaeast" `
    -Action `
        (New-AzScheduledQueryRuleAction -Severity 3 -Trigger `
            (New-AzScheduledQueryRuleTriggerCondition -ThresholdOperator GreaterThan -Threshold 0 -MetricTrigger `
                (New-AzScheduledQueryRuleMetricTrigger -MetricName "UnauthorizedAccess" -MetricResourceId "<log-analytics-workspace-resource-id>" -TimeAggregation "Count" -Operator "GreaterThan" -Threshold 0))) `
    -Source `
        (New-AzScheduledQueryRuleSource -Query "AzureDiagnostics | where ResourceType == 'VAULTS' | where OperationName == 'SecretGet' | where ResultSignature == 'Unauthorized'" -DataSourceId "<log-analytics-workspace-resource-id>") `
    -Schedule `
        (New-AzScheduledQueryRuleSchedule -FrequencyInMinutes 5 -TimeWindowInMinutes 5) `
    -Description "Alert for unauthorized access attempts to Key Vault secrets"

限制对Key Vault的网络访问

应限制对Azure Key Vault的网络访问，以便保管库仅接受来自已知网络位置的请求。有两种常规方法可用于实现此目的：

Azure Private Link。这会在虚拟网络中创建专用终结点，允许应用程序在不遍历公共 Internet 的情况下连接到Azure Key Vault。此选项安全性最高，因为流量始终在你的网络内部传输，但需要创建一个专用终结点并配置 DNS。
防火墙规则。可以在“网络”下配置 Azure Key Vault 的防火墙设置，并使用一个允许的 IP 范围列表。还可以使用此方法允许访问现有虚拟网络，但这要求在所选子网上为Microsoft.KeyVault启用服务终结点。

Azure CLI
Azure PowerShell

可以使用 Azure CLI az network private-endpoint create 命令创建专用终结点：

az network private-endpoint create \
    --name myPrivateEndpoint \
    --resource-group <resource-group> \
    --vnet-name myVNet \
    --subnet mySubnet \
    --private-connection-resource-id /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name> \
    --group-id vault \
    --connection-name myConnection

You can create firewall rules on the Azure Key Vault instance using the Azure CLI [az keyvault network-rule add](https://learn.microsoft.com/cli/azure/keyvault/network-rule#az-keyvault-network-rule-add) command, substituting the appropriate key vault names, resource groups, subnet, and subnet mask information:

```azurecli
az keyvault network-rule add \
    --name <vault-name> \
    --resource-group <resource-group> \
    --ip-address <trusted-ip-address>/32

可以使用 Azure PowerShell New-AzPrivateEndpoint cmdlet 创建专用终结点：

$privateEndpoint = New-AzPrivateEndpoint -Name "myPrivateEndpoint" `
    -ResourceGroupName "<resource-group>" `
    -Location "chinaeast" `
    -SubnetId "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>/subnets/<subnet-name>" `
    -PrivateLinkServiceConnection `
        (New-AzPrivateLinkServiceConnection -Name "myConnection" `
            -PrivateLinkServiceId "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" `
            -GroupId "vault")

可以使用 Azure PowerShell Add-AzKeyVaultNetworkRule cmdlet 在Azure Key Vault实例上创建防火墙规则，替换相应的密钥保管库名称、资源组、子网和子网掩码信息：

Add-AzKeyVaultNetworkRule -VaultName "<vault-name>" `
    -ResourceGroupName "<resource-group>" `
    -IPAddress "<trusted-ip-address>/32"

Azure Key Vault对所有通信强制实施 HTTPS。这可确保你的 API 密钥及其他敏感数据在传输过程中得到加密，防范窃听和中间人攻击。

使用 Python 与Azure Key Vault交互

若要使用Python与Azure Key Vault交互，请安装用于Microsoft Entra ID和Azure Key Vault机密库的Azure标识库：

pip install azure-identity
pip install azure-keyvault-secrets

可以使用Azure标识和Azure Key Vault机密客户端库以编程方式管理机密：

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

key_vault_name = "<vault-name>"
KVUri = f"https://{key_vault_name}.vault.azure.cn"
secret_name = "<secret-name>"

credential = DefaultAzureCredential()
client = SecretClient(vault_url=KVUri, credential=credential)

retrieved_secret = client.get_secret(secret_name)

# Now you can use the API key:

api_key = retrieved_secret.value
print(f"The API key is: {api_key}")

在此示例代码中：

DefaultAzureCredential：此类尝试使用各种方法（环境变量、托管标识等）进行身份验证，使其适用于不同的Azure环境。
SecretClient：此类提供用于与 Key Vault 中的密钥进行交互的方法。
get_secret（）：从Key Vault检索机密。

后续步骤

Last updated on 2026-04-27