Appliquer un domaine personnalisé à Azure API Management

📅👤mark241⏱️3 min
GuidesAzureAPI Management
Partager :

Azure API Management est un moyen rapide de créer une passerelle API cohérente et moderne pour les services principaux existants 1. Cet article décrit comment appliquer un domaine personnalisé à la API Management . De plus, nous vous expliquerons comment activer SSL avec votre propre certificat. Toutes les ressources sont déployées avec le ARM Template 2 ou Azure CLI , afin que vous puissiez construire des pipelines CI / CD avec eux.

1. Déployer Key Vault

Tout d'abord, déployez Key Vault pour conserver les certificats.

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}

Le modèle ci-dessus contient API Management ressources Key Vault et de API Management . Jetons d'abord un œil à la 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}

Voici une brève explication de la raison pour laquelle nous avons d'abord créé la API Management . Dans le déploiement de Key Vault décrit ci-dessous, vous accordez à la API Management accès en lecture à Key Vault . Il s'agit de la API Management pour obtenir le certificat stocké dans Key Vault . API Management et son Managed Id doivent exister avant que cette autorisation puisse être accordée. Pour plus d'informations sur l' Managed Id , reportez-vous au document officiel 3. Il s'agit d'un ID permettant d'identifier la API Management et la gestion des droits est effectuée à l'aide de cet ID.

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

Dans la partie modèle ci-dessus, l' Managed Id pour la API Management a été généré. Voir la documentation officielle 4 pour plus de détails.

Ensuite, regardons les ressources de 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}

Le point Key Vault ressources Key Vault est de gérer les droits d'accès avec accessPolicy . Vous verrez deux cibles répertoriées dans 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}

La première consiste à accorder à la API management autorisation d'obtenir un certificat.

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

Avec la description ci-dessus, spécifiez l' Managed Id la Managed Id des API Management et accordez l'autorisation. Grant get aux secrets et certificates .

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

La seconde est l'autorisation d'importer le certificat dans 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}

Dans cet article, nous utiliserons l' Azure CLI pour importer le certificat dans Key Vault . Par conséquent, vous devez accorder une autorisation d'importation à l'exécuteur Azure CLI ( service principal ou utilisateur). Spécifiez le service principal cible ou l' object ID utilisateur dans commanderObjectId et accordez le droit d' import aux certificates .

2. Importez le certificat dans Key Vault

Ensuite, importez le certificat dans Key Vault . Ici, utilisons les commandes Azure CLI .

powershell
1az keyvault certificate import --file $certFile --name $secretName --vault-name $keyVaultName --password $certPass
  • --file : chemin du fichier de certificat. Format .pfx .
  • --name : nom de la ressource secrète Key Vault pour stocker le certificat.
  • --vault-name : nom du coffre de clés qui stocke le certificat.
  • --password : mot de passe du certificat

Ici, si vous spécifiez le Key Vault vous avez créé précédemment, le certificat sera importé. Exécutez la commande ci-dessus avec l'autorisation de l'exécuteur testamentaire qui a accordé l'autorisation d'importation.

3. Déployer un domaine personnalisé pour la API Management

Enfin, redéployez la 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}

Cela semble similaire à ce que nous avons déployé précédemment, à l'exception de la partie hostnameConfigurations . Il s'agissait d'un tableau vide car nous n'avons pas appliqué de domaine personnalisé plus tôt, mais cette fois, il contient les paramètres du domaine personnalisé.

  • type : type de service auquel appliquer un domaine personnalisé. Il existe quatre types: Proxy , Portal , Scm et Management .
  • hostName : nom de domaine complet du domaine personnalisé
  • keyVaultId : uri du Key Vault partir duquel la API Management obtient le certificat

Spécifions le Proxy pour le type. Il s'agit du type lors de l'application d'un domaine personnalisé à API Gateway ( {api management name}.azure-api.net ). keyVaultId peut être obtenu par la propriété secretUtiWithVersion comme décrit ci-dessus.

Script global

Enfin, voici un script qui déploie tous les modèles ci-dessus. Veuillez les modifier en fonction de votre environnement 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}

Sommaire

Cet article décrit comment appliquer un domaine personnalisé de API Management aide du ARM Template .

  1. Déployer Key Vault
  2. Importer des certificats dans Key Vault
  3. Appliquer un domaine personnalisé à la API Management

Nous avons réussi à appliquer un domaine personnalisé en suivant les étapes ci-dessus.

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 ↩

Partager :

Articles connexes