Atribuir nomes de domínio personalizados aos nomes de host MQTT e HTTP do namespace Event Grid

Artigo
05/21/2024

O namespace Grade de Eventos recebe automaticamente um nome de host HTTP no momento da criação. Se o MQTT estiver habilitado no namespace, o nome do host MQTT também será atribuído ao namespace. Seus clientes usam esses nomes de host para se comunicar com o namespace Event Grid.

Você pode atribuir seus nomes de domínio personalizados aos nomes de host MQTT e HTTP do namespace Event Grid, juntamente com os nomes de host padrão. As configurações de domínio personalizadas não só ajudam você a atender aos seus requisitos de segurança e conformidade, mas também eliminam a necessidade de modificar seus clientes que já estão vinculados ao seu domínio.

Pré-requisitos

Para usar domínios personalizados para namespaces, você precisa ter os seguintes pré-requisitos:

Domínio personalizado que você possui e pode modificar seus registros DNS (Sistema de Nomes de Domínio). Para modificar os registos DNS, precisa de aceder ao registo DNS do seu fornecedor de domínio, como a GoDaddy.
Certificado SSL (Secure Sockets Layer) para seu domínio personalizado de uma CA pública ou privada.
Conta do Azure Key Vault para hospedar o certificado SSL para seu domínio personalizado.

Etapas de alto nível

Para usar domínios personalizados para namespaces, siga estas etapas:

Adicione entradas DNS para apontar seu domínio personalizado para o ponto de extremidade do namespace Event Grid.
Habilite a identidade gerenciada em seu namespace da Grade de Eventos.
Crie uma conta do Cofre da Chave do Azure que hospede o certificado do servidor para seu domínio personalizado.
Adicione atribuição de função no Cofre de Chaves do Azure para a identidade gerenciada do namespace.
Associe seu namespace de Grade de Eventos ao domínio personalizado, especificando seu nome de domínio personalizado, nome de certificado e referência de instância do cofre de chaves.
O namespace Event Grid gera um registro TXT que você usa para provar a propriedade do domínio personalizado.
Comprove a propriedade do seu domínio criando um registro TXT com base no valor que a Grade de Eventos gerou na etapa anterior.
A Grade de Eventos valida os registros TXT do domínio personalizado antes de ativar o domínio personalizado para uso dos clientes.
Seus clientes podem se conectar ao namespace Grade de Eventos por meio do domínio personalizado.

Limitações

A configuração de domínio personalizada é exclusiva por região em nomes de host MQTT e HTTP.
A configuração de domínio personalizada não pode ser idêntica para os nomes de host MQTT e HTTP no mesmo namespace.
A configuração de domínio personalizada não pode entrar em conflito com nenhum nome de host MQTT ou HTTP para qualquer namespace na mesma região.

Adicionar entradas DNS

Crie registos DNS no seu domínio para apontar para o nome de anfitrião do seu espaço de nomes da Grelha de Eventos ao qual pretende associar o seu domínio. Para saber mais, consulte Configurando um nome de domínio personalizado para um serviço de nuvem do Azure.

Seu nome de host HTTP para seu namespace está no seguinte formato: <namespace name>.centraluseuap-1.eventgrid.azure.net

Seu nome de host MQTT para seu namespace está no seguinte formato: <namespace name>.centraluseuap-1.ts.eventgrid.azure.net

Habilite a identidade gerenciada em seu namespace da Grade de Eventos

O namespace usa a identidade gerenciada para acessar sua instância do Azure Key Vault para obter o certificado do servidor para seu domínio personalizado. Use o seguinte comando para habilitar a identidade gerenciada atribuída pelo sistema em seu namespace de Grade de Eventos:

az eventgrid namespace update --resource-group <resource group name> --name <namespace name> --identity "{type:systemassigned}"

Para obter informações sobre como configurar identidades atribuídas pelo sistema e pelo usuário usando o portal do Azure, consulte Habilitar identidade gerenciada para um namespace de Grade de Eventos.

Criar uma conta do Azure Key Vault e carregar o certificado do servidor

Use o seguinte comando para criar uma conta do Azure Key Vault:

az keyvault create --name "<your-unique-keyvault-name>" --resource-group "<resource group name>" --location "centraluseaup"

Use o seguinte comando para importar um certificado para o Cofre da Chave do Azure
```
az keyvault certificate import --vault-name "<your-key-vault-name>" -n "<cert name>" -f "<path to your certificate pem file> " 
```
Nota

