Applicare un dominio personalizzato a Gestione API di Azure

📅👤mark241⏱️3 min
SoftwareAzureAPI Management
Condividi:

Azure API Management è un modo rapido per creare un gateway API coerente e moderno per i servizi di back-end esistenti [^1]. Questo articolo descrive come applicare un dominio personalizzato alla API Management . Inoltre, spiegheremo come abilitare SSL con il tuo certificato. Tutte le risorse sono distribuite con il ARM Template [^3] o l' Azure CLI , in modo da poter costruire con loro pipeline CI / CD.

1. Distribuire Key Vault

Innanzitutto, distribuire Key Vault per conservare i certificati.

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}

Il modello sopra contiene risorse Key Vault e API Management . Innanzitutto, diamo un'occhiata a 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}

Ecco una breve spiegazione del perché abbiamo creato prima API Management . Nella distribuzione di Key Vault descritta di seguito, si concede l'accesso in lettura API Management a Key Vault . Questo è per la API Management per ottenere il certificato archiviato in Key Vault . API Management e il suo Managed Id devono esistere prima che questa autorizzazione possa essere concessa. Per ulteriori informazioni Managed Id , fare riferimento al documento ufficiale [^4]. È un ID per identificare la API Management e la gestione dell'autorità viene eseguita utilizzando questo ID.

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

Nella parte precedente del modello è stato generato l' Managed Id per la API Management . Vedere la documentazione ufficiale [^2] per altri dettagli.

Quindi, esaminiamo le risorse di 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}

Il punto chiave delle risorse di Key Vault è la gestione dei diritti di accesso con accessPolicy . Vedrai due target elencati in 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}

Il primo è quello di concedere alla API management autorizzazione per ottenere un certificato.

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

Con la descrizione sopra, specificare l' Managed Id di API Management e concedere l'autorizzazione. Concedi get secrets e certificates .

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

Il secondo è il permesso di importare il certificato 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 questo articolo useremo l' Azure CLI di Azure CLI per importare il certificato in Key Vault . Pertanto, è necessario concedere l'autorizzazione di importazione all'esecutore dell'interfaccia della Azure CLI comando di Azure CLI (entità service principal o utente). Specificare l'entità service principal destinazione o l' object ID utente in commanderObjectId e concedere l'autorizzazione import ai certificates .

2. Importare il certificato in Key Vault

Successivamente, importare il certificato in Key Vault . Qui, usiamo i comandi Azure CLI comando di Azure CLI .

powershell
1az keyvault certificate import --file $certFile --name $secretName --vault-name $keyVaultName --password $certPass
  • --file : percorso del file del certificato. Formato .pfx .
  • --name : nome della risorsa segreta di Key Vault per l'archiviazione del certificato.
  • --vault-name : il nome del Key Vault in cui è archiviato il certificato.
  • --password : password del certificato

Qui, se si specifica il Key Vault creato in precedenza, il certificato verrà importato. Esegui il comando sopra con l'autorità dell'esecutore che ha dato l'autorizzazione all'importazione.

3. Distribuire un dominio personalizzato per la API Management

Infine, ridistribuire 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}

Sembra simile a quello che abbiamo distribuito in precedenza, ad eccezione della parte hostnameConfigurations . Era un array vuoto perché non abbiamo applicato un dominio personalizzato in precedenza, ma questa volta contiene le impostazioni del dominio personalizzato.

  • type : il tipo di servizio per applicare un dominio personalizzato. Esistono quattro tipi: Proxy , Portal , Scm e Management .
  • hostName : FQDN dominio personalizzato
  • keyVaultId : uri Key Vault da cui la API Management ottiene il certificato

Specifichiamo Proxy per tipo. Questo è il tipo quando si applica un dominio personalizzato al gateway API ( {api management name}.azure-api.net ). keyVaultId può essere ottenuto dalla proprietà secretUtiWithVersion come descritto sopra.

Script generale

Infine, ecco uno script che distribuisce tutti i modelli sopra. Modificarli in modo appropriato in base all'ambiente 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}

Sommario

Questo articolo ha descritto come applicare un dominio personalizzato di API Management utilizzando il ARM Template .

  1. Distribuire Key Vault
  2. Importa certificati in Key Vault
  3. Applica dominio personalizzato a API Management

Abbiamo applicato correttamente un dominio personalizzato utilizzando i passaggi precedenti.

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

Condividi:

Articoli correlati

Applicazione Android CI/CD con Flutter
Software

Applicazione Android CI/CD con Flutter

Scopri come costruire pipeline CI/CD per app Android con Flutter. Basato su GitHub Actions, senza usare fastlane.

mark241