Configurar e solucionar problemas de autenticação SMTP baseada em OAuth no ISE

Introdução

Este documento descreve a configuração do OAuth 2.0 no ISE para permitir a comunicação por e-mail através dos servidores SMTP do Microsoft Exchange Online Mail.

Pré-requisitos

Requisitos

A Cisco recomenda que você tenha um conhecimento básico da funcionalidade do servidor Cisco Identity Services Engine (ISE) e Simple Mail Transfer Protocol (SMTP) e da autorização OAuth.

Componentes Utilizados

ISE versão 3.5 P1 (3.2 Patch 8, 3.3 Patch 8, 3.4 Patch 4 também suporta essa funcionalidade)

Acesso ao centro de administração do Microsoft EntraID e Microsoft 365

As informações neste documento foram criadas a partir de dispositivos em um ambiente de laboratório específico. Todos os dispositivos utilizados neste documento foram iniciados com uma configuração (padrão) inicial. Se a rede estiver ativa, certifique-se de que você entenda o impacto potencial de qualquer comando.

Configurar

Esta seção descreve a configuração no Microsoft Entra ID e ISE para suportar notificações por e-mail usadas para:

• Envie notificações de alarme por email para qualquer usuário administrador interno com a inclusão de alarmes do sistema em opções de email habilitada. Para configurar o endereço de email do remetente, clique em Administração > Sistema > Configurações > Configurações do Alarme > Notificação do Alarme e digite o endereço de email para o configurado no Microsoft 365 admin center

• Os patrocinadores devem enviar uma notificação por e-mail aos convidados com suas credenciais de login e instruções de redefinição de senha. Para o fluxo de Convidado e Patrocinador, o e-mail do remetente é configurado em Centros de Trabalho > Acesso para Convidado > Configurações > Configurações de e-mail de Convidado > Endereço de e-mail 'De' padrão para o configurado no centro de administração do Microsoft 365
• Permita que os convidados recebam automaticamente suas credenciais de login depois que se registrarem com êxito e com ações a serem tomadas antes que suas contas de convidado expirem.
• Envie emails de lembrete para usuários administradores do ISE/usuários de rede interna configurados no ISE antes da data de expiração da senha.

Nós do ISE que enviam e-mails

Diagrama de Rede

Para usar OAuth com ISE, 3 etapas são necessárias:

1. Registrar o aplicativo ISE com a ID do Microsoft Entra

2. Obtenha um token de acesso do servidor de token (IDP)

3. Autentique as solicitações de conexão com o Servidor SMTP com um token de acesso.

Configurações

PASSO 1: Criar conta de e-mail do usuário

Crie uma conta de email de usuário em seu domínio registrado a partir do centro de administração do Microsoft 365. A conta de exemplo é criada aqui com o nome de usuário "no-reply" para se conectar ao aplicativo EntraID e enviar emails do ISE.

1. Navegue até Usuários > Usuários ativos e Adicionar um usuário para enviar emails do ISE.
2. Configure os conceitos básicos: adicione o nome e o sobrenome do usuário, o nome de exibição, o FQDN e a senha e clique em Avançar.
3. Selecione o local e atribua ao usuário uma licença de produto (Microsoft 365 E5 Developer), clique em Avançar

Adicionar um usuário

4. Em Configurações Opcionais, Atribua a Função Usuário (sem acesso ao centro de administração)

5. Revise e clique em Concluir adição.

6. Escolha os aplicativos onde esta conta de usuário pode acessar o email do Microsoft 365: No centro de administração do Microsoft 365, vá para Users > Ative users > selecione a conta do usuário e clique em Mail. Em Aplicativos de email > Gerenciar aplicativos de email. Verifique se Authenticated SMTP também está selecionado junto com outros aplicativos.

Gerenciar aplicativos de email

PASSO 2: Registrar aplicativo ISE na ID do Microsoft Entra

1. Entre no centro de administração do Microsoft Entra usando sua conta do MS Azure que tem uma assinatura ativa e deve ser pelo menos um Desenvolvedor de Aplicativos.
2. Navegue até Entra ID. Pesquise o serviço App registations, clique em New Registration
3. Insira um Nome significativo para seu aplicativo e, em Tipos de conta suportados, especifique quem pode usar o aplicativo, escolha "Somente locatário único - seu locatário EntraID "e clique em Registrar para concluir o registro do aplicativo.

