Configurazione e risoluzione dei problemi di autenticazione SMTP basata su OAuth in ISE

Introduzione

Questo documento descrive la configurazione di OAuth 2.0 in ISE per abilitare la comunicazione e-mail tramite i server SMTP Microsoft Exchange Online Mail.

Prerequisiti

Requisiti

Cisco raccomanda una conoscenza di base delle funzionalità del server Cisco Identity Services Engine (ISE) e Simple Mail Transfer Protocol (SMTP) e dell'autorizzazione OAuth.

Componenti usati

ISE versione 3.5 P1 (3.2 Patch 8, 3.3 Patch 8, 3.4 Patch 4 supporta anche questa funzionalità)

Accesso a Microsoft EntraID e Microsoft 365 admin center

Le informazioni discusse in questo documento fanno riferimento a dispositivi usati in uno specifico ambiente di emulazione. Su tutti i dispositivi menzionati nel documento la configurazione è stata ripristinata ai valori predefiniti. Se la rete è operativa, valutare attentamente eventuali conseguenze derivanti dall'uso dei comandi.

Configurazione

In questa sezione viene descritta la configurazione di Microsoft Entra ID e ISE per il supporto delle notifiche e-mail utilizzate per:

• Invia notifiche di allarme via e-mail a tutti gli utenti amministratori interni con l'opzione di inclusione degli allarmi di sistema nei messaggi e-mail abilitata. Per configurare l'indirizzo e-mail del mittente, fai clic su Amministrazione > Sistema > Impostazioni > Impostazioni allarme > Notifica allarme e digita l'indirizzo e-mail configurato in Microsoft 365 admin center

• Gli sponsor inviano una notifica via e-mail agli ospiti con le proprie credenziali di accesso e le istruzioni per reimpostare la password. Per il flusso Guest e Sponsor, l'e-mail del mittente è configurata in Centri di lavoro > Accesso Guest > Impostazioni > Impostazioni e-mail Guest > Indirizzo e-mail predefinito 'Da' a quello configurato in Microsoft 365 Admin Center
• Consentire agli utenti guest di ricevere automaticamente le credenziali di accesso dopo la registrazione e le azioni da eseguire prima della scadenza degli account guest.
• Inviare un promemoria via e-mail agli utenti amministratori di ISE o agli utenti della rete interna configurati sull'ISE prima della data di scadenza della password.

Nodi ISE per l'invio di e-mail

Esempio di rete

Per utilizzare OAuth con ISE, sono necessari 3 passaggi:

1. Registrare l'applicazione ISE con Microsoft Entra ID

2. Ottenere un token di accesso dal server dei token (IDP)

3. Autentica le richieste di connessione al server SMTP con un token di accesso.

Configurazioni

PASSAGGIO 1: Crea account di posta elettronica utente

Crea l'account di posta elettronica dell'utente nel dominio registrato dall'interfaccia di amministrazione di Microsoft 365. Qui viene creato un account di esempio con il nome utente "no-reply" per collegarsi all'applicazione EntraID e inviare e-mail da ISE.

1. Selezionare Users > Active users (Utenti attivi) e Add a user (Aggiungi utente) per inviare e-mail da ISE (ISE).
2. Configurazione delle nozioni di base: aggiungere il nome e il cognome dell'utente, il nome visualizzato, il nome di dominio completo e la password, quindi fare clic su Avanti.
3. Selezionare il percorso e assegnare una licenza per il prodotto all'utente (sviluppatore Microsoft 365 E5). Fare clic su Avanti

Aggiungi utente

