Aplicar un dominio personalizado a Azure API Management

📅👤mark241⏱️3 min
SoftwareAzureAPI Management
Compartir:

Azure API Management es una forma rápida de crear una puerta de enlace API coherente y moderna para los servicios de back-end existentes [^1]. Este artículo describe cómo aplicar un dominio personalizado a API Management . Además, explicaremos cómo habilitar SSL con su propio certificado. Todos los recursos se implementan con la ARM Template [^3] o la Azure CLI , para que pueda construir canalizaciones de CI / CD con ellos.

1. Implementar Key Vault

Primero, implemente Key Vault para guardar los certificados.

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}

La plantilla anterior contiene recursos de Key Vault y API Management . Primero, echemos un vistazo 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}

Aquí hay una breve explicación de por qué creamos API Management primero. En la implementación de Key Vault descrita a continuación, usted otorga acceso de lectura de API Management a Key Vault . Esto es para que API Management obtenga el certificado almacenado en Key Vault . API Management y su Managed Id deben existir antes de que se pueda otorgar esta autorización. Para obtener más información sobre Managed Id , consulte el documento oficial [^4]. Es una ID para identificar la API Management , y la administración de autoridad se realiza usando esta ID.

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

En la parte anterior de la plantilla, se ha generado el Managed Id para la Managed Id de API Management . Consulte la documentación oficial [^2] para otros detalles.

A continuación, echemos un vistazo a los recursos 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}

El punto Key Vault recursos de Key Vault es administrar los derechos de acceso con accessPolicy . Verá dos objetivos enumerados en 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}

El primero es otorgar permiso a la API management para obtener un certificado.

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

Con la descripción anterior, especifique el Managed Id la Managed Id de API Management y otorgue la autorización. Concede get a secrets y certificates .

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

El segundo es el permiso para importar el certificado en 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}

En este artículo usaremos la Azure CLI para importar el certificado en Key Vault . Por lo tanto, debe otorgar permiso de importación al ejecutor de la Azure CLI ( service principal o usuario). Especifique el service principal destino o el object ID usuario en commanderObjectId y otorgue autorización de import a los certificates .

2. Importe el certificado a Key Vault

A continuación, importe el certificado en Key Vault . Aquí, usemos los comandos de la Azure CLI .

powershell
1az keyvault certificate import --file $certFile --name $secretName --vault-name $keyVaultName --password $certPass
  • --file : ruta del archivo de certificado. formato .pfx .
  • --name : nombre del recurso secreto de Key Vault para almacenar el certificado.
  • --vault-name : el nombre de Key Vault que almacena el certificado.
  • --password : contraseña del certificado

Aquí, si especifica el Key Vault que creó anteriormente, se importará el certificado. Ejecute el comando anterior con la autoridad del ejecutor que le ha otorgado la autoridad de importación.

3. Implemente un dominio personalizado para la API Management

Finalmente, vuelva a implementar 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}

Esto parece similar a lo que implementamos anteriormente, excepto por la parte hostnameConfigurations . Era una matriz vacía porque no aplicamos un dominio personalizado anteriormente, pero esta vez contiene la configuración del dominio personalizado.

  • type : El tipo de servicio para aplicar un dominio personalizado. Hay cuatro tipos: Proxy , Portal , Scm y Management .
  • hostName : dominio personalizado FQDN
  • keyVaultId : Key Vault uri de donde API Management obtiene el certificado

Especifiquemos Proxy para el tipo. Este es el tipo cuando se aplica un dominio personalizado a API Gateway ( {api management name}.azure-api.net ). keyVaultId puede obtenerse mediante la propiedad secretUtiWithVersion como se describe anteriormente.

Guión general

Finalmente, aquí hay un script que implementa todas las plantillas anteriores. Por favor cámbielos adecuadamente de acuerdo con su entorno de 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}

Resumen

Este artículo describe cómo aplicar un dominio personalizado de API Management usando ARM Template .

  1. Implementar Key Vault
  2. Importar certificados a Key Vault
  3. Aplicar dominio personalizado a API Management

Hemos aplicado con éxito un dominio personalizado siguiendo los pasos anteriores.

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

Compartir:

Artículos relacionados

Aplicación de Android CI/CD con Flutter
Software

Aplicación de Android CI/CD con Flutter

Aprenda a construir pipelines CI/CD para apps Android con Flutter. Basado en GitHub Actions, sin usar fastlane.

mark241