Seu certificado deve incluir o nome de domínio no nome alternativo de assunto para DNS. Para obter mais informações, consulte Tutorial: Importar um certificado no Cofre de Chaves do Azure.

Adicionar atribuição de função no Cofre da Chave do Azure para a identidade gerenciada do namespace

Você precisa fornecer acesso ao namespace para acessar sua conta do Azure Key Vault usando as seguintes etapas:

Obter ID principal de identidade gerenciada do sistema de namespace de Grade de Eventos usando o seguinte comando

$principalId=(az eventgrid namespace show --resource-group <resource group name> --name <namespace name> --query identity.principalId -o tsv)

Obtenha sua ID de recurso do cofre da Chave do Azure.

$keyVaultResourceId=(az keyvault show --resource-group <resource group name> --name <your key vault name> --query id -o tsv)

Adicione atribuição de função no Cofre da Chave para a identidade gerenciada do namespace.
```
az role assignment create --role "Key Vault Certificate User" --assignee $principalId --scope $keyVaultResourceId 
```
Para obter mais informações sobre o acesso ao Cofre da Chave e a experiência do portal, consulte Fornecer acesso a chaves, certificados e segredos do Cofre da Chave com um controle de acesso baseado em função do Azure.

Associe seu namespace de Grade de Eventos ao domínio personalizado

Nesta etapa, você associa seu domínio personalizado não verificado ao namespace, mas não pode usá-lo até provar sua propriedade do domínio personalizado na próxima etapa.

Utilizar o portal do Azure

Use as seguintes etapas para adicionar seus domínios personalizados:

Navegue até o namespace da Grade de Eventos no portal do Azure
Na página Namespace da Grade de Eventos , selecione Domínios personalizados no menu de navegação esquerdo.
Na página Domínios personalizados, selecione + Domínio personalizado.
Na página Adicionar domínio personalizado, especifique valores para as seguintes propriedades:
1. Nome de domínio: o nome de domínio totalmente qualificado a ser atribuído a um dos nomes de host do namespace da Grade de Eventos.
2. Tipo de nome de host associado: o tipo de nome de host padrão que deve ser associado ao seu nome de domínio personalizado.
3. URL do Certificado: o Identificador de Certificado do certificado do servidor no Cofre da Chave do Azure. Inclua apenas o identificador base do certificado excluindo o último segmento do Identificador do certificado. Em vez disso, você pode escolher Selecionar um certificado usando um cofre de chaves para selecionar o certificado e o cofre de chaves de suas assinaturas.
4. Identidade gerenciada: a identidade gerenciada usada para autenticar com o Cofre da Chave para acessar o certificado do servidor que foi criado.
5. Selecione Adicionar
Salve os registros TXT como você precisa usar esses valores para provar sua propriedade de domínio personalizado.

Exemplo de CLI do Azure

Use o comando a seguir para atualizar seu namespace com a configuração de domínio personalizada. O objeto a seguir inclui duas configurações diferentes customDomains : a configuração em topicSpacesConfiguration é atribuída ao seu ponto de extremidade MQTT e a configuração em topicsConfiguration é atribuída ao seu ponto de extremidade HTTP.

Nota

Cada configuração de domínio personalizado deve ser exclusiva dentro da mesma região.

az resource create --resource-type Microsoft.EventGrid/namespaces --id /subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/namespaces/<Namespace Name> --is-full-object --properties @./resources/NS.json

NS.json

