Configuration et dépannage de l'authentification SMTP basée sur OAuth dans ISE

Introduction

Ce document décrit la configuration OAuth 2.0 dans ISE pour activer la communication par courrier électronique via les serveurs SMTP de Microsoft Exchange Online Mail.

Conditions préalables

Exigences

Cisco vous recommande d'avoir des connaissances de base sur la fonctionnalité de serveur ISE (Identity Services Engine) et SMTP (Simple Mail Transfer Protocol) de Cisco et sur l'autorisation OAuth.

Composants utilisés

ISE version 3.5 P1 (3.2 Patch 8, 3.3 Patch 8, 3.4 Patch 4 prend également en charge cette fonctionnalité)

Accès à Microsoft EntraID et Microsoft 365 admin center

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. Si votre réseau est en ligne, assurez-vous de bien comprendre l’incidence possible des commandes.

Configurer

Cette section décrit la configuration de Microsoft Entra ID et ISE afin de prendre en charge les notifications par e-mail utilisées pour :

• Envoyez des notifications d'alarme par e-mail à tous les utilisateurs administratifs internes avec l'option d'inclusion des alarmes système dans les e-mails activée. Pour configurer l'adresse e-mail de l'expéditeur, cliquez sur Administration > Système > Paramètres > Paramètres d'alarme > Notification d'alarme et tapez l'adresse e-mail dans celle configurée sous Centre d'administration Microsoft 365

• Les sponsors doivent envoyer une notification par e-mail aux invités avec leurs identifiants de connexion et leurs instructions de réinitialisation de mot de passe. Pour le flux Invité et Sponsor, l'e-mail de l'expéditeur est configuré sous Work Centers > Guest Access > Settings > Guest email settings > Default 'From' email address à celui configuré sous Microsoft 365 admin center
• Permettre aux invités de recevoir automatiquement leurs identifiants de connexion une fois qu'ils se sont inscrits et avec les actions à entreprendre avant l'expiration de leur compte invité.
• Envoyez des e-mails de rappel aux utilisateurs administrateurs ISE/utilisateurs réseau internes configurés sur ISE avant la date d'expiration de leur mot de passe.

Noeuds ISE qui envoient des e-mails

Diagramme du réseau

Pour utiliser OAuth avec ISE, 3 étapes sont nécessaires :

1. Enregistrez l'application ISE avec Microsoft Entra ID

2. Obtenir un jeton d'accès à partir du serveur de jetons (IDP)

3. Authentifiez les demandes de connexion au serveur SMTP avec un jeton d'accès.

Configurations

ÉTAPE 1: Créer un compte de messagerie utilisateur

Créez un compte de messagerie utilisateur dans votre domaine enregistré à partir du Centre d'administration Microsoft 365. L'exemple de compte est créé ici avec le nom d'utilisateur "no-reply" pour se connecter à l'application EntraID et envoyer des e-mails depuis ISE.

1. Accédez à Users > Active users et Add a user to send emails from ISE.
2. Configurez les éléments de base : ajoutez le prénom et le nom de l'utilisateur, le nom d'affichage, le nom de domaine complet et le mot de passe, puis cliquez sur Suivant.
3. Sélectionnez l'emplacement et attribuez une licence de produit à l'utilisateur (Microsoft 365 E5 Developer), cliquez sur Next

Ajouter un utilisateur

4. Sous Optional Settings, Assign the Role User (no admin center access)

5. Vérifiez et cliquez sur Terminer l'ajout.

6. Choisissez les applications dans lesquelles ce compte d'utilisateur peut accéder à la messagerie Microsoft 365 : Dans le Centre d'administration de Microsoft 365, accédez à Utilisateurs > Utilisateurs actifs > sélectionnez le compte d'utilisateur et cliquez sur Courrier. Sous Applications de messagerie > Gérer les applications de messagerie. Assurez-vous que Authenticated SMTP est également sélectionné avec d'autres applications.

Gérer les applications de messagerie

ÉTAPE 2: Enregistrer l'application ISE dans Microsoft Entra ID

1. Connectez-vous au centre d'administration Microsoft Entra à l'aide de votre compte MS Azure qui a un abonnement actif et qui doit être au moins un développeur d'applications.
2. Accédez à Entra ID. Recherchez le service Inscriptions d'applications, cliquez sur Nouvelle inscription
3. Entrez un nom significatif pour votre application et sous Types de comptes pris en charge, spécifiez qui peut utiliser l'application, choisissez « Single tenant only-your EntraID tenant » et cliquez sur Register pour terminer l'enregistrement de l'application.

