Guia de Configuração do HProMail no Microsoft 365

Objetivo e pré-requisitos

Este guia configura o sistema HPro para enviar e-mails pelo Microsoft 365 usando OAuth (Tenant ID, Client ID e Client Secret), por meio de um aplicativo chamado HProMail registrado no tenant do cliente.

Pré-requisitos

• Conta com função Administrador Global no tenant do cliente (ou Administrador de Aplicativos + Administrador do Exchange).

• Computador Windows com PowerShell e acesso à internet.

• Lista das caixas de e-mail que vão enviar pelo sistema.

Valores que serão anotados ao longo do guia

Atenção: existem dois "ID de objeto" diferentes para o HProMail. O que é usado neste guia é sempre o de Aplicativos corporativos, nunca o de Registros de aplicativo.

Parte 1: Registro do aplicativo no Entra

1. Acesse o Centro de administração do Microsoft Entra (entra.microsoft.com) com a conta de administrador do cliente.

2. Vá em Entra ID > Registros de aplicativo e clique em + Novo registro.

3. Preencha:
   ● Nome: HProMail
   ● Tipos de conta com suporte: Somente contas neste diretório organizacional (locatário único)
   URI de redirecionamento: deixe em branco

4. Clique em Registrar.

5. Na Visão geral do aplicativo, anote:
   ● ID do aplicativo (cliente) → Client ID
   ● ID do diretório (locatário) → Tenant ID

6. Agora pegue o ID de objeto que será usado no PowerShell: vá em Entra ID > Aplicativos corporativos > Todos os aplicativos, abra o HProMail, clique em Propriedades e anote o ID de objeto.

Não use o "ID de objeto" que aparece na Visão geral de Registros de aplicativo. Ele é outro número e o comando New-ServicePrincipal da Parte 5 falha com o erro AADServicePrincipalNotFound.

Parte 2: Criar o Client Secret

O Client Secret é ••• no Registro de aplicativo. A tela de Aplicativos corporativos não tem essa opção.

1. Vá em Entra ID > Registros de aplicativo > Todos os aplicativos e abra o HProMail.

2. No menu do aplicativo, em Gerenciar, clique em Certificados e segredos.

3. Na aba Segredos do cliente, clique em + Novo segredo do cliente.

4. Preencha a Descrição (ex.: Sistema HPro), escolha a validade e clique em Adicionar.

5. Copie imediatamente o conteúdo da coluna Valor. Esse é o Client Secret.

O Client Secret é o campo Valor, e não o ID secreto. O Valor só aparece completo logo após a criação; se for perdido, crie um novo segredo.

Anote também a data da coluna Expira em. Quando o segredo vencer, o envio para em todas as caixas do tenant.

Parte 3: Permissões de API

1. Ainda no Registro de aplicativo do HProMail, clique em Permissões de APIs.

2. Clique em + Adicionar uma permissão.

3. Abra a aba APIs que minha organização usa e pesquise por Office 365 Exchange Online.

4. Escolha Permissões de aplicativo e marque:
   ● SMTP.SendAsApp (obrigatória para o envio)
   ● IMAP.AccessAsApp
   ● POP.AccessAsApp

5. Clique em Adicionar permissões.

6. Clique em Conceder consentimento do administrador para <empresa> e confirme.

7. Verifique se todas as permissões mostram o status com o check verde.

● As permissões são do Office 365 Exchange Online, não do Microsoft Graph. Não é necessário adicionar Mail.Send.

● IMAP e POP permitem que o aplicativo leia as caixas liberadas. Se o sistema só envia e-mails, deixe apenas SMTP.SendAsApp para reduzir o risco caso o Client Secret vaze.

Parte 4: Habilitar SMTP Autenticado na caixa

O envio por OAuth usa o mesmo SMTP do Microsoft 365, mudando apenas a forma de login. Por isso o SMTP Autenticado precisa continuar ativado em cada caixa que envia pelo sistema.

1. Acesse o Centro de administração do Microsoft 365 (admin.microsoft.com).

2. Vá em Usuários > Usuários ativos e abra o usuário da caixa de envio.

3. Na aba Email, clique em Gerenciar aplicativos de email.

4. Confirme que SMTP autenticado está marcado.

5. Clique em Salvar alterações.

Repita para cada caixa que vai enviar pelo sistema.

Parte 5: Registro no Exchange via PowerShell