Registrar um aplicativo

4. A página Visão Geral da aplicação é exibida. Registre a ID do aplicativo (cliente), que identifica exclusivamente seu aplicativo. Além disso, sua ID de diretório (locatário), a ser usada na configuração SMTP do ISE.

Detalhes de Registro do Aplicativo

5. Agora adicione as credenciais do Aplicativo a este Aplicativo MS Entra para autenticar-se com segurança e acessar a API da Web sem interação do usuário.

1. No aplicativo recém-registrado, navegue até Gerenciar > Certificados e segredos. Em Segredos do cliente clique em Novo segredo do cliente. Insira uma Descrição em Adicionar um segredo do cliente e defina a Duração da expiração e clique em Adicionar.
2. Anote o Valor do segredo do cliente pois os valores do segredo do cliente não podem ser exibidos, exceto imediatamente após a criação. Certifique-se de salvar o segredo quando criado antes de sair da página.
3. Anote também a data de expiração da chave.

Configuração do Segredo do Cliente de Aplicativo

6. Os aplicativos são autorizados a chamar APIs quando recebem permissões de usuários/administradores. Agora adicione permissões SMTP ao Aplicativo MS Entra.

1. No aplicativo recém-registrado, navegue até Gerenciar > permissões de API. Selecione Adicionar uma permissão.
2. Selecione a guia APIs que minha organização usa e procure por "Office 365 Exchange Online".
3. Clique em Permissões de aplicativo.
4. Para acesso SMTP, escolha a permissão SMTP.SendAsApp.
5. O consentimento do Administrador de Locatários é necessário para esta permissão. Clique em Conceder consentimento administrativo para <nome do locatário>

Atribuir permissão de API ao aplicativo

Note: User.Read Permission for Microsoft Graph is added by default (No Admin consent for the tenant) 

7. Entidades de serviço no Exchange são usadas para permitir que os aplicativos acessem as caixas de correio do Exchange por meio do fluxo de credenciais do cliente com os protocolos SMTP, POP e IMAP. 

    Assim que um administrador de locatários consentir seu aplicativo Microsoft Entra, o administrador deve registrar sua entidade de serviço de aplicativo Entra no Exchange através do Exchange Online PowerShell. Esse registro é habilitado pelo cmdlet New-ServicePrincipal.

1. Instale o Powershell, se já não estiver instalado no laptop

abc@abc-M-506L ~ % brew install --cask powershell
abc@abc-M-506L ~ % sh
sh-3.2$ brew update 
sh-3.2$ brew upgrade powershell

Instalar o Powershell

II. Para usar o cmdlet New-ServicePrincipal, instale o ExchangeOnlineManagement e conecte-se ao seu locatário como mostrado no snippet:

sh-3.2$ pwsh
PowerShell 7.5.4

PS/Users/abc> Install-Module -Name ExchangeOnlineManagement
PS/Users/abc> Import-module ExchangeOnlineManagement
PS/Users/abc> Connect-ExchangeOnline -Organization xxxxxxxx-xxxx-xxxx-xxxx-xxxxx999be76 ---->Directory (tenant) ID

Conectar-se ao Espaço do Exchange Online

III. Registro de uma entidade de serviço do aplicativo Microsoft Entra no Exchange. Use o AppID e o ObjectID [O OBJECT_ID é a ID do Objeto na página Visão Geral do nó de Aplicativo Empresarial (Portal do Azure) para o registro do aplicativo. Ele NÃO é o ID do objeto da página Visão geral do nó Registros de aplicativo. O uso da ID de objeto incorreta resulta em falha de autenticação].

PS/Users/abc> New-ServicePrincipal -AppId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxx6a953e -ObjectId b10axxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Registrar entidade de serviço de aplicativo Entra no Exchange

IV.  Verifique seu identificador da entidade de serviço registrado usando o cmdlet Get-ServicePrincipal

PS/Users/abc> Get-ServicePrincipal | fl

Verificar identificador de entidade de serviço registrado

V.  O administrador de locatários agora pode adicionar as caixas de correio específicas no locatário que pode ser acessado pelo seu aplicativo. Essa configuração é feita com o cmdlet Add-MailboxPermission.