{
    "properties": {
        "topicsConfiguration": {
            "hostname": "HOSTNAME",
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.HTTPDOMAINNAME.com",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        },
        "topicSpacesConfiguration": {
            "state": " Enabled",
            "routeTopicResourceId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.EventGrid/namespaces/NAMESPACENAME/topics/TOPICNAME",
            "hostname": "NAMESPACENAME.westus2-1.ts.eventgrid.azure.net",
            "routingIdentityInfo": {
                "type": "None"
            },
            "customDomains": [
                {
                    "fullyQualifiedDomainName": " www.MQTTDOMAINNAME.com ",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": "/subscriptions/SUBSCRIPTIONNAME/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        }
    }
}

Substitua os seguintes espaços reservados por valores apropriados, salve-os em um arquivo chamado NS.jsone execute o comando CLI.

Espaço reservado	Description
`HOSTNAME`	Você pode obter o nome do host na página Visão geral do namespace Grade de Eventos no portal do Azure.
`NAMESPACENAME`	Nome do namespace Event Grid.
`TOPICNAME`	Nome do tópico no namespace.
`HTTPDOMAINNAME`	Nome do domínio HTTP.
`MQTTDOMAINNAME`	Nome do domínio MQTT.
`SUBSCRIPTIONID`	ID da subscrição do Azure.
`RESOURCEGROUPNAME`	Nome do grupo de recursos do Azure.
`KEYVAULTNAME`	Nome do cofre de chaves.
`CERTIFICATENAME`	Nome do certificado.

O tipo de identidade (type) pode ser ou UserAssignedSystemAssigned . Se UserAssigned estiver selecionado, especifique a identidade atribuída ao usuário usando a userAssignedIdentity propriedade.

A resposta a esta operação inclui as informações de DNS na forma das seguintes propriedades: expectedTxtRecordName e expectedTxtRecordValue. Salve essas informações, pois você precisa usar esses valores para provar sua propriedade de domínio personalizado. Aqui está um exemplo de resposta:

{
    "properties": {
        "topicsConfiguration": {
            "hostname": "HOSTNAME",
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.HTTPDOMAINNAME.com",
                    "validationState": "Pending",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    },
                    "expectedTxtRecordName": "_eg. www.contoso-http.com",
                    "expectedTxtRecordValue": "<random string>"
                }
            ]
        },
        "topicSpacesConfiguration": {
            "state": " Enabled",
            "routeTopicResourceId": " /subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.EventGrid/namespaces/MSNS/topics/TOPICNAME",
            "hostname": "HOSTNAME",
            "routingIdentityInfo": {
                "type": "None"
            },
            "customDomains": [
                {
                    "fullyQualifiedDomainName": " www.MQTTDOMAINNAME.com ",
                    "validationState": "Pending",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": "/subscriptions/SUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    },
                    "expectedTxtRecordName": "_eg. www.contoso-mqtt.com",
                    "expectedTxtRecordValue": "<random string>"
                }
            ]
        }
    }
}

Comprove a propriedade do seu domínio personalizado

Para provar a propriedade do seu domínio, siga estes passos:

Adicione as informações de DNS.

Volte ao seu registrador de domínios e crie um novo registro TXT para seu domínio com base nas informações de DNS copiadas da etapa anterior. A criação deste TXT para o seu domínio verifica a propriedade do seu nome de domínio. Defina o tempo de vida (TTL) para 3.600 segundos (60 minutos) e, em seguida, salve o registro.

Verifique o seu nome de domínio personalizado.

Para usar o portal do Azure, siga estas etapas para validar seus domínios personalizados:
1. Na página Domínios personalizados, selecione Validar domínios.
2. Na página Validar domínios, selecione Validar.

Use o comando a seguir para atualizar seu namespace com uma configuração de domínio personalizada idêntica. Este comando aciona a validação da propriedade do domínio personalizado. Os registros DNS devem se propagar antes que você possa verificar o domínio e o tempo de propagação das configurações de DNS depende do registrador de domínios.

Na resposta ao comando, verifique se o validationState é Approved.

az resource create --resource-type Microsoft.EventGrid/namespaces --id /subscriptions/<Subscription ID>/resourceGroups/<Resource Group>/providers/Microsoft.EventGrid/namespaces/<Namespace Name> --is-full-object --properties @./resources/NS.json

NS.json:

{
    "properties": {
        "topicsConfiguration": {
            "hostname": "HOSTNAME",
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.HTTPDOMAINNAME.com",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": " /subscriptions/AZURESUBCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        },
        "topicSpacesConfiguration": {
            "state": " Enabled",
            "routeTopicResourceId": " /subscriptions/AZURESUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.EventGrid/namespaces/NAMESPACENAME/topics/TOPICNAME",
            "hostname": "HOSTNAME",
            "routingIdentityInfo": {
                "type": "None"
            },
            "customDomains": [
                {
                    "fullyQualifiedDomainName": "www.MQTTDOMAINNAME.com ",
                    "identity": {
                        "type": "SystemAssigned"
                    },
                    "certificateInfo": {
                        "keyVaultArmId": "/subscriptions/AZURESUBSCRIPTIONID/resourceGroups/RESOURCEGROUPNAME/providers/Microsoft.KeyVault/vaults/KEYVAULTNAME",
                        "certificateName": "CERTIFICATENAME"
                    }
                }
            ]
        }
    }
}

Partilhar via