Konfiguration und Fehlerbehebung für OAuth-basierte SMTP-Authentifizierung in der ISE

Einleitung

In diesem Dokument wird die OAuth 2.0-Konfiguration in der ISE beschrieben, um die E-Mail-Kommunikation über Microsoft Exchange Online Mail SMTP-Server zu aktivieren.

Voraussetzungen

Anforderungen

Cisco empfiehlt, dass Sie über Grundkenntnisse der Cisco Identity Services Engine (ISE) und des Simple Mail Transfer Protocol (SMTP)-Servers sowie der Autorisierung für den Zugriff verfügen.

Verwendete Komponenten

ISE Version 3.5 P1 (3.2 Patch 8, 3.3 Patch 8, 3.4 Patch 4 unterstützt diese Funktionalität ebenfalls)

Zugriff auf Microsoft EntraID und das Microsoft 365 Admin Center

Die Informationen in diesem Dokument beziehen sich auf Geräte in einer speziell eingerichteten Testumgebung. Alle Geräte, die in diesem Dokument benutzt wurden, begannen mit einer gelöschten (Nichterfüllungs) Konfiguration. Wenn Ihr Netzwerk in Betrieb ist, stellen Sie sicher, dass Sie die möglichen Auswirkungen aller Befehle kennen.

Konfigurieren

In diesem Abschnitt wird die Konfiguration der Microsoft Entra-ID und der ISE beschrieben, um E-Mail-Benachrichtigungen zu unterstützen, die verwendet werden, um:

• Senden Sie E-Mail-Warnmeldungen an alle internen Administratoren, wobei die Option "System-Warnmeldungen in E-Mails einbeziehen" aktiviert ist. Um die E-Mail-Adresse des Absenders zu konfigurieren, klicken Sie auf Administration > System > Einstellungen > Alarmeinstellungen > Warnmeldung, und geben Sie die E-Mail-Adresse an die Adresse ein, die unter Microsoft 365 admin center konfiguriert ist.

• Sponsoren, eine E-Mail-Benachrichtigung mit ihren Anmeldeinformationen und Anweisungen zum Zurücksetzen des Kennworts an Gäste zu senden. Für den Gast- und Sponsorfluss wird die Absender-E-Mail unter Work Centers > Guest Access > Settings > Guest email settings > Default 'From' (Absender-E-Mail-Adresse) auf die unter Microsoft 365 admin center konfigurierte E-Mail-Adresse konfiguriert.
• Ermöglicht Gästen, ihre Anmeldeinformationen automatisch zu erhalten, nachdem sie sich erfolgreich registriert haben, und Maßnahmen zu ergreifen, bevor ihre Gastkonten ablaufen.
• Senden Sie Erinnerungs-E-Mails an ISE-Administratoren/interne Netzwerkbenutzer, die auf der ISE vor Ablauf ihres Kennworts konfiguriert wurden.

ISE-Knoten, die E-Mails versenden

Netzwerkdiagramm

Zur Verwendung von OAuth mit der ISE sind drei Schritte erforderlich:

1. ISE-Anwendung mit Microsoft Entra-ID registrieren

2. Rufen Sie ein Zugriffstoken vom Tokenserver (IDP) ab.

3. Authentifizieren von Verbindungsanforderungen an den SMTP-Server mit einem Zugriffstoken.

Konfigurationen

SCHRITT 1: E-Mail-Konto des Benutzers erstellen

Erstellen Sie ein E-Mail-Benutzerkonto in Ihrer registrierten Domäne über das Microsoft 365-Admin-Center. Das Beispielkonto wird hier mit dem Benutzernamen "no-reply" erstellt, um sich mit der EntraID-Anwendung zu verbinden und E-Mails von der ISE zu versenden.

1. Navigieren Sie zu Benutzer > Aktive Benutzer, und fügen Sie einen Benutzer hinzu, um E-Mails von der ISE zu senden.
2. Richten Sie die Grundlagen ein: Fügen Sie den Vor- und Nachnamen des Benutzers hinzu, geben Sie den Anzeigenamen, den FQDN und das Kennwort ein, und klicken Sie auf "Weiter".
3. Wählen Sie den Speicherort aus, und weisen Sie dem Benutzer eine Produktlizenz zu (Microsoft 365 E5 Developer). Klicken Sie dann auf Weiter