PS/Users/abc> Add-MailboxPermission -Identity "no-reply@abcdef.onmicrosoft.com" -User b10aa0dx-xxxx-xxxx-xxxx-xxxxxxe189bb -AccessRights FullAccess

Adicionar permissão de caixa de correio para acessar o aplicativo

Seu aplicativo Microsoft Entra agora pode acessar as caixas de correio permitidas por meio dos protocolos SMTP, POP ou IMAP usando o fluxo de concessão de credenciais do cliente OAuth 2.0.

PASSO 3: Configurar a autenticação de usuário SMTP do ISE via OAuth do MS Exchange Online

Para configurar um servidor SMTP, clique no ícone Menu () e escolha Administração > Sistema > Configurações > Servidor SMTP. Configure os campos.

• Na área Configurações do servidor SMTP:
  • Servidor SMTP: smtp.office365.com
  • Porta SMTP: 587
  • Tempo limite da conexão: 60 segundos
• Na área Authentication Settings, use o switch de alternância para ativar a opção Use Authentication Settings.

Escolha MS Exchange Online OAuth: Digite esses valores para configurar o OAuth do Microsoft Exchange Online.

• No campo Nome de Usuário, insira o endereço de email completo do Nome de Usuário do Exchange Online.
• No campo ID do Cliente, insira a ID do cliente do aplicativo Azure Entra ID.
• No campo ID do Locatário, insira a ID do locatário do aplicativo Azure Entra ID.
• No campo Segredo do Cliente, insira o segredo do cliente do aplicativo Azure Entra ID.
• No campo Expiry Date, insira a data de expiração do segredo do cliente.

Os alarmes de expiração de segredo do cliente são acionados com base nesta configuração.

• Os arquivos API de Ponto de Extremidade de Token OAuth e Escopo são preenchidos automaticamente.

A configuração pode ser salva somente após a operação Testar Conexão bem-sucedida.

Êxito ao testar conexão com servidor SMTP

Note: To protect sensitive customer data, these configurations are excluded from Backup and Restore operations

Verificar

Para verificar, defina as Configurações de e-mail de convidado. Navegue até Centros de trabalho > Acesso de convidado > E-mail de convidado Configurações. Selecione Ativar notificações de e-mail para convidados e configure o Endereço de e-mail ‘De’ Padrão da conta sem resposta configurada durante a Etapa 1 da configuração e Salvar.

Alterar Configurações de Email de Convidado

Envie um e-mail de teste navegando até Centros de trabalho > Acesso de convidado > Portal e componentes > Portais de convidado > Portal de convidado autorregistrado (padrão) > Personalização da página do portal > Notificações > E-mail.

No lado direito do painel de visualização, clique em Configurações > Enviar e-mail de teste, Adicionar seu ID de e-mail e clique em Enviar.

Testar e-mail do portal de autorregistro

Seu Outlook deve receber um e-mail de uma conta sem resposta configurada na etapa 1 da verificação. Exemplo de e-mail na captura de tela.

Exemplo de e-mail recebido no Outlook

Guest.log at debug level:
2026-02-02 05:17:34,608 INFO   [admin-http-pool139][[]] cpm.guestaccess.apiservices.util.SmtpMsgRetryThreadUtil -::admin:::- sendMailMessage: Submitting Mail Job............
2026-02-02 05:17:34,608 INFO   [admin-http-pool139][[]] cpm.guestaccess.apiservices.util.SmtpMsgRetryThreadUtil -::admin:::- submitMailMsgJob: SMTP server FQDN ==> smtp.office365.com
2026-02-02 05:17:34,609 INFO   [admin-http-pool139][[]] cpm.guestaccess.apiservices.util.SmtpMsgRetryThreadUtil -::admin:::- sendMailMessage: Time taken for Submitting mail job is 1 Milli seconds.
2026-02-02 05:17:34,609 INFO   [admin-http-pool139][[]] cpm.guestaccess.apiservices.util.SmtpMsgRetryThreadUtil -::admin:::- sendMailMessage: Calling Future.get....
2026-02-02 05:17:34,609 INFO   [GUEST_ACCESS_SMTP_RETRY_THREAD][[]] cpm.guestaccess.apiservices.util.SmtpMsgRetryThreadUtil -:::::- submitMailMsgJob: Creating transport object...
2026-02-02 05:17:39,365 INFO   [GUEST_ACCESS_SMTP_RETRY_THREAD][[]] cpm.guestaccess.apiservices.util.SmtpMsgRetryThreadUtil -:::::- submitMailMsgJob: Time taken for transport.sendMessage() call is 4756 Milli Seconds.
2026-02-02 05:17:39,365 INFO   [admin-http-pool139][[]] cpm.guestaccess.apiservices.util.SmtpMsgRetryThreadUtil -::admin:::- sendMailMessage: Future.get status: success Time taken for Future.get method call is 4756 Milliseconds.

