Referência de evento de envio de OTP por email

Aplica-se a: Locatários de força de trabalho Locatários externos (saiba mais)

Para configurar um provedor de email personalizado para eventos de envio de senha única (OTP) por email , crie uma extensão de autenticação personalizada e invoque-a em pontos específicos no fluxo do usuário. Quando o evento emailOtpSend é ativado, o Microsoft Entra envia uma senha única para a API REST especificada que você possui.

A API REST usa o provedor de email escolhido, como o Serviço de Comunicação do Azure ou o SendGrid, para enviar a senha única com seu modelo de email personalizado, de endereço, assunto de email e muito mais. Este artigo descreve o esquema da API REST para o evento emailOtpSend.

Solicitação para a API REST externa

A extensão de autenticação personalizada que você definiu no Microsoft Entra ID faz uma chamada HTTP para sua API REST com um payload JSON. O conteúdo JSON contém o endereço de email do usuário e a senha única. A solicitação também inclui atributos de contexto de autenticação e informações sobre o aplicativo que o usuário pretende entrar.

A solicitação HTTP a seguir demonstra como o Microsoft Entra invoca sua API REST. Essa solicitação HTTP pode ser usada para depurar sua API REST simulando uma solicitação do Microsoft Entra.

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

Content-Type: application/json

[Request payload]

O documento JSON a seguir fornece um exemplo de conteúdo de solicitação:

{
    "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"
            }
        }
    }
}

Resposta da API REST externa

A ID do Microsoft Entra espera uma resposta da API REST no HTTP a seguir.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

Na resposta HTTP, forneça o seguinte documento JSON:

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

Próximas etapas

Veja como configurar um provedor de email personalizado para eventos de envio de senha única.