4. In Impostazioni facoltative, Assegna il ruolo utente (nessun accesso all'interfaccia di amministrazione)

5. Esaminare e fare clic su Fine aggiunta.

6. Scegli le app in cui questo account utente può accedere alla posta elettronica di Microsoft 365: Nell'interfaccia di amministrazione di Microsoft 365, selezionare Utenti > Utenti attivi > selezionare l'account utente e fare clic su Posta. In App e-mail > Gestisci le app e-mail. Accertarsi che Authenticated SMTP sia selezionato anche in altre app.

Gestisci app e-mail

PASSAGGIO 2: Registra l'applicazione ISE in Microsoft Entra ID

1. Accedere all'interfaccia di amministrazione di Microsoft Entra utilizzando l'account di Microsoft Azure con la sottoscrizione attiva e che deve essere almeno uno sviluppatore di applicazioni.
2. Selezionare Entra ID. Cercare Servizio registrazioni app, quindi fare clic su Nuova registrazione
3. Immettere un nome significativo per l'app e in Tipi di account supportati specificare chi può utilizzare l'applicazione, scegliere "Solo tenant singolo-tenant EntraID "e fare clic su Registra per completare la registrazione dell'app.

Registra un'applicazione

4. Viene visualizzata la pagina Panoramica dell'applicazione. Registrare l'ID applicazione (client) che identifica in modo univoco l'applicazione. Anche il tuo ID directory (tenant), da utilizzare nella configurazione ISE SMTP.

Dettagli registrazione app

5. Aggiungere ora le credenziali dell'applicazione a questa applicazione MS Entra per autenticarsi in modo sicuro e accedere all'API Web senza interazione dell'utente.

1. Nell'applicazione appena registrata, selezionare Gestione > Certificati e segreti. Sotto i segreti client fare clic su Nuovo segreto client. Immettere una descrizione in Aggiungi segreto client e impostare la durata della scadenza e fare clic su Aggiungi.
2. Prendere nota del Valore segreto client in quanto i valori del segreto client non possono essere visualizzati, tranne che subito dopo la creazione. Assicurarsi di salvare il segreto quando viene creato prima di uscire dalla pagina.
3. Annotare inoltre la data di scadenza della chiave.

Configurazione segreto client applicazione

6. Le applicazioni sono autorizzate a chiamare le API quando ricevono autorizzazioni da utenti/amministratori. Aggiungere ora le autorizzazioni SMTP all'applicazione MS Entra.

1. Nell'applicazione appena registrata, selezionare Gestisci > autorizzazioni API. Selezionare Aggiungi autorizzazione.
2. Selezionare la scheda API utilizzate dall'organizzazione e cercare "Office 365 Exchange Online".
3. Fare clic su Autorizzazioni applicazione.
4. Per l'accesso SMTP, scegliere l'autorizzazione SMTP.SendAsApp.
5. Per questa autorizzazione è necessario il consenso dell'amministratore tenant. Fare clic su Concedi il consenso dell'amministratore per <nome tenant>

Assegna autorizzazione API all'applicazione

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

7. Le entità servizio in Exchange vengono utilizzate per consentire alle applicazioni di accedere alle cassette postali di Exchange tramite il flusso di credenziali client con i protocolli SMTP, POP e IMAP. 

    Dopo che l'amministratore tenant ha autorizzato l'applicazione Microsoft Entra, l'amministratore deve registrare l'entità del servizio dell'applicazione Entra in Exchange tramite Exchange Online PowerShell. Questa registrazione è abilitata dal cmdlet New-ServicePrincipal.

1. Installare Powershell, se non è già installato sul notebook

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

Installa Powershell

II. Per utilizzare il cmdlet New-ServicePrincipal, installare ExchangeOnlineManagement e connettersi al tenant come mostrato nel frammento:

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

Connetti al tenant di Exchange Online

III. Registrazione di un'entità servizio dell'applicazione Microsoft Entra in Exchange. Usare AppID e ObjectID [OBJECT_ID è l'ID oggetto della pagina Panoramica del nodo Applicazione enterprise (portale di Azure) per la registrazione dell'applicazione. NON corrisponde all'ID oggetto nella pagina Panoramica del nodo Registrazioni applicazioni. L'utilizzo di un ID oggetto non corretto genera un errore di autenticazione].

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

Registra entità servizio applicazione Entra in Exchange

IV.  Verificare l'identificatore dell'entità servizio registrato utilizzando il cmdlet Get-ServicePrincipal

PS/Users/abc> Get-ServicePrincipal | fl

Verifica l'identificatore dell'entità servizio registrata

V.  L'amministratore tenant può ora aggiungere le cassette postali specifiche nel tenant a cui l'applicazione può accedere. Questa configurazione viene eseguita con il cmdlet Add-MailboxPermission.

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

Aggiungi autorizzazione cassetta postale per accedere all'applicazione

L'applicazione Microsoft Entra è ora in grado di accedere alle cassette postali consentite tramite i protocolli SMTP, POP o IMAP utilizzando il flusso di concessione delle credenziali del client OAuth 2.0.

PASSAGGIO 3: Configurazione dell'autenticazione utente SMTP ISE tramite OAuth di MS Exchange Online

Per configurare un server SMTP (Simple Mail Transfer Protocol), fare clic sull'icona Menu () e scegliere Amministrazione > Sistema > Impostazioni > Server SMTP. Configurare i campi.

• Nell'area Impostazioni server SMTP:
  • Server SMTP: smtp.office365.com
  • Porta SMTP: 587
  • Timeout connessione: 60 secondi
• Nell'area Authentication Settings (Impostazioni di autenticazione), utilizzare l'interruttore toggle per abilitare l'opzione Use Authentication Settings (Usa impostazioni di autenticazione).

Scegliere MS Exchange Online OAuth: Immettere questi valori per configurare Microsoft Exchange Online OAuth.

• Nel campo Username (Nome utente), immettere l'indirizzo e-mail completo del nome utente di Exchange Online.
• Nel campo ID client, immettere l'ID client dell'applicazione Azure Entra ID.
• Nel campo ID tenant, immettere l'ID tenant dell'applicazione Azure Entra ID.
• Nel campo Segreto client, immettere il segreto client dell'applicazione Azure Entra ID.
• Nel campo Data scadenza, immettere la data di scadenza del segreto client.

In base a questa configurazione vengono attivati allarmi di scadenza del segreto client.

• I file OAuth Token Endpoint API e Scope vengono popolati automaticamente.

La configurazione può essere salvata solo dopo il completamento dell'operazione Test connessione.

Test della connessione al server SMTP riuscito

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

Verifica

Per procedere alla verifica, configurare le impostazioni e-mail del guest. Passare a Centri di lavoro > Accesso guest > Impostazioni e-mail Guest. Selezionare l'opzione Abilita notifiche via e-mail agli ospiti e configurare l'indirizzo e-mail predefinito del mittente dell'account di mancata risposta configurato durante il passaggio 1 della configurazione e del salvataggio.

Modifica impostazioni posta elettronica guest

Inviare un messaggio di posta elettronica di prova passando a Centri di lavoro > Accesso guest > Portale e componenti > Portali guest > Portale guest con registrazione automatica (impostazione predefinita) > Personalizzazione pagina portale > Notifiche > Posta elettronica.

Nel riquadro di anteprima a destra, fare clic su Impostazioni > Invia messaggio di prova, Aggiungi il tuo ID e-mail e fare clic su Invia.

Prova l'email dal portale di autoregistrazione

Outlook deve ricevere un messaggio di posta elettronica dall'account senza risposta configurato nel passaggio 1 della verifica. E-mail di esempio nello screenshot.

Esempio di messaggio di posta elettronica ricevuto in 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.

Eseguire inoltre il test dal portale dello sponsor inviando di nuovo le credenziali dell'utente all'utente guest dall'amministratore dello sponsor.

Test dal portale degli sponsor

Invia credenziali all'utente Guest

Esempio di messaggio di posta elettronica ricevuto dall'utente guest:

Notifica via e-mail all'utente guest

Risoluzione dei problemi

Iniziare con il controllo degli allarmi per la scadenza del segreto client. I nuovi allarmi relativi al segreto client SMTP OAuth vengono aggiunti in ISE.

Per ulteriori informazioni sulla risoluzione dei problemi, abilitare i registri di debug sul nodo PAN, PSN o PMnT in base al problema che si sta risolvendo.

• Componente registrazione: guest-access-admin, accesso guest
• File registro: guest.log

Test del funzionamento della connessione

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.

Operazione di salvataggio

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

Risoluzione dei problemi di connettività

1. Errore GUI: Connessione a smtp.office365.con non riuscita.

Errore di timeout della connessione

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 indica il timeout della connessione. Per risolvere il problema, è necessario correggere la configurazione proxy.

2. Errore GUI: Endpoint OAuth o identificatore tenant non valido. Autoesplicativo. Controllare l'ID tenant.

3. Segreto client non valido - Uguale, è necessario verificare il valore del segreto client

Errore segreto client non valido

4. Indirizzo e-mail non valido. Assicurarsi che la configurazione del Service Premium sia corretta.

Errore indirizzo di posta elettronica non valido

5. Impossibile trovare un percorso di certificazione valido per la destinazione richiesta: Verificare che i certificati della catena di certificati Entra ID (Microsoft Azure RSA TLS Issuing CA e DigiCert Root CA ecc. in base al pcap) siano presenti nell'archivio certificati attendibile di ISE e che siano attendibili per il ruolo "Attendibilità per l'autenticazione all'interno di ISE e comunicazione client-server (infrastruttura)".

Verificare tutti i certificati inviati da EntraID utilizzando un pcap.

Errore di convalida del certificato

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