Aplicar um domínio personalizado ao Gerenciamento de API do Azure

📅👤mark241⏱️3 min
SoftwareAzureAPI Management
Compartilhar:

Azure API Management é uma maneira rápida de criar um gateway de API moderno e consistente para os serviços de back-end existentes [^1]. Este artigo descreve como aplicar um domínio personalizado ao API Management . Além disso, explicaremos como habilitar o SSL com seu próprio certificado. Todos os recursos são implantados com o ARM Template [^3] ou a Azure CLI , para que você possa construir pipelines de CI / CD com eles.

1. Implante o cofre de chaves

Primeiro, implante o Key Vault para manter os 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}

O modelo acima contém os recursos do Key Vault e de API Management . Primeiro, vamos dar uma olhada no 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}

Aqui está uma breve explicação de por que criamos o API Management primeiro. Na implantação do Key Vault descrita abaixo, você concede acesso de leitura do API Management ao Key Vault . É para o API Management obter o certificado armazenado no Key Vault . API Management e seu Managed Id devem existir antes que esta autorização possa ser concedida. Para mais informações sobre o Managed Id , consulte o documento oficial [^4]. É um ID para identificar o API Management , e o gerenciamento de autoridade é realizado usando esse ID.

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

No modelo acima, o Managed Id para API Management foi gerado. Veja a documentação oficial [^2] para outros detalhes.

A seguir, vejamos os recursos do 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}

O ponto principal dos recursos do Key Vault é gerenciar os direitos de acesso com o accessPolicy . Você verá dois destinos listados na 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}

O primeiro é conceder ao API management permissão para obter um certificado.

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

Com a descrição acima, especifique o Managed Id do Managed Id de API Management e conceda a autoridade. Grant get a secrets e certificates .

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

A segunda é a permissão para importar o certificado para o 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}

Neste artigo, usaremos a Azure CLI do Azure CLI para importar o certificado para o Key Vault . Portanto, você precisa conceder permissão de importação ao executor da Azure CLI do Azure CLI ( service principal ou usuário do service principal ). Especifique o service principal destino ou o object ID usuário em commanderObjectId e conceda autoridade de import aos certificates .

2. Importe o certificado para o Key Vault

Em seguida, importe o certificado para o Key Vault . Aqui, vamos usar comandos da Azure CLI .

powershell
1az keyvault certificate import --file $certFile --name $secretName --vault-name $keyVaultName --password $certPass
  • --file : caminho do arquivo de certificado. formato .pfx .
  • --name : nome do recurso secreto do Key Vault para armazenar o certificado.
  • --vault-name : o nome do cofre de chaves que armazena o certificado.
  • --password : senha do certificado

Aqui, se você especificar o Key Vault você criou anteriormente, o certificado será importado. Execute o comando acima com a autoridade do executor que deu a autoridade de importação.

3. Implante um domínio personalizado para API Management

Por fim, reimplemente o 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}

Isso parece semelhante ao que implementamos anteriormente, exceto na parte hostnameConfigurations . Era uma matriz vazia porque não aplicamos um domínio personalizado anteriormente, mas desta vez ele contém as configurações do domínio personalizado.

  • type : o tipo de serviço para aplicar o domínio personalizado. Existem quatro tipos: Proxy , Portal , Scm e Management .
  • hostName : domínio personalizado FQDN
  • keyVaultId : keyVaultId Key Vault partir do qual o API Management obtém o certificado

Vamos especificar Proxy para o tipo. Esse é o tipo ao aplicar um domínio personalizado ao API Gateway ( {api management name}.azure-api.net ). keyVaultId pode ser obtido pela propriedade secretUtiWithVersion conforme descrito acima.

Script Geral

Finalmente, aqui está um script que implanta todos os modelos acima. Altere-os adequadamente de acordo com o seu ambiente 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}

Sumário

Este artigo descreveu como aplicar um domínio personalizado do API Management usando o ARM Template .

  1. Implantar o Key Vault
  2. Importar certificados para o Key Vault
  3. Aplicar domínio personalizado ao API Management

Aplicamos com êxito um domínio personalizado usando as etapas acima.

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

Compartilhar:

Artigos relacionados

Aplicativo Android CI/CD com Flutter
Software

Aplicativo Android CI/CD com Flutter

Aprenda a construir pipelines CI/CD para apps Android com Flutter. Baseado em GitHub Actions, sem usar fastlane.

mark241