Teste também no portal do patrocinador, reenviando as credenciais do usuário ao usuário convidado pelo administrador do patrocinador.

Teste do Portal do patrocinador

Enviar credenciais para usuário Convidado

Exemplo de e-mail recebido pelo usuário convidado:

Notificação de e-mail para usuário convidado

Troubleshooting

Comece verificando se há expiração do Segredo do Cliente nos alarmes. Novos alarmes relacionados ao segredo do cliente OAuth SMTP são adicionados ao ISE.

Para Troubleshooting adicional, ative os logs de depuração nos nós PAN, PSN ou PMnT de acordo com o problema que você está solucionando.

• Componente de Log: guest-access-admin, guestaccess
• Arquivo de log: guest.log

Testar operação de conexão

2026-02-02 05:58:21,501 DEBUG [MnT-AlarmWorkerMail-Threadpool-0][[]] cpm.guestaccess.apiservices.util.SmtpSession -:::::- SMTP settings : Username : null Port : 587 timeout : 60 isSSLEnabled: false isAuthEnabled false Server: smtp.office365.com
2026-02-02 05:58:21,501 DEBUG [MnT-AlarmWorkerMail-Threadpool-0][[]] cpm.guestaccess.apiservices.util.SmtpSession -:::::- Setting MailSessionProperties
2026-02-02 05:58:21,501 DEBUG [MnT-AlarmWorkerMail-Threadpool-0][[]] cpm.guestaccess.apiservices.util.SmtpSession -:::::- Set the FQDN : sa-ise35-1.poongarg.local
2026-02-02 05:58:21,513 DEBUG [MnT-AlarmWorkerMail-Threadpool-0][[]] cpm.guestaccess.apiservices.util.SmtpSession -:::::- SMTP settings : Username : null Port : 587 timeout : 60 isSSLEnabled: false isAuthEnabled false Server: smtp.office365.com
2026-02-02 05:58:21,513 DEBUG [MnT-AlarmWorkerMail-Threadpool-0][[]] cpm.guestaccess.apiservices.util.SmtpSession -:::::- Setting MailSessionProperties
2026-02-02 05:58:21,513 DEBUG [MnT-AlarmWorkerMail-Threadpool-0][[]] cpm.guestaccess.apiservices.util.SmtpSession -:::::- Set the FQDN : sa-ise35-1.poongarg.local
2026-02-02 05:59:14,872 DEBUG [admin-http-pool136][[]] cpm.admin.guestaccess.action.SmtpServerSettingsAction -::admin:::- inside smtpServerSettings testConnection
2026-02-02 05:59:14,872 DEBUG [admin-http-pool136][[]] cpm.admin.guestaccess.action.SmtpServerSettingsAction -::admin:::- smtpServerSecureSettings testConnection
2026-02-02 05:59:15,630 DEBUG [admin-http-pool136][[]] cpm.guestaccess.apiservices.oauth.OauthTokenCache -::admin:::- Putting value in OAuth Cache (accessToken, expiry) ..
2026-02-02 05:59:15,630 DEBUG [admin-http-pool136][[]] cpm.guestaccess.apiservices.oauth.ExchangeOnlineProvider -::admin:::- Access token acquired (no caching in this method)
2026-02-02 05:59:15,630 DEBUG [admin-http-pool136][[]] cpm.guestaccess.apiservices.oauth.OauthTokenCache -::admin:::- Putting value in OAuth Cache (accessToken, expiry) ..
2026-02-02 05:59:20,146 DEBUG [admin-http-pool136][[]] cpm.guestaccess.apiservices.util.SmtpSession -::admin:::- Successfully created mail session and connected to mail server.
2026-02-02 05:59:20,146 DEBUG [admin-http-pool136][[]] cpm.admin.guestaccess.action.SmtpServerSettingsAction -::admin:::- Successfully connected to smtp.office365.com.

