Pas een aangepast domein toe op Azure API Management

📅👤mark241⏱️3 min
GuidesAzureAPI Management
Delen:

Azure API Management is een snelle manier om een consistente, moderne API-gateway te maken voor bestaande back-endservices 1. Dit artikel beschrijft hoe u een aangepast domein kunt toepassen op API Management . Daarnaast leggen we uit hoe u SSL kunt inschakelen met uw eigen certificaat. Alle bronnen worden geïmplementeerd met ARM Template 2 of Azure CLI , zodat u daarmee CI / CD-pijpleidingen kunt bouwen.

1. Implementeer Key Vault

Implementeer eerst Key Vault om de certificaten te bewaren.

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}

De bovenstaande sjabloon bevat bronnen voor Key Vault en API Management . Laten we eerst eens kijken naar 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 is een korte uitleg waarom we eerst API Management hebben gemaakt. In de hieronder beschreven Key Vault implementatie verleent u API Management leestoegang tot Key Vault . Dit is voor API Management om het certificaat opgeslagen te krijgen in Key Vault . API Management en de Managed Id moeten bestaan voordat deze autorisatie kan worden verleend. Raadpleeg het officiële document 3 voor meer informatie over Managed Id . Het is een ID voor het identificeren van API Management en autorisatiebeheer wordt uitgevoerd met behulp van deze ID.

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

In de bovenstaande sjabloon is de Managed Id voor API Management gegenereerd. Raadpleeg de officiële documentatie 4 voor andere details.

Laten we nu eens kijken naar Key Vault bronnen.

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}

Het belangrijkste punt van Key Vault bronnen is het beheren van toegangsrechten met accessPolicy . U ziet twee doelen in de 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}

De eerste is om API management toestemming te geven om een certificaat te verkrijgen.

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

Met de bovenstaande beschrijving geeft u de Managed Id van API Management en verleent u de machtiging. Grant get om secrets en certificates .

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

De tweede is toestemming om het certificaat in Key Vault te importeren.

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

In dit artikel zullen we de Azure CLI gebruiken om het certificaat in Key Vault te importeren. Daarom moet u importmachtiging verlenen aan de Azure CLI uitvoerder ( service principal of gebruiker). Geef de doelservice service principal of gebruikersobject- object ID in commanderObjectId en verleen import aan certificates .

2. Importeer het certificaat in Key Vault

Importeer vervolgens het certificaat in Key Vault . Laten we hier Azure CLI opdrachten gebruiken.

powershell
1az keyvault certificate import --file $certFile --name $secretName --vault-name $keyVaultName --password $certPass
  • --file : pad van certificaatbestand. .pfx indeling.
  • --name : Key Vault geheime --name om het certificaat op te slaan.
  • --vault-name : de naam van de sleutelkluis waarin het certificaat wordt opgeslagen.
  • --password : certificaatwachtwoord

Als u hier de Key Vault opgeeft die u eerder hebt gemaakt, wordt het certificaat geïmporteerd. Voer het bovenstaande commando uit met de autoriteit van de uitvoerder die de importbevoegdheid heeft gegeven.

3. Implementeer een aangepast domein voor API Management

Eindelijk API Management opnieuw 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}

Dit lijkt op wat we eerder hebben geïmplementeerd, behalve het gedeelte hostnameConfigurations . Het was een lege array omdat we eerder geen aangepast domein hadden toegepast, maar deze keer bevat het de instellingen van het aangepaste domein.

  • type : het type service om een aangepast domein toe te passen. Er zijn vier soorten: Proxy , Portal , Scm en Management .
  • hostName : aangepast domein FQDN
  • keyVaultId : Key Vault uri van waaruit API Management het certificaat ontvangt

Laten we Proxy voor type opgeven. Dit is het type bij het toepassen van een aangepast domein op API Gateway ( {api management name}.azure-api.net ). keyVaultId kan worden verkregen door de eigenschap secretUtiWithVersion zoals hierboven beschreven.

Algemeen script

Ten slotte is hier een script dat alle bovenstaande sjablonen implementeert. Wijzig deze op de juiste manier volgens uw CI / CD-omgeving.

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}

Samenvatting

In dit artikel wordt beschreven hoe u een aangepast domein voor API Management kunt toepassen met behulp van ARM Template .

  1. Key Vault implementeren
  2. Certificaten importeren in Key Vault
  3. Pas een aangepast domein toe op API Management

We hebben met succes een aangepast domein toegepast met behulp van de bovenstaande stappen.

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 ↩

Delen:

Gerelateerde artikelen

Beschrijf Azure-resources als ARM Template
Guides

Beschrijf Azure-resources als ARM Template

ARM Template is een json-bestand dat Azure-resources definieert. Leer hoe u efficiënt ARM Templates kunt maken.

mark241