Enregistrer une demande

4. La page Aperçu de l'application s'affiche. Enregistrez l'ID de l'application (client), qui identifie de manière unique votre application. Également votre ID de répertoire (locataire), à utiliser dans la configuration ISE SMTP.

Détails d'inscription

5. Maintenant, ajoutez les informations d'identification de l'application à cette application MS Entra pour s'authentifier en toute sécurité et accéder à l'API Web sans interaction de l'utilisateur.

1. Dans l'application nouvellement enregistrée, accédez à Manage > Certificates & secrets. Sous Client secrets, cliquez sur New client secret. Entrez une Description sous Ajouter un secret client et définissez la durée d'expiration et cliquez sur Ajouter.
2. Notez la valeur secrète du client car les valeurs secrètes du client ne peuvent pas être affichées, sauf immédiatement après la création. Veillez à enregistrer le secret lors de sa création avant de quitter la page.
3. Notez également la date d'expiration de la clé.

Configuration du secret client de l'application

6. Les applications sont autorisées à appeler des API lorsque les utilisateurs/administrateurs leur accordent des autorisations. Ajoutez maintenant des autorisations SMTP à l'application MS Entra.

1. Dans l'application nouvellement enregistrée, accédez à Manage > API permissions. Sélectionnez Ajouter une autorisation.
2. Sélectionnez l'onglet API utilisées par mon organisation et recherchez « Office 365 Exchange Online ».
3. Cliquez sur Autorisations d'application.
4. Pour l'accès SMTP, choisissez l'autorisation SMTP.SendAsApp.
5. Le consentement de l'administrateur du locataire est requis pour cette autorisation. Cliquez sur Grant admin consent for <nom du client>

Attribuer une autorisation API à l'application

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

7. Les identités de service dans Exchange sont utilisées pour permettre aux applications d'accéder aux boîtes aux lettres Exchange via le flux d'informations d'identification du client avec les protocoles SMTP, POP et IMAP. 

    Une fois qu'un administrateur de service partagé a accepté votre application Microsoft Entra, l'administrateur doit enregistrer votre principal de service d'application Entra dans Exchange via Exchange Online PowerShell. Cette inscription est activée par l'applet de commande New-ServicePrincipal.

1. Installez Powershell, si ce n'est déjà fait sur votre ordinateur portable

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

Installer Powershell

II. Pour utiliser l'applet de commande New-ServicePrincipal, installez ExchangeOnlineManagement et connectez-vous à votre locataire comme indiqué dans l'extrait de code :

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

Se connecter à Exchange Online Tenant

III. Enregistrement d'un principal de service d'application Microsoft Entra dans Exchange. Utiliser l'AppID et l'ObjectID [L'OBJECT_ID est l'ID d'objet de la page Vue d'ensemble du noeud Application d'entreprise (Azure Portal) pour l'enregistrement de l'application. Il ne s'agit PAS de l'ID d'objet de la page Vue d'ensemble du noeud Inscriptions d'application. L'utilisation d'un ID d'objet incorrect entraîne un échec d'authentification].

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

Enregistrer le principal du service d'application Entra dans Exchange

IV.  Vérifiez votre identificateur de principal du service inscrit à l'aide de l'applet de commande Get-ServicePrincipal

PS/Users/abc> Get-ServicePrincipal | fl

Vérifier l'identificateur principal du service enregistré

V.  L'administrateur du service partagé peut désormais ajouter les boîtes aux lettres spécifiques du service partagé auxquelles votre application peut accéder. Cette configuration est effectuée avec l'applet de commande Add-MailboxPermission.

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

Ajouter une autorisation de boîte aux lettres pour accéder à l'application

Votre application Microsoft Entra peut désormais accéder aux boîtes aux lettres autorisées via les protocoles SMTP, POP ou IMAP à l'aide du flux d'octroi des informations d'identification du client OAuth 2.0.

ÉTAPE 3: Configuration de l'authentification utilisateur SMTP ISE via MS Exchange Online OAuth

Pour configurer un serveur SMTP (Simple Mail Transfer Protocol), cliquez sur l'icône Menu () et choisissez Administration > System > Settings > SMTP Server. Configurez les champs.