Benutzer hinzufügen

4. Weisen Sie unter Optionale Einstellungen die Rolle Benutzer zu (kein Zugriff auf das Admin Center).

5. Überprüfen Sie und klicken Sie auf Fertig stellen hinzufügen.

6. Wählen Sie die Apps aus, über die dieses Benutzerkonto auf die E-Mail-Adresse von Microsoft 365 zugreifen kann: Gehen Sie im Microsoft 365-Admin-Center zu Benutzer > Aktive Benutzer > wählen Sie das Benutzerkonto aus, und klicken Sie auf Mail. Unter E-Mail-Apps > E-Mail-Apps verwalten. Stellen Sie sicher, dass Authenticated SMTP zusammen mit anderen Apps ausgewählt ist.

E-Mail-Apps verwalten

PHASE 2: Registrieren der ISE-Anwendung in Microsoft Entra-ID

1. Melden Sie sich beim Microsoft Entra Admin Center mit Ihrem Microsoft Azure-Konto an, das über ein aktives Abonnement verfügt und mindestens ein Anwendungsentwickler sein muss.
2. Navigieren Sie zu Entra ID. Suchen Sie nach App-Registrierungsdienst, klicken Sie auf Neue Registrierung
3. Geben Sie einen aussagekräftigen Namen für Ihre App ein, und wählen Sie unter Unterstützte Kontotypen aus, wer die Anwendung verwenden kann, wählen Sie "Nur ein Tenant - Ihr EntraID-Tenant" und klicken Sie auf "Registrieren", um die App-Registrierung abzuschließen.

Registrieren einer Anwendung

4. Die Seite Übersicht der Anwendung wird angezeigt. Notieren Sie sich die Anwendungs-ID (Client), die Ihre Anwendung eindeutig identifiziert. Außerdem Ihre Verzeichnis-ID (Tenant) für die ISE SMTP-Konfiguration.

App-Registrierungsdetails

5. Fügen Sie nun die Anmeldeinformationen für die Anwendung dieser MS Entra-Anwendung hinzu, um sich sicher zu authentifizieren und ohne Benutzereingriff auf die Web-API zuzugreifen.

1. Navigieren Sie in der neu registrierten Anwendung zu Verwalten > Zertifikate und Geheimnisse. Klicken Sie unter Client Secrets auf New client secret. Geben Sie unter Clientschlüssel hinzufügen eine Beschreibung ein, legen Sie die Ablaufdauer fest, und klicken Sie auf Hinzufügen.
2. Notieren Sie sich den geheimen Client-Wert, da geheime Client-Werte nicht angezeigt werden können, außer unmittelbar nach der Erstellung. Vergessen Sie nicht, den geheimen Schlüssel zu speichern, bevor Sie die Seite verlassen.
3. Notieren Sie sich auch das Ablaufdatum des Schlüssels.

Geheime Konfiguration des Anwendungsclients

6. Anwendungen sind berechtigt, APIs aufzurufen, wenn ihnen von Benutzern/Administratoren Berechtigungen erteilt werden. Fügen Sie nun der MS Entra-Anwendung SMTP-Berechtigungen hinzu.

1. Navigieren Sie in der neu registrierten Anwendung zu Verwalten > API-Berechtigungen. Wählen Sie Berechtigung hinzufügen aus.
2. Wählen Sie die Registerkarte APIs meiner Organisation aus, und suchen Sie nach "Office 365 Exchange Online".
3. Klicken Sie auf Anwendungsberechtigungen.
4. Wählen Sie für den SMTP-Zugriff die SMTP.SendAsApp-Berechtigung aus.
5. Tenant-Administratorzustimmung ist für diese Berechtigung erforderlich. Klicken Sie auf Admin-Zustimmung erteilen für <Tenant-Name>

