Condividi tramite

Configurare un provider di posta elettronica personalizzato per l'invio di eventi con passcode monouso (anteprima)

  • Articolo

Si applica a: Cerchio bianco con un simbolo X grigio. Tenant della forza lavoro Cerchio verde con segno di spunta bianco. Tenant esterni (altre informazioni)

Questo articolo fornisce una guida sulla configurazione e la configurazione di un provider di posta elettronica personalizzato per il tipo di evento OTP (One Time Passcode) Send. L'evento viene attivato quando viene attivato un messaggio di posta elettronica OTP, che consente di chiamare un'API REST per usare il proprio provider di posta elettronica chiamando un'API REST.

Suggerimento

Da provare subito

Per provare questa funzionalità, passare alla demo Woodgrove Groceries e avviare il caso d'uso "Usa un provider di posta elettronica personalizzato per un codice monouso".

Prerequisiti

Passaggio 1: Creare un'app per le funzioni di Azure

Questa sezione illustra come configurare un'app per le funzioni di Azure nel portale di Azure. L'API della funzione è il gateway per il provider di posta elettronica. Si crea un'app per le funzioni di Azure per ospitare la funzione trigger HTTP e configurare le impostazioni nella funzione.

Suggerimento

La procedura descritta in questo articolo può variare leggermente in base al portale di partenza.

  1. Accedere al portale di Azure almeno come amministratore di applicazioni e amministratore dell'autenticazione.

  2. Nel menu del portale di Azure o dalla pagina Home selezionare Crea una risorsa.

  3. Cercare e selezionare App per le funzioni e selezionare Crea.

  4. Nella pagina Crea app per le funzioni selezionare Consumo e quindi Seleziona.

  5. Nella scheda Informazioni di base della pagina Crea app per le funzioni (consumo) creare un'app per le funzioni usando le impostazioni specificate nella tabella seguente:

    Impostazione Valore suggerito Descrizione
    Abbonamento Sottoscrizione in uso Sottoscrizione in cui viene creata la nuova app per le funzioni.
    Gruppo di risorse myResourceGroup Selezionare il gruppo di risorse usato per configurare le risorse del servizio di comunicazione di Azure e del servizio di comunicazione tramite posta elettronica come parte dei prerequisiti
    Nome dell'app per le funzioni Nome globalmente univoco Nome che identifica la nuova app per le funzioni. I caratteri validi sono a-z (senza distinzione tra maiuscole e minuscole), 0-9 e -.
    Distribuire codice o immagine del contenitore Codice Opzione per la pubblicazione di file di codice o di un contenitore Docker. Per questa esercitazione selezionare Codice.
    Stack di runtime .NET Linguaggio di programmazione preferito. Per questa esercitazione selezionare .NET.
    Versione 8 (LTS) in-process Versione del runtime .NET. In-process indica che è possibile creare e modificare funzioni nel portale, consigliato per questa guida
    Area Area preferita Selezionare un'area vicina a sé o vicina ad altri servizi a cui le funzioni possono accedere.
    Sistema operativo Windows Viene preselezionato automaticamente il sistema operativo in base alla selezione dello stack di runtime.

  6. Selezionare Rivedi e crea per esaminare le selezioni di configurazione dell’app e quindi selezionare Crea. La distribuzione richiede alcuni minuti.

  7. Una volta distribuito, selezionare Vai alla risorsa per visualizzare la nuova app per le funzioni.

1.1 Creare una funzione trigger HTTP

Dopo aver creato l'app per le funzioni di Azure, creare una funzione trigger HTTP. Un trigger HTTP consente di richiamare una funzione con una richiesta HTTP Questo trigger HTTP fa riferimento all'estensione di autenticazione personalizzata Microsoft Entra.

  1. All'interno dell'app per le funzioni scegliere Funzioni dal menu.
  2. Selezionare Crea funzione.
  3. Nella finestra Crea funzione, in Selezionare un modello cercare e selezionare il modello di trigger HTTP. Selezionare Avanti.
  4. In Dettagli modello immettere CustomAuthenticationExtensionsAPI per la proprietà Nome funzione.
  5. Per il Livello di autorizzazione, selezionare Funzione.
  6. Seleziona Crea.