5.1 Instalar o módulo do Exchange Online (somente na primeira vez)

1. Abra o PowerShell como Administrador e execute:

Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser

2. Se aparecer a pergunta sobre repositório não confiável (PSGallery), responda S (Sim) ou A (Sim para Todos).

3. Se aparecer erro informando que a execução de scripts está desabilitada, execute o comando abaixo, responda S e repita a instalação:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

5.2 Conectar no Exchange Online

1. Import-Module ExchangeOnlineManagement

2. Connect-ExchangeOnline -UserPrincipalName admin@dominiodocliente.com.br

3. Abrirá uma janela de login da Microsoft. Entre com a conta de administrador do tenant do cliente. Após o login, o PowerShell volta ao prompt sem mensagem de erro.

5.3 Registrar o aplicativo no Exchange

Este comando é executado uma vez por tenant.

New-ServicePrincipal -AppId "CLIENT_ID" -ObjectId "ID_DE_OBJETO_APLICATIVO_CORPORATIVO" -DisplayName "HProMail"

● CLIENT_ID: ID do aplicativo (cliente).
● ID_DE_OBJETO_APLICATIVO_CORPORATIVO: ID de objeto de Aplicativos corporativos > HProMail > Propriedades(Parte 1, passo 6).

Para confirmar o registro:

Get-ServicePrincipal | Format-Table DisplayName, AppId, ObjectId

O HProMail deve aparecer com o mesmo AppId e ObjectId usados no comando.

5.4 Dar permissão na caixa de envio

Execute para cada caixa que vai enviar e-mails pelo sistema:

Add-MailboxPermission -Identity "envio@dominiodocliente.com.br" -User "ID_DE_OBJETO_APLICATIVO_CORPORATIVO" -AccessRights FullAccess

Para confirmar a permissão na caixa:

Get-MailboxPermission -Identity "envio@dominiodocliente.com.br" | Where-Object { $_.User -notlike "NT AUTHORITY*" } | Format-Table User, AccessRights

O HProMail deve aparecer com FullAccess.

● Libere somente as caixas que enviam pelo sistema, nunca todas as caixas do tenant.

● Caixas criadas depois não recebem a permissão automaticamente: inclua este passo no checklist de criação de usuários que vão usar o sistema.

5.5 Desconectar

Disconnect-ExchangeOnline -Confirm:$false

Parte 6: Configurar no sistema HPro

1. No sistema HPro, entre no cadastro de usuário, selecione o usuário que envia e-mails e clique em Alterar. As opções de configuração de e-mail ficam nessa tela.

2. Preencha os três campos:
   ● Tenant: ID do diretório (locatário)
   ● Client ID: ID do aplicativo (cliente)
   ● Client Secret: o Valor do segredo ••• na Parte 2

3. Mantenha como estão o servidor SMTP, a porta, o e-mail e a senha já configurados.

4. Salve a configuração e repita para cada usuário que envia e-mails pelo sistema.

Exemplo de usuário configurado (campos Tenant, Client ID e Client Secret preenchidos na parte inferior da tela, em "As informações abaixo são exclusivas para envio através do Office365"):

Janela de "Informações do usuário" exibindo os campos de cadastro, definições de senha e parâmetros de e-mail padrão.

O ID de objeto não é informado no sistema. Ele é usado somente nos comandos do PowerShell da Parte 5.

Parte 7: Teste e observações

Teste

1. Aguarde cerca de 30 minutos após a Parte 5. As permissões levam um tempo para começar a valer.

2. Envie um e-mail de teste pelo sistema HPro.

3. No Entra, vá em Entra ID > Monitoramento e integridade > Logs de entrada, abra a aba Entradas de entidade de serviço e filtre por HProMail.

4. Deve aparecer uma entrada com status Sucesso no horário do envio. Se o e-mail saiu, mas não há entrada do HProMail, o sistema ainda está enviando com usuário e senha.

Observações

• Um aplicativo por tenant: cada empresa cliente precisa do seu próprio HProMail, com Client ID e Client Secret próprios.

• Novas caixas no mesmo tenant: precisam apenas da Parte 4 e do passo 5.4. Não é necessário criar outro aplicativo nem outro segredo.

• Vencimento do segredo: ••• o Client Secret antes da data de vencimento (Parte 2) e atualize o novo Valor no sistema.

• Segurança: guarde o Client Secret com o mesmo cuidado de uma senha de administrador.