Zuweisen von API-Berechtigungen zu einer Anwendung

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

7. Dienstprinzipale in Exchange werden verwendet, um Anwendungen den Zugriff auf Exchange-Postfächer über den Client-Anmeldedatenfluss mit den SMTP-, POP- und IMAP-Protokollen zu ermöglichen. 

    Sobald ein Tenant-Administrator der Microsoft Entra-Anwendung zustimmt, muss der Administrator den Entra-Anwendungsdienstprinzipal in Exchange über Exchange Online PowerShell registrieren. Diese Registrierung wird durch das Cmdlet New-ServicePrincipal aktiviert.

1. Installieren Sie Powershell, falls es nicht bereits auf Ihrem Laptop installiert ist.

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

PowerShell installieren

II. Um das Cmdlet New-ServicePrincipal zu verwenden, installieren Sie ExchangeOnlineManagement, und stellen Sie eine Verbindung mit dem Mandanten her, wie im Ausschnitt gezeigt:

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

Mit Exchange Online-Tenant verbinden

III. Registrierung eines Microsoft Entra-Anwendungsdienstprinzips in Exchange. Verwenden Sie die AppID und die ObjectID [Die OBJECT_ID ist die Object-ID aus der Übersichtsseite des Enterprise Application-Knotens (Azure-Portal) für die Anwendungsregistrierung. Es handelt sich NICHT um die Objekt-ID auf der Seite Übersicht des Knotens App-Registrierungen. Die Verwendung der falschen Objekt-ID führt zu einem Authentifizierungsfehler].

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

Registrieren des Anwendungs-Dienstprinzips in Exchange

IV.  Überprüfen des registrierten Dienstprinzipalbezeichners mit dem Cmdlet Get-ServicePrincipal

PS/Users/abc> Get-ServicePrincipal | fl

Prinzipalkennung für registrierten Dienst überprüfen

V.  Der Tenant-Administrator kann jetzt die spezifischen Mailboxen im Tenant hinzufügen, auf die die Anwendung zugreifen darf. Diese Konfiguration erfolgt mit dem Cmdlet Add-MailboxPermission.

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

Hinzufügen von Postfachberechtigungen für den Zugriff auf die Anwendung

Ihre Microsoft Entra-Anwendung kann jetzt über die SMTP-, POP- oder IMAP-Protokolle mithilfe des Gewährungsflusses für OAuth 2.0-Clientanmeldeinformationen auf die zulässigen Mailboxen zugreifen.

SCHRITT 3: Konfigurieren der ISE SMTP-Benutzerauthentifizierung über MS Exchange Online OAuth

Um einen SMTP-Server (Simple Mail Transfer Protocol) zu konfigurieren, klicken Sie auf das Menü-Symbol (), und wählen Sie Administration > System > Settings > SMTP Server aus. Konfigurieren Sie die Felder.

• Im Bereich SMTP-Servereinstellungen:
  • SMTP-Server: smtp.office365.com
  • SMTP-Port: 587
  • Verbindungs-Timeout: 60 Sekunden
• Verwenden Sie im Bereich Authentifizierungseinstellungen den Umschalter, um die Option Authentifizierungseinstellungen verwenden zu aktivieren.

Wählen Sie MS Exchange Online OAuth: Geben Sie diese Werte ein, um Microsoft Exchange Online OAuth zu konfigurieren.

• Geben Sie im Feld Benutzername die vollständige E-Mail-Adresse des Exchange Online-Benutzernamens ein.
• Geben Sie im Feld Client-ID die Client-ID der Azure Entra-ID-Anwendung ein.
• Geben Sie im Feld Tenant-ID die Tenant-ID der Azure Entra-ID-Anwendung ein.
• Geben Sie im Feld Client Secret (Client-Schlüssel) den Client-Schlüssel der Azure Entra ID-Anwendung ein.
• Geben Sie im Feld Ablaufdatum das Ablaufdatum des Kundengeheimnisses ein.

Auf Basis dieser Konfiguration werden Alarme zum Ablauf des geheimen Clientzugriffs ausgelöst.

