Применить пользовательский домен к управлению API Azure

📅👤mark241⏱️3 мин
SoftwareAzureAPI Management
Поделиться:

Azure API Management - это быстрый способ создания согласованного современного API-шлюза для существующих внутренних служб [^1]. В этой статье описывается, как применить пользовательский домен к API Management . Кроме того, мы объясним, как включить SSL с вашим собственным сертификатом. Все ресурсы развертываются с помощью ARM Template [^3] или 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 , пожалуйста, обратитесь к официальному документу [^4]. Это идентификатор для идентификации API Management , и управление полномочиями выполняется с использованием этого идентификатора.

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

В приведенной выше части шаблона был создан Managed Id для API Management . Смотрите официальную документацию [^2] для других деталей.

Далее давайте посмотрим на ресурсы 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]"

В приведенном выше описании укажите Managed Id управления API Management и предоставьте полномочия. Грант 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 или пользователю). Укажите целевой субъект service principal или object ID пользователя в commanderObjectId и предоставьте полномочия на 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 : полное доменное имя
  • keyVaultId : keyVaultId Key Vault из которого API Management получает сертификат

Укажем Proxy для типа. Этот тип применяется при применении пользовательского домена к API {api management name}.azure-api.net ( {api management name}.azure-api.net ). keyVaultId может быть получен свойством 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}

Резюме

В этой статье описывается, как применить пользовательский домен API Management с помощью ARM Template .

  1. Развернуть Key Vault
  2. Импорт сертификатов в Key Vault
  3. Применить пользовательский домен к API Management

Мы успешно применили пользовательский домен, используя шаги, описанные выше.

[^1]: API Management documentation [^2]: Microsoft. ApiManagement service template reference [^3]: Azure Resource Manager documentation [^4]: Azure AD-managed identities for Azure resources documentation

Поделиться:

Связанные статьи