Compartilhar via


Referência de evento de envio de OTP por email

Aplica-se a: Círculo branco com símbolo X cinza. Locatários de força de trabalho Círculo verde com marca de verificação branca. 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.