• Die OAuth-Token-Endpunkt-API und Bereichsdateien werden automatisch ausgefüllt.

Die Konfiguration kann erst nach dem erfolgreichen Test der Verbindung gespeichert werden.

Erfolgreiche Testverbindung mit SMTP-Server

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

Überprüfung

Konfigurieren Sie zur Überprüfung die Einstellungen für Gast-E-Mail. Navigieren Sie zu Work Centers > Guest Access > Guest Email Settings. Wählen Sie die Option "E-Mail-Benachrichtigungen für Gäste aktivieren" aus, und konfigurieren Sie die Standard-E-Mail-Adresse "Von" des Kontos, das in Schritt 1 der Konfiguration und bei "Speichern" konfiguriert wurde.

Gast-E-Mail-Einstellungen ändern

Senden Sie eine Test-E-Mail, indem Sie zu Work Centers > Guest Access > Portal & Components > Guest Portals > Self-Registered Guest Portal (Standard) > Portal Page Customization > Notifications > Email navigieren.

Klicken Sie im Vorschaufenster rechts auf Einstellungen > Test-E-Mail senden, fügen Sie Ihre E-Mail-ID hinzu, und klicken Sie auf Senden.

Test-E-Mail aus dem Portal zur Selbstregistrierung

Ihr Outlook muss eine E-Mail von einem in Schritt 1 der Überprüfung konfigurierten Konto erhalten, das keine Antwort sendet. Beispiel-E-Mail im Screenshot.

Beispiel für in Outlook empfangene E-Mails

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.

Testen Sie das Portal des Sponsors, indem Sie die Anmeldeinformationen des Benutzers erneut an den Gastbenutzer durch den Sponsoradministrator senden.

Test über das Sponsorportal

Anmeldeinformationen an Gastbenutzer senden

Beispiel für eine vom Gastbenutzer empfangene E-Mail:

E-Mail-Benachrichtigung an Gastbenutzer

Fehlerbehebung

Beginnen Sie mit der Überprüfung von Alarmen für das Ablaufdatum des Client Secret. Neue Alarme für den SMTP-OAuth-Clientschlüssel werden in ISE hinzugefügt.

Aktivieren Sie zur weiteren Fehlerbehebung Debug-Protokolle auf PAN-, PSN- oder PMnT-Knoten, je nachdem, welches Problem Sie beheben möchten.

• Protokollkomponente: Gastzugriff-Administrator, Gastzugriff
• Protokolldatei: guest.log

Test-Verbindungsvorgang

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.

Vorgang speichern

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

Beheben von Verbindungsproblemen

1. GUI-Fehler: Verbindung mit smtp.office365.con fehlgeschlagen.

Timeoutfehler beim Verbinden

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

Bei "Guest.log" ist die Verbindung abgelaufen. Die Proxykonfiguration muss behoben werden, um dieses Problem zu beheben.

2. GUI-Fehler: Ungültiger OAuth-Endpunkt oder Tenant-ID - selbsterklärend. Die Tenant-ID muss überprüft werden.

3. Ungültiger geheimer Clientschlüssel - Identisch, muss geheimen Clientwert überprüfen

Ungültiger geheimer Clientfehler

4. Ungültige E-Mail-Adresse: Vergewissern Sie sich, dass die Konfiguration des Serviceprinzips korrekt ist.

Fehler bei ungültiger E-Mail-Adresse

5. Es wurde kein gültiger Zertifizierungspfad zum angeforderten Ziel gefunden: Stellen Sie sicher, dass die Entra ID-Zertifikatskettenzertifikate (Microsoft Azure RSA TLS Issuing CA und DigiCert Root CA usw. gemäß pcap) im vertrauenswürdigen Zertifikatspeicher von ISE vorhanden und für die Rolle "Trust for authentication within ISE and Client-Server communication (Infrastructure)" vertrauenswürdig sind.

Überprüfen Sie alle von EntraID gesendeten Zertifikate, indem Sie pcap verwenden.

Fehler bei der Validierung des Zertifikats

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