将自定义域应用于Azure API管理

📅👤mark241⏱️约2分钟
GuidesAzureAPI Management
分享：

Azure API Management是一种为现有后端服务1创建一致的现代API网关的快速方法。本文介绍如何将自定义域应用于API Management 。此外，我们将说明如何使用您自己的证书启用SSL。所有资源都使用ARM Template 2或Azure CLI进行部署，因此您可以使用它们来构建CI / CD管道。

1.部署密钥库

首先，部署Key Vault来保存证书。

json
1{
2  "$schema": "https://schema.management.azure.com/schemas/2018-05-01/deploymentTemplate.json#",
3  "contentVersion": "1.0.0.0",
4  "parameters": {
5    "keyVaultName": {
6      "type": "string",
7      "metadata": {
8        "description": "Key Vault Name"
9      }
10    },
11    "apiMgmtName": {
12      "type": "string",
13      "metadata": {
14        "description": "API Management Name"
15      }
16    },
17    "commanderObjectId": {
18      "type": "securestring",
19      "metadata": {
20        "description": "Object id of azure cli command executor."
21      }
22    }
23  },
24  "variables": {},
25  "resources": [
26    {
27      "name": "[parameters('apiMgmtName')]",
28      "type": "Microsoft.ApiManagement/service",
29      "apiVersion": "2019-01-01",
30      "properties": {
31        "notificationSenderEmail": "apimgmt-noreply@mail.windowsazure.com",
32        "hostnameConfigurations": [],
33        "publisherEmail": "ch241.sample@example.com",
34        "publisherName": "mark241"
35      },
36      "sku": {
37        "name": "Developer"
38      },
39      "identity": {
40        "type": "SystemAssigned"
41      },
42      "location": "[resourceGroup().location]"
43    },
44    {
45      "name": "[parameters('keyVaultName')]",
46      "type": "Microsoft.KeyVault/vaults",
47      "apiVersion": "2018-02-14",
48      "location": "[resourceGroup().location]",
49      "dependsOn": [
50        "[resourceId('Microsoft.ApiManagement/service', parameters('apiMgmtName'))]"
51      ],
52      "properties": {
53        "tenantId": "[subscription().tenantId]",
54        "sku": {
55          "family": "A",
56          "name": "standard"
57        },
58        "accessPolicies": [
59          {
60            "tenantId": "[subscription().tenantId]",
61            "objectId": "[reference(resourceId('Microsoft.ApiManagement/service', parameters('apiMgmtName')), '2019-01-01', 'Full').identity.principalId]",
62            "permissions": {
63              "keys": [],
64              "secrets": ["get"],
65              "certificates": ["get"],
66              "storage": []
67            }
68          },
69          {
70            "tenantId": "[subscription().tenantId]",
71            "objectId": "[parameters('commanderObjectId')]",
72            "permissions": {
73              "keys": [],
74              "secrets": [],
75              "certificates": ["import"],
76              "storage": []
77            }
78          }
79        ],
80        "enabledForDeployment": false,
81        "enabledForDiskEncryption": false,
82        "enabledForTemplateDeployment": false
83      },
84      "resources": []
85    }
86  ]
87}

上面的模板包含Key Vault和API Management资源。 首先，让我们看一下API Management 。

json
1{
2  "name": "[parameters('apiMgmtName')]",
3  "type": "Microsoft.ApiManagement/service",
4  "apiVersion": "2019-01-01",
5  "properties": {
6    "notificationSenderEmail": "apimgmt-noreply@mail.windowsazure.com",
7    "hostnameConfigurations": [],
8    "publisherEmail": "ch241.sample@example.com",
9    "publisherName": "mark241"
10  },
11  "sku": {
12    "name": "Developer"
13  },
14  "identity": {
15    "type": "SystemAssigned"
16  },
17  "location": "[resourceGroup().location]"
18}

这是为什么我们首先创建API Management的简要说明。 在下面描述的Key Vault部署中，您授予API Management对Key Vault读取权限。 这是用于API Management以获取存储在Key Vault的证书。 必须先存在API Management及其Managed Id ，然后才能授予此授权。 有关Managed Id更多信息，请参考正式文档3。 它是用于标识API Management的ID，并且使用该ID执行权限管理。

json
1"identity": {
2    "type": "SystemAssigned"
3  }