• Dans la zone Paramètres du serveur SMTP :
  • Serveur SMTP : smtp.office365.com
  • Port SMTP : 587
  • Délai de connexion : 60 secondes
• Dans la zone Authentication Settings, utilisez le commutateur à bascule pour activer l'option Use Authentication Settings.

Sélectionnez MS Exchange Online OAuth : Entrez ces valeurs pour configurer Microsoft Exchange Online OAuth.

• Dans le champ Username, saisissez l'adresse e-mail complète du nom d'utilisateur Exchange Online.
• Dans le champ ID client, entrez l'ID client de l'application Azure Entra ID.
• Dans le champ ID du locataire, entrez l'ID du locataire de l'application Azure Entra ID.
• Dans le champ Client Secret, entrez le secret client de l'application Azure Entra ID.
• Dans le champ Expiry Date, saisissez la date d'expiration du secret client.

Les alarmes d'expiration de secret client sont déclenchées en fonction de cette configuration.

• L'API et les fichiers d'étendue du point de terminaison du jeton OAuth sont automatiquement remplis.

La configuration peut être enregistrée uniquement après une opération de test de connexion réussie.

Test réussi de la connexion au serveur SMTP

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

Vérifier

Pour le vérifier, configurez les paramètres de messagerie de l'invité. Accédez à Work Centers > Guest Access > Guest Email Settings. Sélectionnez l'option Enable email notifications to invités et configurez l'adresse e-mail « From » par défaut du compte de non-réponse configuré au cours de l'étape 1 de la configuration et Save.

Modifier les paramètres de messagerie des invités

Pour envoyer un e-mail test, accédez à Work Centers > Guest Access > Portal & Components > Guest Portals > Self-Registered Guest Portal (par défaut) > Portal Page Customization > Notifications > Email.

Sous le volet d'aperçu à droite, cliquez sur Paramètres > Envoyer un e-mail test, Ajouter votre ID d'e-mail et cliquez sur Envoyer.

E-mail test à partir du portail d'inscription

Votre Outlook doit recevoir un e-mail du compte sans réponse configuré à l'étape 1 de la vérification. Exemple d'e-mail dans la capture.

Exemple de courrier électronique reçu dans 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.

Testez également à partir du portail du sponsor en renvoyant les identifiants de l'utilisateur à l'utilisateur invité par l'administrateur du sponsor.

Test à partir du portail du sponsor

Envoyer les informations d'identification à l'utilisateur invité

Exemple d'e-mail reçu par l'utilisateur invité :

Notification par e-mail à l'utilisateur invité

Dépannage

Commencez par vérifier les alarmes pour l'expiration de Client Secret. De nouvelles alarmes liées à SMTP OAuth Client Secret sont ajoutées dans ISE.

Pour un dépannage plus approfondi, activez les journaux de débogage sur le noeud PAN, PSN ou PMnT selon le problème que vous avez résolu.

• Composant de journalisation : guest-access-admin, accès invité
• Fichier journal : guest.log

Tester le fonctionnement de connexion

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.

Enregistrer l'opération

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

Dépannage des problèmes de connectivité

1. Erreur GUI : La connexion à smtp.office365.con a échoué.

Erreur Connect timed out

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 indique que la connexion a expiré. La configuration du proxy doit être corrigée pour résoudre ce problème.

2. Erreur GUI : Identificateur de point de terminaison ou de locataire OAuth non valide - Auto explicatif. Vous devez vérifier l'ID du locataire.

3. Secret client non valide : identique, vous devez vérifier la valeur du secret client

Erreur de secret client non valide

4. Adresse e-mail non valide : vérifiez que la configuration du principe de service est correcte.

Erreur d'adresse e-mail incorrecte

5. Chemin de certification valide introuvable vers la cible demandée : Assurez-vous que les certificats de la chaîne de certificats Entra ID (Autorité de certification émettrice Microsoft Azure RSA TLS et Autorité de certification racine DigiCert, etc., conformément au pcap) sont présents dans le magasin de certificats approuvé d'ISE et qu'ils sont approuvés pour le rôle « Confiance pour l'authentification au sein d'ISE et communication client-serveur (infrastructure) ».

Vérifiez tous les certificats envoyés par EntraID en prenant un pcap.

Échec de validation du certificat

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