Atribuir nomes de domínio personalizados aos nomes de host MQTT e HTTP do namespace da Grade de Eventos

Artigo
05/21/2024

O namespace da 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 da Grade de Eventos.

Você pode atribuir seus nomes de domínio personalizados aos nomes de host MQTT e HTTP do namespace da Grade de Eventos, juntamente com os nomes de host padrão. As configurações de domínio personalizadas não só ajudam você a atender aos 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 registros DNS, você precisa de acesso ao registro DNS para seu provedor de domínio, como o GoDaddy.
Certificado de protocolo SSL (Secure Sockets Layer) para seu domínio personalizado de uma AC 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 da Grade de Eventos.
Habilite a identidade gerenciada no namespace da Grade de Eventos.
Crie uma conta do Azure Key Vault que hospeda o certificado do servidor para seu domínio personalizado.
Adicione a atribuição de função no Azure Key Vault para a identidade gerenciada do namespace.
Associe o namespace da Grade de Eventos ao domínio personalizado, especificando o nome de domínio personalizado, o nome do certificado e a referência da instância do cofre de chaves.
O namespace da Grade de Eventos gera um registro TXT que você usa para provar a propriedade do domínio personalizado.
Prove sua propriedade de domínio criando um registro TXT com base no valor gerado pela Grade de Eventos na etapa anterior.
A Grade de Eventos valida os registros TXT do domínio personalizado antes de ativar o domínio personalizado para uso de seus clientes.
Seus clientes podem se conectar ao namespace da Grade de Eventos por meio do domínio personalizado.

Limitações

A configuração de domínio personalizado é exclusiva por região em nomes de host MQTT e HTTP.
A configuração de domínio personalizado não pode ser idêntica para os nomes de host MQTT e HTTP no mesmo namespace.
A configuração de domínio personalizado 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 registros DNS em seu domínio para apontar para o nome do host do namespace da Grade de Eventos ao qual você deseja associar seu domínio. Para saber mais, consulte Configurar 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

Habilitar a identidade gerenciada no 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 no namespace da 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 da Grade de Eventos.

Criar uma conta do Azure Key Vault e carregar seu 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 comando a seguir para importar um certificado para o Azure Key Vault
```
az keyvault certificate import --vault-name "<your-key-vault-name>" -n "<cert name>" -f "<path to your certificate pem file> " 
```
Observação

Seu certificado precisa incluir o nome de domínio no Nome Alternativo do Titular do DNS. Para obter mais informações, consulte Tutorial: Importar um certificado no Azure Key Vault.

Adicionar uma atribuição de função no Azure Key Vault para a identidade gerenciada do namespace

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

Obtenha a ID da entidade de segurança da identidade gerenciada pelo sistema do namespace da Grade de Eventos usando o comando a seguir

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

Obtenha sua ID de recurso do Azure Key Vault.

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

Adicione a atribuição de função no Key Vault 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 Key Vault e a experiência do portal, consulte Fornecer acesso a chaves, certificados e segredos do Key Vault com um controle de acesso baseado em função do Azure.

Associar o namespace da 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.

Usar 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 à esquerda.
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 Azure Key Vault. Inclua apenas o identificador base do certificado excluindo o último segmento do Identificador de Certificado. 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 Key Vault para acessar o certificado do servidor que foi criado.
5. Selecione Adicionar
Salve os registros TXT, pois você precisa usar esses valores para provar sua propriedade de domínio personalizada.

Exemplos 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 de customDomains diferentes: a configuração em topicSpacesConfiguration é atribuída ao ponto de extremidade MQTT e a configuração em topicsConfiguration é atribuída ao seu ponto de extremidade HTTP.

Observação

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 espaços reservados a seguir por valores apropriados, salve-os em um arquivo nomeado NS.json e execute o comando da CLI.

Place holder	Descrição
`HOSTNAME`	Você pode obter o nome do host na página Visão geral do namespace da Grade de Eventos no portal do Azure.
`NAMESPACENAME`	Nome do namespace da Grade de Eventos.
`TOPICNAME`	Nome do tópico no namespace.
`HTTPDOMAINNAME`	Nome do domínio HTTP.
`MQTTDOMAINNAME`	Nome do domínio MQTT.
`SUBSCRIPTIONID`	Id de assinatura 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 SystemAssigned ou UserAssigned. Se UserAssigned estiver selecionado, especifique a identidade atribuída pelo usuário usando a propriedade userAssignedIdentity.

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 personalizada. Veja abaixo 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>"
                }
            ]
        }
    }
}

Provar sua propriedade de domínio personalizada

Para provar sua propriedade de domínio, siga estas etapas:

Adicione as informações de DNS.

Volte para o 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 desse TXT para seu domínio verifica a propriedade do seu nome de domínio. Defina o tempo de vida útil (TTL) como 3.600 segundos (60 minutos) e salve o registro.

Verifique 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. Esse comando dispara a validação da propriedade de domínio personalizada. Os registros DNS devem ser propagados antes de verificar o domínio e o tempo de propagação das configurações de DNS depende do registrador de domínio.

Na resposta ao seu comando, verifique se 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"
                    }
                }
            ]
        }
    }
}

Compartilhar via