在上面的模板中，已生成API Management的Managed Id 。 有关其他详细信息，请参见官方文档4。

接下来，让我们看看Key Vault资源。

json
1{
2  "name": "[parameters('keyVaultName')]",
3  "type": "Microsoft.KeyVault/vaults",
4  "apiVersion": "2018-02-14",
5  "location": "[resourceGroup().location]",
6  "dependsOn": [
7    "[resourceId('Microsoft.ApiManagement/service', parameters('apiMgmtName'))]"
8  ],
9  "properties": {
10    "tenantId": "[subscription().tenantId]",
11    "sku": {
12      "family": "A",
13      "name": "standard"
14    },
15    "accessPolicies": [
16      {
17        "tenantId": "[subscription().tenantId]",
18        "objectId": "[reference(resourceId('Microsoft.ApiManagement/service', parameters('apiMgmtName')), '2019-01-01', 'Full').identity.principalId]",
19        "permissions": {
20          "keys": [],
21          "secrets": ["get"],
22          "certificates": ["get"],
23          "storage": []
24        }
25      },
26      {
27        "tenantId": "[subscription().tenantId]",
28        "objectId": "[parameters('commanderObjectId')]",
29        "permissions": {
30          "keys": [],
31          "secrets": [],
32          "certificates": ["import"],
33          "storage": []
34        }
35      }
36    ],
37    "enabledForDeployment": false,
38    "enabledForDiskEncryption": false,
39    "enabledForTemplateDeployment": false
40  },
41  "resources": []
42}

Key Vault资源的关键点是使用accessPolicy管理访问权限。 您将在accessPolicy看到两个目标。

json
1{
2  "tenantId": "[subscription().tenantId]",
3  "objectId": "[reference(resourceId('Microsoft.ApiManagement/service', parameters('apiMgmtName')), '2019-01-01', 'Full').identity.principalId]",
4  "permissions": {
5    "keys": [],
6    "secrets": ["get"],
7    "certificates": ["get"],
8    "storage": []
9  }
10}

第一个是授予API management获得获得证书的权限。

json
1"objectId": "[reference(resourceId('Microsoft.ApiManagement/service', parameters('apiMgmtName')), '2019-01-01', 'Full').identity.principalId]"

通过以上描述，指定API Management的Managed Id并授予权限。 格兰特get secrets和certificates 。

json
1"permissions": {
2    "keys": [],
3    "secrets": ["get"],
4    "certificates": ["get"],
5    "storage": []
6  }

第二个权限是将证书导入Key Vault权限。

json
1{
2  "tenantId": "[subscription().tenantId]",
3  "objectId": "[parameters('commanderObjectId')]",
4  "permissions": {
5    "keys": [],
6    "secrets": [],
7    "certificates": ["import"],
8    "storage": []
9  }
10}

在本文中，我们将使用Azure CLI将证书导入Key Vault 。因此，您需要向Azure CLI执行程序（ service principal或用户）授予导入权限。 在commanderObjectId指定目标service principal或用户object ID ，然后import权限授予certificates 。

2.将证书导入Key Vault

接下来，将证书导入Key Vault 。 在这里，让我们使用Azure CLI命令。

powershell
1az keyvault certificate import --file $certFile --name $secretName --vault-name $keyVaultName --password $certPass
  • --file ：证书文件路径。 .pfx格式。
  • --name ：用于存储证书的密钥库机密资源名称。
  • --vault-name ：存储证书的密钥保管库的名称。
  • --password ：证书密码

在这里，如果您指定了先前创建的Key Vault ，则将导入证书。 以授予导入权限的执行者的权限执行上述命令。

3.部署用于API Management的自定义域

最后，重新部署API Management 。