Salvar operação

2026-02-02 05:54:07,337 DEBUG [admin-http-pool129][[]] cpm.admin.guestaccess.action.SmtpServerSettingsAction -::admin:::- inside smtpServerSettings editSubmit
2026-02-02 05:54:07,337 DEBUG [admin-http-pool129][[]] cpm.admin.guestaccess.action.SmtpServerSettingsAction -::admin:::- smtpServerSettings in editSubmit
2026-02-02 05:54:07,339 DEBUG [admin-http-pool129][[]] cpm.admin.guestaccess.action.SmtpServerSettingsAction -::admin:::- Set SMTP Server is :smtp.office365.com
2026-02-02 05:54:07,339 DEBUG [admin-http-pool129][[]] cpm.admin.guestaccess.action.SmtpServerSettingsAction -::admin:::- Set SMTP port is :587
2026-02-02 05:54:07,339 DEBUG [admin-http-pool129][[]] cpm.admin.guestaccess.action.SmtpServerSettingsAction -::admin:::- Set Connection Timout is :60
2026-02-02 05:54:07,339 DEBUG [admin-http-pool129][[]] cpm.admin.guestaccess.action.SmtpServerSettingsAction -::admin:::- Set TLS/SSL config is :false
2026-02-02 05:54:07,339 DEBUG [admin-http-pool129][[]] cpm.admin.guestaccess.action.SmtpServerSettingsAction -::admin:::- Set Authentication config is :false
2026-02-02 05:54:07,357 DEBUG [admin-http-pool129][[]] cpm.admin.guestaccess.action.SmtpServerSettingsAction -::admin:::- SMTP server settings successfully saved

Solução de problemas de conectividade

1. Erro de GUI: Falha na conexão com smtp.office365.con.

Erro de tempo limite de conexão

2026-02-09 03:24:58,658 ERROR [admin-http-pool11][[]] cpm.guestaccess.apiservices.util.SmtpSession -::admin:::- MessagingException : com.sun.mail.util.MailConnectException: Couldn't connect to host, port: smtp.office365.com, 587; timeout 60000;
nested exception is:
java.net.SocketTimeoutException: connect timed out

Guest.log mostra o tempo limite de conexão atingido. A configuração do proxy precisa ser corrigida para resolver esse problema.

2. Erro de GUI: Identificador de locatário ou ponto de extremidade OAuth inválido - Autoexplicativo. É necessário verificar a ID do Locatário.

3. Segredo do cliente inválido - O mesmo, é necessário verificar o valor do segredo do cliente

Erro de segredo de cliente inválido

4. Endereço de E-mail Inválido- Verifique se a configuração do Princípio do Serviço está correta.

Erro de Endereço de Email Inválido

5. Não é possível encontrar um caminho de certificação válido para o Destino solicitado: Certifique-se de que os certificados da cadeia de certificados Entra ID (CA de Emissão de TLS RSA do Microsoft Azure e CA raiz do DigiCert, etc, de acordo com o pcap) estejam presentes no repositório de certificados Confiáveis do ISE e sejam Confiáveis para a função "Confiança para autenticação no ISE e comunicação Cliente-Servidor (Infraestrutura)".

Verifique todos os certificados enviados pela EntraID usando um pcap.

Falha na validação do certificado

2026-02-10 14:32:47,528 ERROR  [admin-http-pool9][[]] cpm.guestaccess.apiservices.util.SmtpSession -::admin:::- Exception : javax.mail.AuthenticationFailedException: failed to connect
2026-02-10 14:34:06,549 ERROR  [admin-http-pool9][[]] cpm.guestaccess.apiservices.oauth.ExchangeOnlineProvider -::admin:::- Error acquiring token: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
2026-02-10 14:34:28,655 ERROR  [admin-http-pool27][[]] cpm.guestaccess.apiservices.oauth.ExchangeOnlineProvider -::admin:::- Error acquiring token: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target