Wenden Sie eine benutzerdefinierte Domäne auf die Azure-API-Verwaltung an

📅👤mark241⏱️3 Min
GuidesAzureAPI Management
Teilen:

Azure API Management schnell ein konsistentes, modernes API-Gateway für vorhandene Back-End-Dienste erstellen 1. Dieser Artikel beschreibt das Anwenden einer benutzerdefinierten Domäne auf API Management . Darüber hinaus wird erläutert, wie Sie SSL mit Ihrem eigenen Zertifikat aktivieren. Alle Ressourcen werden mit ARM Template 2 oder Azure CLI bereitgestellt, sodass Sie damit CI / CD-Pipelines erstellen können.

1. Stellen Sie Key Vault bereit

Stellen Sie zunächst Key Vault bereit, um die Zertifikate zu speichern.

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}

Die obige Vorlage enthält Ressourcen für die Key Vault und die API Management . Schauen wir uns zunächst das 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}

Hier ist eine kurze Erklärung, warum wir zuerst das API Management . In der unten beschriebenen Key Vault Bereitstellung gewähren Sie der API Management Lesezugriff auf Key Vault . Damit kann die API Management das Zertifikat in Key Vault speichern. API Management und seine Managed Id müssen vorhanden sein, bevor diese Berechtigung erteilt werden kann. Weitere Informationen zu Managed Id finden Sie im offiziellen Dokument 3. Es ist eine ID zum Identifizieren der API Management , und die Berechtigungsverwaltung wird unter Verwendung dieser ID durchgeführt.

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

In der obigen Vorlage wurde die Managed Id für die API Management generiert. Weitere Einzelheiten finden Sie in der offiziellen Dokumentation 4.

Schauen wir uns als Nächstes die Ressourcen von 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}

Der Schlüsselpunkt der Ressourcen von Key Vault ist die Verwaltung der Zugriffsrechte mit accessPolicy . In der accessPolicy werden zwei Ziele aufgelistet.

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}

Die erste besteht darin, der API management die Berechtigung zum Abrufen eines Zertifikats zu erteilen.

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

Geben Sie mit der obigen Beschreibung die Managed Id der API Management und erteilen Sie die Berechtigung. Erhalten get secrets und certificates .

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

Die zweite Berechtigung ist das Importieren des Zertifikats in 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}

In diesem Artikel wird die Azure CLI zum Importieren des Zertifikats in Key Vault . Daher müssen Sie dem Azure CLI Ausführer ( service principal oder Benutzer) die Importberechtigung erteilen. Geben Sie den service principal oder Benutzer - object ID - commanderObjectId import certificates object ID in commanderObjectId und gewähren import certificates .

2. Importieren Sie das Zertifikat in Key Vault

Importieren Sie anschließend das Zertifikat in Key Vault . Verwenden wir hier die Azure CLI Befehle.

powershell
1az keyvault certificate import --file $certFile --name $secretName --vault-name $keyVaultName --password $certPass
  • --file : Pfad der Zertifikatsdatei. .pfx Format.
  • --name : Name der geheimen Ressource von Key Vault zum Speichern des Zertifikats.
  • --vault-name : Der Name des Schlüsseldepots, in dem das Zertifikat --vault-name ist.
  • --password : Zertifikatspasswort

Wenn Sie hier den zuvor erstellten Key Vault angeben, wird das Zertifikat importiert. Führen Sie den obigen Befehl mit der Berechtigung des Ausführers aus, der die Importberechtigung erteilt hat.

3. Stellen Sie eine benutzerdefinierte Domäne für die API Management bereit

Stellen Sie abschließend die API Management bereit.

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}

Dies ähnelt dem, was wir zuvor bereitgestellt haben, mit Ausnahme des Teils hostnameConfigurations . Es war ein leeres Array, da wir zuvor keine benutzerdefinierte Domäne angewendet haben, diesmal jedoch die Einstellungen der benutzerdefinierten Domäne.

  • type : Die Art des Dienstes, für den eine benutzerdefinierte Domäne angewendet werden soll. Es gibt vier Typen: Proxy , Portal , Scm und Management .
  • hostName : FQDN der benutzerdefinierten Domäne
  • keyVaultId : Key Vault URL, von der die API Management das Zertifikat erhält

Lassen Sie uns Proxy als Typ angeben. Dies ist der Typ, wenn eine benutzerdefinierte Domäne auf das API-Gateway {api management name}.azure-api.net ( {api management name}.azure-api.net ). keyVaultId kann wie oben beschrieben von der Eigenschaft secretUtiWithVersion abgerufen werden.

Gesamtskript

Schließlich ist hier ein Skript, das alle oben genannten Vorlagen bereitstellt. Bitte ändern Sie sie entsprechend Ihrer CI / CD-Umgebung.

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}

Zusammenfassung

In diesem Artikel wurde beschrieben, wie eine benutzerdefinierte API Management mithilfe der ARM Template .

  1. Stellen Sie Key Vault bereit
  2. Importieren Sie Zertifikate in Key Vault
  3. Wenden Sie eine benutzerdefinierte Domäne auf die API Management

Wir haben eine benutzerdefinierte Domain erfolgreich mithilfe der obigen Schritte angewendet.

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 ↩

Teilen:

Verwandte Artikel