json
1{
2  "$schema": "https://schema.management.azure.com/schemas/2018-05-01/deploymentTemplate.json#",
3  "contentVersion": "1.0.0.0",
4  "parameters": {
5    "apiMgmtName": {
6      "type": "string",
7      "metadata": {
8        "description": "Service name of API Management"
9      }
10    },
11    "hostName": {
12      "type": "string",
13      "metadata": {
14        "description": "Host name of API Management"
15      }
16    },
17    "keyVaultName": {
18      "type": "string",
19      "metadata": {
20        "description": "Key Vault name"
21      }
22    },
23    "secretName": {
24      "type": "string",
25      "metadata": {
26        "description": "Secret name"
27      }
28    }
29  },
30  "variables": {
31    "keyVaultResourceId": "[resourceId(resourceGroup().name, 'Microsoft.KeyVault/vaults/secrets', parameters('keyVaultName'), parameters('secretName'))]"
32  },
33  "resources": [
34    {
35      "name": "[parameters('apiMgmtName')]",
36      "type": "Microsoft.ApiManagement/service",
37      "apiVersion": "2019-01-01",
38      "properties": {
39        "notificationSenderEmail": "apimgmt-noreply@mail.windowsazure.com",
40        "hostnameConfigurations": [
41          {
42            "type": "Proxy",
43            "hostName": "[parameters('hostName')]",
44            "keyVaultId": "[reference(variables('keyVaultResourceId'), '2018-02-14').secretUriWithVersion]"
45          }
46        ],
47        "publisherEmail": "ch241.sample@example.com",
48        "publisherName": "mark241"
49      },
50      "sku": {
51        "name": "Developer"
52      },
53      "identity": {
54        "type": "SystemAssigned"
55      },
56      "location": "[resourceGroup().location]"
57    }
58  ]
59}

除了hostnameConfigurations部分外，这似乎与我们之前部署的内容相似。 这是一个空数组，因为我们之前没有应用自定义域，但是这次它包含了自定义域的设置。

  • type ：应用自定义域的服务类型。有四种类型： Proxy ， Portal ， Scm和Management 。
  • hostName ：自定义域FQDN
  • keyVaultId ： API Management从中获取证书的Key Vault uri

让我们为类型指定Proxy 。将自定义域应用于API网关（ {api management name}.azure-api.net ）时，就是这种类型。 keyVaultId可以通过secretUtiWithVersion属性secretUtiWithVersion 。

整体剧本

最后，这是一个部署上述所有模板的脚本。 请根据您的CI / CD环境适当地更改它们。

powershell
1Param(
2    [parameter(mandatory = $true)][String]$resourceGroup,
3    [parameter(mandatory = $true)][String]$keyVaultName,
4    [parameter(mandatory = $true)][String]$apiMgmtName,
5    [parameter(mandatory = $true)][String]$objectId,
6    [parameter(mandatory = $true)][String]$certFile,
7    [parameter(mandatory = $true)][String]$certPass,
8    [parameter(mandatory = $true)][String]$secretName,
9    [parameter(mandatory = $true)][String]$hostName
10)
11 
12# 1. Deploy Key Vault
13try{
14    az group deployment create --resource-group $resourceGroup --template-file ./keyvault.json --parameters keyVaultName=$keyVaultName apiMgmtName=$apiMgmtName commanderObjectId=$objectId
15}
16catch {
17    $message = $_.Exception.message
18    Write-Error "Failed to deploy key vault: ${message}"
19}
20 
21# 2. Import a certificate
22try{
23    az keyvault certificate import --file $certFile --name $secretName --vault-name $keyVaultName --password $certPass
24}
25catch {
26    $message = $_.Exception.message
27    Write-Error "Failed to import certificate: ${message}"
28}
29 
30# 3. Deploy API Management
31try {
32    az group deployment create --resource-group $resourceGroup --template-file ./apimgmt.json --parameters apiMgmtName=$apiMgmtName hostName=$hostName keyVaultName=$keyVaultName secretName=$secretName
33}
34catch {
35    $message = $_.Exception.message
36    Write-Error "Failed to deploy api management: ${message}"
37}

摘要

本文介绍了如何使用ARM Template应用API Management自定义域。

  1. 部署Key Vault
  2. 将证书导入Key Vault
  3. 将自定义域应用于API Management

通过上述步骤，我们已成功应用了自定义域。

Footnotes

  1. API Management documentation ↩

  2. Azure Resource Manager documentation ↩

  3. Azure AD-managed identities for Azure resources documentation ↩

  4. Microsoft. ApiManagement service template reference ↩

分享：

相关文章

将后端连接到Azure API管理
Guides

将后端连接到Azure API管理

了解如何使用ARM模板向API管理添加API。使用operations、policy和backend资源连接到后端。

mark241
将Azure资源描述为ARM Template
Guides

将Azure资源描述为ARM Template

ARM Template是定义Azure资源的json文件。本文介绍如何高效创建ARM Template来部署新资源。

mark241