1.2 Modificare la funzione

Il codice inizia con la lettura dell'oggetto JSON in ingresso. Microsoft Entra ID invia l'oggetto JSON all'API. In questo esempio legge l'indirizzo di posta elettronica (identificatore) e OTP. Il codice invia quindi i dettagli al servizio di comunicazione per inviare il messaggio di posta elettronica usando un modello dinamico.

Questa guida pratica illustra l'evento di invio OTP usando Servizi di comunicazione di Azure e SendGrid. Usare le schede per selezionare l'implementazione.

  1. Dal menu, selezionare Codice e test.

  2. Sostituire l'intero codice con il frammento di codice seguente.

    using System.Dynamic;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Text.Json.Serialization;
using Azure.Communication.Email;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Company.AuthEvents.OnOtpSend.CustomEmailACS
{
    public class CustomEmailACS
    {
        private readonly ILogger<CustomEmailACS> _logger;

        public CustomEmailACS(ILogger<CustomEmailACS> logger)
        {
            _logger = logger;
        }

        [Function("OnOtpSend_CustomEmailACS")]
        public async Task<IActionResult> RunAsync([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            // Get the request body
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            JsonNode jsonPayload = JsonNode.Parse(requestBody)!;

            // Get OTP and mail to
            string emailTo = jsonPayload["data"]!["otpContext"]!["identifier"]!.ToString();
            string otp = jsonPayload["data"]!["otpContext"]!["onetimecode"]!.ToString();

            // Send email
            await SendEmailAsync(emailTo, otp);

            // Prepare response
            ResponseObject responseData = new ResponseObject("microsoft.graph.OnOtpSendResponseData");
            responseData.Data.Actions = new List<ResponseAction>() { new ResponseAction(
                "microsoft.graph.OtpSend.continueWithDefaultBehavior") };

            return new OkObjectResult(responseData);
        }

        private async Task SendEmailAsync(string emailTo, string code)
        {
            // Get app settings
            var connectionString = Environment.GetEnvironmentVariable("mail_connectionString");
            var sender = Environment.GetEnvironmentVariable("mail_sender");
            var subject = Environment.GetEnvironmentVariable("mail_subject");

            try
            {
                if (!string.IsNullOrEmpty(connectionString))
                {
                    var emailClient = new EmailClient(connectionString);
                    var body = EmailTemplate.GenerateBody(code);

                    _logger.LogInformation($"Sending OTP to {emailTo}");

                    EmailSendOperation emailSendOperation = await emailClient.SendAsync(
                    Azure.WaitUntil.Started,
                    sender,
                    emailTo,
                    subject,
                    body);
                }
            }
            catch (System.Exception ex)
            {
                _logger.LogError(ex.Message);
            }
        }
    }

    public class ResponseObject
    {
        [JsonPropertyName("data")]
        public Data Data { get; set; }

        public ResponseObject(string dataType)
        {
            Data = new Data(dataType);
        }
    }

    public class Data
    {
        [JsonPropertyName("@odata.type")]
        public string DataType { get; set; }
        [JsonPropertyName("actions")]
        public List<ResponseAction> Actions { get; set; }

        public Data(string dataType)
        {
            DataType = dataType;
        }
    }

    public class ResponseAction
    {
        [JsonPropertyName("@odata.type")]
        public string DataType { get; set; }

        public ResponseAction(string dataType)
        {
            DataType = dataType;
        }
    }

    public class EmailTemplate
    {
        public static string GenerateBody(string oneTimeCode)
        {
            return @$"<html><body>
            <div style='background-color: #1F6402!important; padding: 15px'>
                <table>
                <tbody>
                    <tr>
                        <td colspan='2' style='padding: 0px;font-family: "Segoe UI Semibold", "Segoe UI Bold", "Segoe UI", "Helvetica Neue Medium", Arial, sans-serif;font-size: 17px;color: white;'>Woodgrove Groceries live demo</td>
                    </tr>
                    <tr>
                        <td colspan='2' style='padding: 15px 0px 0px;font-family: "Segoe UI Light", "Segoe UI", "Helvetica Neue Medium", Arial, sans-serif;font-size: 35px;color: white;'>Your Woodgrove verification code</td>
                    </tr>
                    <tr>
                        <td colspan='2' style='padding: 25px 0px 0px;font-family: "Segoe UI", Tahoma, Verdana, Arial, sans-serif;font-size: 14px;color: white;'> To access <span style='font-family: "Segoe UI Bold", "Segoe UI Semibold", "Segoe UI", "Helvetica Neue Medium", Arial, sans-serif; font-size: 14px; font-weight: bold; color: white;'>Woodgrove Groceries</span>'s app, please copy and enter the code below into the sign-up or sign-in page. This code is valid for 30 minutes. </td>
                    </tr>
                    <tr>
                        <td colspan='2' style='padding: 25px 0px 0px;font-family: "Segoe UI", Tahoma, Verdana, Arial, sans-serif;font-size: 14px;color: white;'>Your account verification code:</td>
                    </tr>
                    <tr>
                        <td style='padding: 0px;font-family: "Segoe UI Bold", "Segoe UI Semibold", "Segoe UI", "Helvetica Neue Medium", Arial, sans-serif;font-size: 25px;font-weight: bold;color: white;padding-top: 5px;'>
                        {oneTimeCode}</td>
                        <td rowspan='3' style='text-align: center;'>
                            <img src='https://woodgrovedemo.com/custom-email/shopping.png' style='border-radius: 50%; width: 100px'>
                        </td>
                    </tr>
                    <tr>
                        <td style='padding: 25px 0px 0px;font-family: "Segoe UI", Tahoma, Verdana, Arial, sans-serif;font-size: 14px;color: white;'> If you didn't request a code, you can ignore this email. </td>
                    </tr>
                    <tr>
                        <td style='padding: 25px 0px 0px;font-family: "Segoe UI", Tahoma, Verdana, Arial, sans-serif;font-size: 14px;color: white;'> Best regards, </td>
                    </tr>
                    <tr>
                        <td>
                            <img src='https://woodgrovedemo.com/Company-branding/headerlogo.png' height='20'>
                        </td>
                        <td style='font-family: "Segoe UI", Tahoma, Verdana, Arial, sans-serif;font-size: 14px;color: white; text-align: center;'>
                            <a href='https://woodgrovedemo.com/Privacy' style='color: white; text-decoration: none;'>Privacy Statement</a>
                        </td>
                    </tr>
                </tbody>
                </table>
            </div>
            </body></html>";
        }
    }
}

  3. Selezionare Recupera URL funzione e copiare l'URL della chiave della funzione, che viene quindi usato e denominato {Function_Url}. Chiudere la funzione.

Passaggio 2: Aggiungere stringa di connessione alla funzione di Azure

Le stringhe di connessione consentono agli SDK di Servizi di comunicazione di eseguire la connessione e l'autenticazione ad Azure. Sia per Servizi di comunicazione di Azure che per SendGrid è quindi necessario aggiungere questi stringa di connessione all'app per le funzioni di Azure come variabili di ambiente.

2.1: Estrarre i stringa di connessione e gli endpoint di servizio dalla risorsa Servizi di comunicazione di Azure

È possibile accedere alle stringhe di connessione e agli endpoint di servizio di Servizi di comunicazione dal portale di Azure o a livello di codice con le API di Azure Resource Manager.

  1. Nella home page del portale di Azure aprire il menu del portale, cercare e selezionare Tutte le risorse.

  2. Cercare e selezionare il Servizio comunicazioni di Azure creato come parte dei prerequisiti di questo articolo.

  3. Nel riquadro sinistro selezionare l'elenco a discesa Impostazioni , quindi selezionare Chiavi.

  4. Copiare l'endpoint e dalla chiave primaria copiare i valori per Chiave e Stringa di connessione.

    Screenshot della pagina Chiavi del servizio di comunicazione di Azure che mostra i percorsi dell'endpoint e delle chiavi.

2.2: Aggiungere i stringa di connessione alla funzione di Azure

  1. Tornare alla funzione di Azure creata in Creare un'app per le funzioni di Azure.

  2. Nella pagina Panoramica dell'app per le funzioni, nel menu a sinistra selezionare Impostazioni Variabili> di ambiente per aggiungere le impostazioni dell'app seguenti. Dopo aver aggiunto tutte le impostazioni, selezionare Applica, quindi Conferma.

    Impostazione Value (esempio) Descrizione
    mail_connectionString https://ciamotpcommsrvc.unitedstates.communication.azure.com/:accesskey=A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u Endpoint di Servizi di comunicazione di Azure
    mail_sender from.email@myemailprovider.com Dall'indirizzo di posta elettronica.
    mail_subject CIAM Demo Oggetto del messaggio di posta elettronica.

Passaggio 3: Registrare un'estensione di autenticazione personalizzata

In questo passaggio viene configurata un'estensione di autenticazione personalizzata usata da Microsoft Entra ID per chiamare la funzione di Azure. L'estensione per l'autenticazione personalizzata contiene informazioni sull'endpoint dell'API REST, sulle attestazioni analizzate dall'API REST e su come eseguire l'autenticazione con l'API REST. Usare il portale di Azure o Microsoft Graph per registrare un'applicazione per autenticare l'estensione di autenticazione personalizzata nella funzione di Azure.

Registrare un'estensione per l'autenticazione personalizzata

  1. Accedere al portale di Azure almeno come amministratore di applicazioni e amministratore dell'autenticazione.

  2. Cercare e selezionare Microsoft Entra ID, quindi selezionare Applicazioni aziendali.

  3. Selezionare Estensioni di autenticazione personalizzate e quindi selezionare Crea un'estensione personalizzata.

  4. In Informazioni di base selezionare il tipo di evento EmailOtpSend e selezionare Avanti.

    Screenshot del portale di Azure che evidenzia l'evento di invio OTP di posta elettronica.

  5. Nella scheda Configurazione endpoint immettere le proprietà seguenti, quindi selezionare Avanti per continuare.

    • Nome: un nome per l'estensione di autenticazione personalizzata. Ad esempio, Invia OTP tramite posta elettronica.
    • URL di destinazione: {Function_Url} dell'URL di Funzioni di Azure. Passare alla pagina Panoramica dell'app Funzioni di Azure e quindi selezionare la funzione creata. Nella pagina Panoramica delle funzioni selezionare Recupera URL funzione e usare l'icona di copia per copiare l'URL customauthenticationextension_extension (chiave di sistema).
    • Descrizione: descrizione delle estensioni per l'autenticazione personalizzate.

  6. Nella scheda Autenticazione API selezionare l'opzione Crea nuova registrazione app per creare una registrazione dell'app che rappresenta l'app per le funzioni.

  7. Assegnare all'app un nome, ad esempio Funzioni di Azure'API degli eventi di autenticazione e selezionare Avanti.

  8. Nella scheda Applicazioni selezionare l'applicazione da associare all'estensione di autenticazione personalizzata. Selezionare Avanti. È possibile applicarla all'intero tenant selezionando la casella . Selezionare Avanti per continuare.

  9. Nella scheda Verifica verificare che i dettagli siano corretti per l'estensione di autenticazione personalizzata. Prendere nota dell'ID app in Autenticazione API, necessario per configurare l'autenticazione per la funzione di Azure nell'app Funzioni di Azure. Seleziona Crea.

Dopo aver creato l'estensione di autenticazione personalizzata, aprire l'applicazione dal portale in Registrazioni app e selezionare Autorizzazioni API.

Nella pagina Autorizzazioni API selezionare il pulsante Concedi consenso amministratore per "YourTenant" per concedere all'amministratore il consenso all'app registrata, che consente all'estensione di autenticazione personalizzata di eseguire l'autenticazione all'API. L'estensione di autenticazione personalizzata usa client_credentials per eseguire l'autenticazione all'app per le funzioni di Azure usando l'autorizzazione Receive custom authentication extension HTTP requests.

Lo screenshot seguente mostra come concedere le autorizzazioni.

Screenshot di portale di Azure e come concedere il consenso amministratore.

Passaggio 4: Configurare un'app OpenID Connect da testare con

Per ottenere un token e testare l'estensione di autenticazione personalizzata, è possibile usare l'app https://jwt.ms. Si tratta di un'applicazione Web di proprietà di Microsoft che visualizza il contenuto decodificato di un token (il contenuto del token non lascia mai il browser).

Eseguire questi passaggi per registrare l'applicazione Web jwt.ms:

4.1 Registrare un'applicazione Web di test

  1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come amministratore applicazione.
  2. Passare a Identità>Applicazioni>Registrazioni applicazioni.
  3. Seleziona Nuova registrazione.
  4. Immettere un nome per l'applicazione. Ad esempio, Applicazione di test personale.
  5. In Tipi di account supportati selezionare Account solo in questa directory organizzativa.
  6. Nell'elenco a discesa Selezionare una piattaforma in URI di reindirizzamento selezionare Web e quindi immettere https://jwt.ms nella casella di testo URL.
  7. Selezionare Registra per completare la registrazione dell'app.
  8. Nella registrazione dell'app, in . In Microsoft Graph vi si fa riferimento tramite la proprietà appId.

Lo screenshot seguente mostra come registrare l'applicazione Test personale.

Screenshot che mostra come selezionare il tipo di account supportato e l'URI di reindirizzamento.

4.1 Ottenere l'ID applicazione

Copiare l'ID applicazione (client) dalla pagina Panoramica di registrazione dell'app. L'ID app viene definito come {App_to_sendotp_ID} nei passaggi successivi. In Microsoft Graph vi si fa riferimento tramite la proprietà appId.

4.2 Abilitare il flusso implicito

L'applicazione di test jwt.ms usa il flusso implicito. Abilitare il flusso implicito nella registrazione dell'applicazione test:

Importante

Microsoft consiglia di usare il flusso di autenticazione più sicuro disponibile. Il flusso di autenticazione usato per i test in questa procedura richiede un livello di attendibilità molto elevato nell'applicazione e comporta rischi che non sono presenti in altri flussi. Questo approccio non deve essere usato per autenticare gli utenti nelle app di produzione (altre informazioni).

  1. In Gestisci selezionare Autenticazione.
  2. In Concessione implicita e flussi ibridi selezionare la casella di controllo token ID (usati per i flussi impliciti e ibridi).
  3. Seleziona Salva.

Passaggio 5: Proteggere la funzione di Azure

L'estensione di autenticazione personalizzata di Microsoft Entra usa il flusso da server a server per ottenere un token di accesso inviato nell'intestazione Authorization HTTP alla funzione di Azure. Quando si pubblica la funzione in Azure, in particolare in un ambiente di produzione, è necessario convalidare il token inviato nell'intestazione dell'autorizzazione.

Per proteggere la funzione di Azure, seguire questa procedura di integrazione dell'autenticazione di Microsoft Entra, in modo da convalidare i token in ingresso con la registrazione dell'applicazione API degli eventi di autenticazione di Funzioni di Azure.

Nota

Se l'app per le funzioni di Azure è ospitata in un tenant di Azure diverso rispetto al tenant in cui è registrata l'estensione di autenticazione personalizzata, passare al passaggio del provider di identità OpenID Connect.

  1. Accedere al portale di Azure.
  2. Passare e selezionare l'app per le funzioni pubblicata in precedenza.
  3. Selezionare Autenticazione dal menu a sinistra.
  4. Selezionare Aggiungi provider di identità.
  5. Dal menu a discesaSelezionare Microsoft come provider di identità.
  6. In Tipo di registrazione app-App> selezionare Seleziona una registrazione dell'app esistente in questa directory e selezionare la registrazione dell'app per le API degli eventi di autenticazione Funzioni di Azure creata in precedenza durante la registrazione del provider di posta elettronica personalizzato.
  7. Aggiungere la scadenza del segreto client per l'app.
  8. In Richieste non autenticate selezionare HTTP 401 Non autorizzato come provider di identità.
  9. Deselezionare l'opzione Archivio token.
  10. Selezionare Aggiungi per aggiungere l'autenticazione alla funzione di Azure.

Screenshot che mostra come aggiungere l'autenticazione all'app per le funzioni.

5.1 Uso del provider di identità OpenID Connect

Se è stato configurato il provider di identità Microsoft, ignorare questo passaggio. In caso contrario, se la funzione di Azure è ospitata in un tenant diverso rispetto al tenant in cui è registrata l'estensione di autenticazione personalizzata, seguire questa procedura per proteggere la funzione:

  1. Accedere al portale di Azure, poi passare e selezionare l'app per le funzioni pubblicata in precedenza.

  2. Selezionare Autenticazione nel riquadro sinistro.

  3. Selezionare Aggiungi provider di identità.

  4. Selezionare OpenID Connect come provider di identità.

  5. Specificare un nome, ad esempio Microsoft Entra ID Contoso.

  6. Nella voce metadati immettere l'URL seguente per l'URL del documento. Sostituire con l'ID {tenantId} tenant di Microsoft Entra e {tenantname} con il nome del tenant senza "onmicrosoft.com".

    https://{tenantname}.ciamlogin.com/{tenantId}/v2.0/.well-known/openid-configuration

  7. In Registrazione app immettere l'ID applicazione (ID client) della registrazione app API degli eventi di autenticazione di Funzioni di Azurecreata in precedenza.

  8. Nell'interfaccia di amministrazione di Microsoft Entra:

    1. Selezionare la registrazione app API degli eventi di autenticazione di Funzioni di Azurecreata in precedenza.
    2. Selezionare Certificati e segreti>Segreti client>Nuovo segreto client.
    3. Aggiungere una descrizione per il segreto client.
    4. Selezionare una scadenza per il segreto o specificare una durata personalizzata.
    5. Selezionare Aggiungi.
    6. Registrare il valore del segreto da usare nel codice dell'applicazione client. Questo valore del segreto non viene mai più visualizzato dopo aver lasciato questa pagina.

  9. Tornare alla funzione di Azure e, in Registrazione app, immettere il segreto client.

  10. Deselezionare l'opzione Archivio token.

  11. Selezionare Aggiungi per aggiungere il provider di identità OpenID Connect.

Passaggio 6: Testare l'applicazione

Per testare il provider di posta elettronica personalizzato, seguire questa procedura:

  1. Aprire un nuovo browser privato e accedere tramite l'URL seguente.

    https://{tenantname}.ciamlogin.com/{tenant-id}/oauth2/v2.0/authorize?client_id={App_to_sendotp_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

  2. Sostituire {tenant-id} con l'ID tenant, il nome del tenant o uno dei nomi di dominio verificati. Ad esempio: contoso.onmicrosoft.com.

  3. Sostituire {tenantname} con il nome del tenant senza "onmicrosoft.com".

  4. Sostituire {App_to_sendotp_ID} con l'ID registrazione dell'applicazione My Test.

  5. Assicurarsi di accedere usando un account passcode monouso di posta elettronica. Selezionare quindi Invia codice. Assicurarsi che il codice inviato agli indirizzi di posta elettronica registrati usi il provider personalizzato registrato in precedenza.

Passaggio 7: Eseguire il fallback al provider Microsoft

Se si verifica un errore all'interno dell'API di estensione, per impostazione predefinita Entra ID non invierà un OTP all'utente. È invece possibile impostare il comportamento in caso di errore per il fallback al provider Microsoft.

Per abilitare questa operazione, eseguire la richiesta seguente. Sostituire {customListenerOjectId} con l'ID del listener di autenticazione personalizzato registrato in precedenza.

  • È necessaria l'autorizzazione delegata EventListener.ReadWrite.All.
PATCH https://graph.microsoft.com/beta/identity/authenticationEventListeners/{customListenerOjectId}

{
    "@odata.type": "#microsoft.graph.onEmailOtpSendListener",
    "handler": {
        "@odata.type": "#microsoft.graph.onOtpSendCustomExtensionHandler",
        "configuration": {
            "behaviorOnError": {
                "@odata.type": "#microsoft.graph.fallbackToMicrosoftProviderOnError"
            }
        }
    }
}

Vedi anche