Informazioni di riferimento per l'invio tramite posta elettronica dell'evento OTP

Si applica a: inquilini della forza lavoro inquilini esterni (scopri di più)

Per configurare un provider di posta elettronica personalizzato per gli eventi di invio di passcode monouso (OTP), creare un'estensione di autenticazione personalizzata e richiamarla in punti specifici del flusso utente. Quando l'evento emailOtpSend viene attivato, Microsoft Entra invia un passcode monouso all'API REST specificata di cui si è proprietari.

L'API REST usa quindi il provider di posta elettronica scelto, ad esempio Il servizio di comunicazione di Azure o SendGrid per inviare il passcode monouso con il modello di posta elettronica personalizzato, dall'indirizzo, dall'oggetto di posta elettronica e altro ancora. Questo articolo descrive lo schema dell'API REST per l'evento emailOtpSend.

Richiesta all'API REST esterna

L'estensione di autenticazione personalizzata definita in Microsoft Entra ID esegue una chiamata HTTP all'API REST con un payload JSON. Il payload JSON contiene l'indirizzo di posta elettronica dell'utente e il passcode monouso. La richiesta include anche attributi del contesto di autenticazione e informazioni sull'applicazione che l'utente intende accedere.

La richiesta HTTP seguente illustra come Microsoft Entra richiama l'API REST. Questa richiesta HTTP può essere usata per eseguire il debug dell'API REST simulando una richiesta da Microsoft Entra.

POST https://example.azureWebsites.net/api/functionName

Content-Type: application/json

[Request payload]

Il documento JSON seguente fornisce un esempio di payload di richiesta:

{
    "type": "microsoft.graph.authenticationEvent.emailOtpSend",
    "source": "/tenants/ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d/applications/bbbbbbbb-cccc-dddd-2222-333333333333",
    "data": {
        "@odata.type": "microsoft.graph.onOtpSendCalloutData",
        "otpContext": {
            "identifier": "someone@example.com",
            "oneTimeCode": "12345678"
        },
        "tenantId": "ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d",
        "authenticationEventListenerId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "customAuthenticationExtensionId": "11112222-bbbb-3333-cccc-4444dddd5555",
        "authenticationContext": {
            "correlationId": "3333dddd-44ee-ffff-aa55-bbbbbbbb6666",
            "client": {
                "ip": "192.168.0.0",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "requestType": "signUp",
            "clientServicePrincipal": {
                "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
                "appId": "bbbbbbbb-cccc-dddd-2222-333333333333",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
                "appId": "bbbbbbbb-cccc-dddd-2222-333333333333",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            }
        }
    }
}

Risposta dall'API REST esterna

Microsoft Entra ID prevede una risposta api REST nel http seguente.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

Nella risposta HTTP specificare il documento JSON seguente:

{
    "data": {
        "@odata.type": "microsoft.graph.OnOtpSendResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.OtpSend.continueWithDefaultBehavior"
            }
        ]
    }
}

Passaggi successivi

È possibile configurare un provider di posta elettronica personalizzato per l'invio di eventi con passcode monouso.