Настройка настраиваемого поставщика электронной почты для однократных событий отправки секретного кода

Применяется: зеленый круг с символом белой галочки, указывающим, что следующее содержимое применяется к внешним клиентам. Внешние клиенты (дополнительные сведения)

В этой статье содержится руководство по конфигурированию и настройке индивидуального провайдера электронной почты для типа события отправки одноразового пароля (OTP). Событие активируется при активации электронной почты OTP, что позволяет вызывать REST API для использования собственного поставщика электронной почты путем вызова REST API.

Просмотрите это видео, чтобы узнать, как настроить электронные письма проверки с помощью Microsoft Entra пользовательских расширений проверки подлинности с помощью веб-API на основе Azure Logic Apps. Приложение логики позволяет пользователям создавать рабочие процессы с помощью визуального конструктора.

Предварительные требования

Знакомство и понимание концепций, описанных в расширениях пользовательской проверки подлинности.
Подписка Azure. Если у вас нет существующей учетной записи Azure, зарегистрируйтесь на бесплатную пробную версию или используйте преимущества вашей подписки Visual Studio при создании учетной записи.
Microsoft Entra ID внешний арендатор.
Поставщик услуг ретрансляции почты:
- Azure Communication Services
- SendGrid
- Ресурс служб коммуникации Azure. Если у вас нет, создайте в "Кратком руководстве: создание и управление ресурсами служб коммуникации" используя новую или существующую группу ресурсов.
- Ресурс служб коммуникации электронной почты Azure создан и готов к работе с подготовленным доменом. Если у вас нет ресурса, обратитесь к Quickstart: создание ресурсов службы коммуникации электронной почты и управление ими и использование той же группы ресурсов, что и Azure Communication Services.
- Активный ресурс служб коммуникации, подключенный к домену электронной почты. См. Краткое руководство: Как подключить проверенный домен электронной почты
- (Необязательно) Отправить электронное письмо с помощью Azure Communication Services для проверки отправки писем нужным получателям и проверки конфигурации вашего приложения для отправки электронной почты.
- Учетная запись SendGrid. Если у вас еще нет учетной записи SendGrid, начните с настройки учетной записи SendGrid. Инструкции по настройке см. в разделе Create a SendGrid Account раздела How to send email using SendGrid with Azure.

Шаг 1. Создание приложения-функции Azure

В этом разделе показано, как настроить приложение-функцию Azure на портале Azure. API функции — это шлюз для вашего поставщика почты. Вы создаете приложение-функцию Azure для размещения функции триггера HTTP и настройки параметров в функции.

Совет

Действия, описанные в этой статье, могут немного отличаться в зависимости от портала, с которого вы начинаете.

Войдите на портал Azure как минимум администратор Application Administrator и Authentication Administrator.
В меню портала Azure или на странице Home выберите Создать ресурс.
Найдите и выберите приложение-функцию и нажмите кнопку "Создать".
На странице "Создание приложения-функции" выберите "Потребление", а затем нажмите кнопку "Выбрать".

На странице создания приложения-функции (потребления) на вкладке "Основные сведения" создайте приложение-функцию с помощью параметров, указанных в следующей таблице:

Настройка	Предлагаемое значение	Описание
Подписка	Ваша подписка	Подписка, в рамках которой создается новое функциональное приложение.
Группа ресурсов	Группа компаний myResourceGroup	Выберите группу ресурсов, используемую для настройки службы коммуникации Azure и Email Communication Service в рамках предварительных требований
Имя приложения-функции	Глобально уникальное имя	Имя, определяющее новое приложение-функцию. Допустимые символы: `a-z` (без учета регистра), `0-9` и `-`.
Развертывание кода или образа контейнера	Код	Параметр для публикации файлов кода или контейнера Docker. В этом руководстве выберите Код.
Стек среды выполнения	.NET	Предпочитаемый язык программирования. В этом руководстве выберите .NET.
Версия	8 (LTS) в процессе выполнения	Версия среды выполнения .NET. В рамках процесса вы можете создавать и изменять функции на портале, что рекомендуется для следования этому руководству.
Область	Предпочтительный регион	Выберите регион , расположенный рядом с вами или рядом с другими службами, к которым могут обращаться ваши функции.
Операционная система	Windows	Операционная система предварительно выбирается на основе выбора стека среды выполнения.

Выберите "Проверка и создание ", чтобы просмотреть выбранные параметры конфигурации приложения, а затем нажмите кнопку "Создать". Развертывание займет несколько минут.
После развертывания выберите "Перейти к ресурсу" , чтобы просмотреть новое приложение-функцию.

1.1. Создание функции триггера HTTP

После создания приложения-функции Azure создайте функцию триггера HTTP. Триггер HTTP позволяет вызвать функцию с помощью HTTP-запроса. Функция с HTTP-триггером привязана к настраиваемому расширению проверки подлинности в Microsoft Entra.

В вашем функциональном приложении в меню выберите Функции.
Выберите "Создать функцию".
В окне "Создать функцию " в разделе "Выбор шаблона" найдите и выберите шаблон триггера HTTP . Нажмите кнопку "Далее".
В разделе "Сведения о шаблоне" введите CustomAuthenticationExtensionsAPI для свойства "Имя функции ".
Для уровня авторизации выберите "Функция".
Нажмите кнопку "Создать".

1.2 Изменение функции

Код начинается с чтения входящего объекта JSON. Microsoft Entra ID отправляет объект JSON в API. В этом примере он считывает адрес электронной почты (идентификатор) и OTP. Затем код отправляет сведения в службу коммуникаций для отправки сообщения электронной почты с помощью динамического шаблона.

В этом руководстве показано событие отправки OTP с помощью Azure Communication Services и SendGrid. Используйте вкладки, чтобы выбрать реализацию.

Azure Communication Services
SendGrid

В меню выберите "Код и тест".

Замените весь код следующим фрагментом кода.

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

Выберите «Получить URL функции» и скопируйте URL ключа функции, который отныне будет использован и обозначен как {Function_Url}. Закройте функцию.

В меню выберите "Код и тест".

Замените весь код следующим фрагментом кода.

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.CustomEmailSendGrid
{
    public class CustomEmailSendGrid
    {
        private readonly ILogger<CustomEmailSendGrid> _logger;

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

        [Function("OnOtpSend_CustomEmailSendGrid")]
        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 apiKey = Environment.GetEnvironmentVariable("mail_sendgridKey");
            var sender = Environment.GetEnvironmentVariable("mail_sender");
            var senderName = Environment.GetEnvironmentVariable("mail_senderName");
            var template = Environment.GetEnvironmentVariable("mail_template");

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

            try
            {
                if (!string.IsNullOrEmpty(apiKey))
                {
                    var client = new HttpClient();
                    var request = new HttpRequestMessage(HttpMethod.Post, "https://api.sendgrid.com/v3/mail/send");
                    request.Headers.Add("Authorization", $"Bearer {apiKey}");

                    SendGridMessage msg = new SendGridMessage()
                    {
                        template_id = template,
                        from = new Person { email = sender, name = senderName },
                        personalizations = new List<Personalization> {

                new Personalization(emailTo, code)
                }
                    };

                    request.Content = new StringContent(msg.ToString(), null, "application/json");

                    var response = await client.SendAsync(request);
                    _logger.LogInformation($"Sendgrid response: {response.StatusCode}");
                    response.EnsureSuccessStatusCode();
                    _logger.LogInformation(await response.Content.ReadAsStringAsync());
                }
            }
            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>";
        }
    }

    /********* SendGrid data ********/
    public class SendGridMessage
    {
        public List<Personalization> personalizations { get; set; }
        public string template_id { get; set; }
        public Person from { get; set; }

        public override string ToString()
        {
            return JsonSerializer.Serialize(this, new JsonSerializerOptions { WriteIndented = true });
        }
    }

    public class Personalization
    {
        public Personalization(string to, string otp)
        {
            this.to = new List<Person>() { new Person() { email = to } };
            this.dynamic_template_data = new DynamicTemplateData() { otp = otp };
        }

        public List<Person> to { get; set; }
        public DynamicTemplateData dynamic_template_data { get; set; }
    }

    public class DynamicTemplateData
    {
        public string otp { get; set; }
    }

    public class Person
    {
        public string email { get; set; }

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string name { get; set; }
    }

    public class OTPCodeTemplateData
    {
        [JsonPropertyName("otp")]
        public string OTPCode { get; set; }

    }
}

Выберите «Получить URL функции» и скопируйте URL ключа функции, который отныне будет использован и обозначен как {Function_Url}. Закройте функцию.

Шаг 2. Добавление строк подключения в функцию Azure

Строки подключения позволяют приложению-функции подключаться и аутентифицироваться в почтовом релей-сервере. Для Azure Communication Services и SendGrid добавьте эти строки подключения в приложение-функцию Azure в качестве переменных среды.

Azure Communication Services
SendGrid

2.1. Извлечение строк подключения и конечных точек службы из ресурса Azure Communication Services

Вы можете получить доступ к строкам подключения служб коммуникации и конечным точкам службы на портале Azure или программным способом с помощью api Azure Resource Manager.

На странице Home на портале Azure откройте меню портала, найдите и выберите All resources.
Найдите и выберите службу Azure Communications Service, созданную в рамках предварительных требований к этой статье.
В левой области выберите раскрывающийся список "Параметры ", а затем выберите "Ключи".
Скопируйте конечную точку и из первичного ключа скопируйте значения для строки "Ключ " и "Подключение".

2.2. Добавление строк подключения в функцию Azure

Вернитесь к функции Azure, созданной в Создание приложения функции Azure.

На странице обзора вашего приложения-функции в меню слева выберите Параметры>Переменные среды и добавьте следующие параметры приложения. После добавления всех параметров нажмите кнопку "Применить", а затем подтвердите.

Настройка	Значение (пример)	Описание
mail_connectionString	`https://ciamotpcommsrvc.unitedstates.communication.azure.com/:accesskey=`	Точка подключения Azure Communication Services
mail_sender	from.email@myemailprovider.com	Адрес электронной почты отправителя.
mail_subject	Код проверки учетной записи	Тема сообщения электронной почты.

2.1. Добавление строк подключения в функцию Azure

Вернитесь к функции Azure, созданной в создании приложения-функции Azure.

Настройка	Значение (пример)	Описание
mail_sendgridKey	SG.12a3456789...	Ключ API SendGrid.
mail_sender	from.email@myemailprovider.com	Адрес электронной почты отправителя.
mail_senderName	Контосо	Имя отправителя электронной почты.
mail_template	d-01234567....	Идентификатор динамического шаблона SendGrid.

Шаг 3. Регистрация настраиваемого расширения аутентификации

На этом шаге вы настроите пользовательское расширение проверки подлинности, которое Microsoft Entra ID используется для вызова функции Azure. Расширение пользовательской проверки подлинности содержит сведения о конечной точке REST API, утверждениях, которые он анализирует из REST API, а также о том, как пройти проверку подлинности в REST API. Используйте портал Azure или Microsoft Graph для регистрации приложения, чтобы аутентифицировать ваше пользовательское расширение проверки подлинности в вашей функции Azure.

портал Azure
Microsoft Graph

Регистрация кастомного расширения аутентификации

Войдите на портал Azure как минимум администратор Application Administrator и Authentication Administrator.
Найдите и выберите Microsoft Entra ID и выберите приложения Enterprise.
Выберите пользовательские расширения для проверки подлинности, затем выберите Создать пользовательское расширение.
В разделе "Основы" выберите тип события EmailOtpSend и нажмите кнопку "Далее".
На вкладке "Конфигурация конечной точки" введите следующие свойства, а затем нажмите кнопку "Далее " для продолжения.
- Имя — для вашего настраиваемого расширения аутентификации. Например, отправка OTP по электронной почте.
- Target Url — {Function_Url} URL-адреса вашей функции Azure. Перейдите на страницу Overview приложения-функции Azure, а затем выберите созданную функцию. На странице обзора функции выберите "Получить URL-адрес функции" и используйте значок копирования, чтобы скопировать URL-адрес customauthenticationextension_extension (системный ключ).
- Описание — описание пользовательских расширений проверки подлинности.
На вкладке "Проверка подлинности API " выберите параметр "Создать новое приложение" , чтобы создать регистрацию приложения, представляющего приложение-функцию.
Присвойте приложению имя, например Azure Functions API событий проверки подлинности и выберите Next.
На вкладке "Приложения" выберите приложение, которое необходимо связать с пользовательским расширением проверки подлинности. Нажмите кнопку "Далее". Вы можете применить его ко всему арендатору, установив соответствующий флажок. Нажмите кнопку "Далее ", чтобы продолжить.
На вкладке "Обзор" проверьте правильность данных для настраиваемого расширения проверки подлинности. Обратите внимание на идентификатор приложения App ID в разделе Аутентификация API, который необходим для настройки аутентификации для вашей функции Azure в вашем приложении функции Azure. Нажмите кнопку "Создать".

3.1 Регистрация приложения в обозревателе Graph

Войдите в Graph Explorer с помощью учетной записи, в которой домашний клиент является клиентом, в котором вы хотите управлять пользовательским расширением проверки подлинности. Учетная запись должна иметь права для регистрации и управления регистрацией приложения в тенанте.

Выполните следующий запрос.

POST https://graph.microsoft.com/v1.0/applications
Content-type: application/json

{
    "displayName": "authenticationeventsAPI"
}

В ответе запишите значение id и appId для недавно созданной регистрации приложения. Эти значения ссылаются в этой статье как {authenticationeventsAPI_ObjectId} и {authenticationeventsAPI_AppId} соответственно.
Создайте субъект-службу в клиенте для регистрации приложения authenticationeventsAPI .
Выполните следующий запрос в обозревателе Graph. Замените {authenticationeventsAPI_AppId} на значение appId, которое вы записали на предыдущем шаге.
```
POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
    "appId": "{authenticationeventsAPI_AppId}"
}
```

3.2. Задайте URI идентификатора приложения, версию маркера доступа и необходимый доступ к ресурсам

Обновите только что созданное приложение, чтобы задать значение URI идентификатора приложения, версию маркера доступа и необходимый доступ к ресурсам.

В обозревателе Graph выполните следующий запрос.

Задайте значение URI идентификатора приложения в свойстве identifierUris . Замените {Function_Url_Hostname} именем хоста {Function_Url}, записанным ранее.
{authenticationeventsAPI_AppId} Задайте значение с идентификатором appId, записанным ранее.

Например, api://authenticationeventsAPI.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444. Запишите это значение. Вам понадобится позже в этой статье вместо {functionApp_IdentifierUri}.

PATCH https://graph.microsoft.com/v1.0/applications/{authenticationeventsAPI_ObjectId}
Content-type: application/json
{
    "identifierUris": [
        "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"
    ],    
    "api": {
        "requestedAccessTokenVersion": 2,
        "acceptMappedClaims": null,
        "knownClientApplications": [],
        "oauth2PermissionScopes": [],
        "preAuthorizedApplications": []
    },
    "requiredResourceAccess": [
        {
            "resourceAppId": "00000003-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "214e810f-fda8-4fd7-a475-29461495eb00",
                    "type": "Role"
                }
            ]
        }
    ]
}

3.3 Регистрация настраиваемого расширения аутентификации

Затем зарегистрируйте настраиваемое расширение проверки подлинности и свяжите его с регистрацией приложения для Функции Azure и конечной точкой Функции Azure {Function_Url}.

В обозревателе Graph выполните следующий запрос. Замените {Function_Url} именем узла приложения-функции Azure. Замените {functionApp_IdentifierUri} на идентификатор URI, использованный на предыдущем этапе.

Требуется делегированное разрешение CustomAuthenticationExtension.ReadWrite.All .

POST https://graph.microsoft.com/beta/identity/customAuthenticationExtensions
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.OnOtpSendCustomExtension",
    "displayName": "onEmailOtpSendCustomExtension",
    "description": "Use an external Email provider to send OTP Codes.",
    "authenticationConfiguration": {
        "@odata.type": "#microsoft.graph.azureAdTokenAuthentication",
        "resourceId": "{functionApp_IdentifierUri}"
    },
    "endpointConfiguration": {
        "@odata.type": "#microsoft.graph.httpRequestEndpoint",
        "targetUrl": "{Function_Url}"
    }
}

Запишите значение идентификатора созданного объекта поставщика OTP электронной почты, который используется далее в этой статье вместо {customExtensionObjectId}.

3.4 Назначение пользовательского поставщика электронной почты приложению

Чтобы использовать кастомные электронные письма, вы должны назначить поставщика кастомных электронных писем для вашего приложения. Настраиваемый поставщик электронной почты использует настраиваемое расширение проверки подлинности, настроенное с прослушивателем события отправки OTP.

Выполните следующие действия, чтобы подключить приложение "Мой тест " с пользовательским расширением проверки подлинности:

Войдите в Graph Explorer с помощью учетной записи, в которой домашний клиент является клиентом, в котором вы хотите управлять пользовательским расширением проверки подлинности.

Выполните следующий запрос. Замените {App_to_sendotp_ID} идентификатором приложения My Test , записанным ранее. Замените {customExtensionObjectId} пользовательским идентификатором расширения проверки подлинности, записанным ранее.

Для этого требуется делегированное разрешение EventListener.ReadWrite.All.

POST https://graph.microsoft.com/beta/identity/authenticationEventListeners
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.onEmailOtpSendListener",
    "conditions": {
        "applications": {
            "includeAllApplications": false,
            "includeApplications": [
                {
                    "appId": "{App_to_sendotp_ID}"
                }
            ]
        }
    },
    "priority": 500,
    "handler": {
        "@odata.type": "#microsoft.graph.onOtpSendCustomExtensionHandler",
        "customExtension": {
            "id": "{customExtensionObjectId}"
        }
    }
}

Запишите значение идентификатора созданного объекта прослушивателя, который используется далее в этой статье вместо {customListenerObjectId}.

После создания расширения пользовательской проверки подлинности откройте приложение на портале в разделе App registrations и выберите разрешения API.

На странице разрешений API нажмите кнопку "Предоставить согласие администратора" для "YourTenant" , чтобы предоставить администратору согласие на зарегистрированное приложение, которое позволяет пользовательскому расширению проверки подлинности пройти проверку подлинности в API. Расширение настраиваемой проверки подлинности использует client_credentials для аутентификации в функциональном приложении Azure с помощью разрешения Receive custom authentication extension HTTP requests.

На следующем снимках экрана показано, как предоставить разрешения.

Шаг 4. Настройка приложения OpenID Connect для тестирования

Чтобы получить токен и протестировать пользовательское расширение аутентификации, вы можете использовать приложение https://jwt.ms. Это веб-приложение, принадлежащее Майкрософт, которое отображает декодированное содержимое токена (содержимое токена никогда не выходит за пределы вашего браузера).

Выполните следующие действия, чтобы зарегистрировать веб-приложение jwt.ms :

4.1 Регистрация тестового веб-приложения

Войдите в центр администрирования Microsoft Entra как минимум как Администратор приложений.
Перейдите к Entra ID>Регистрации приложений.
Выберите "Создать регистрацию".
Введите имя приложения. Например, мое тестовое приложение.
В разделе "Поддерживаемые типы учетных записей" выберите только учетные записи в этом каталоге организации.
В раскрывающемся списке "Выбор платформы" в URI перенаправления выберите веб-сайт и введите https://jwt.ms в текстовое поле URL-адреса.
Нажмите кнопку "Регистрация", чтобы завершить регистрацию приложения.
В вашем приложении в разделе "Обзор" скопируйте идентификатор приложения (клиента), который используется позже и называется {App_to_sendotp_ID}. В Microsoft Graph это свойство называется appId.

На следующем снимку экрана показано, как зарегистрировать приложение My Test.

4.1 Получение идентификатора приложения

В вашей регистрации приложения в разделе Обзор скопируйте идентификатор приложения (клиента). Идентификатор приложения будет ссылаться как {App_to_sendotp_ID} на следующих этапах. В Microsoft Graph это свойство называется appId.

4.2 Включение неявного потока

Тестовое приложение jwt.ms использует неявный поток. Включите неявный поток в регистрации приложения My Test :

Важный

Корпорация Майкрософт рекомендует использовать самый безопасный поток проверки подлинности. Поток проверки подлинности, используемый для тестирования в этой процедуре, требует высокого уровня доверия к приложению и несет риски, которые не присутствуют в других потоках. Этот подход не следует использовать для проверки подлинности пользователей в рабочих приложениях (дополнительные сведения).

В разделе "Управление" выберите "Проверка подлинности".
В разделе "Неявное предоставление" и "Гибридные потоки" выберите флажок "Идентификатор токена" (используются для неявных и гибридных потоков).
Нажмите кнопку "Сохранить".

Шаг 5. Защита функции Azure

Microsoft Entra пользовательское расширение проверки подлинности использует серверный поток для получения маркера доступа, который отправляется в заголовке HTTP Authorization в вашу функцию Azure. При публикации функции в Azure, особенно в рабочей среде, необходимо проверить маркер, отправленный в заголовке авторизации.

Чтобы защитить функцию Azure, выполните следующие действия для интеграции аутентификации Microsoft Entra. Это позволит проверять входящие токены с использованием API событий аутентификации Azure Functions регистрации приложения.

Примечание.

Если приложение Azure Functions размещено в другом клиенте Azure, отличном от клиента, в котором зарегистрировано ваше пользовательское расширение проверки подлинности, перейдите к этапу использование поставщика удостоверений OpenID Connect.

Войдите на портал Azure.
Перейдите и выберите приложение-функцию, которое вы ранее опубликовали.
Выберите проверку подлинности в меню слева.
Выберите «Добавить поставщик удостоверений».
В раскрывающемся меню выберите Майкрософт в качестве поставщика удостоверений.
В разделе Регистрации приложения - >Тип регистрации приложения выберите существующую регистрацию приложения в этом каталоге и выберите регистрацию приложения API событий аутентификации Azure Functions, которую вы создали ранее при регистрации пользовательского поставщика электронной почты.
Добавьте срок действия секрета клиента для приложения.
В разделе "Неавторизованные запросы" выберите HTTP 401 Unauthorizeded в качестве поставщика удостоверений.
Отмените выбор параметра хранилища токенов .
Выберите Add, чтобы добавить проверку подлинности в функцию Azure.

5.1 Использование поставщика удостоверений OpenID Connect

Если вы настроили поставщика удостоверений Майкрософт, пропустите этот шаг. В противном случае, если функция Azure размещена в другом клиенте, отличном от клиента, в котором зарегистрировано пользовательское расширение проверки подлинности, выполните следующие действия, чтобы защитить функцию:

Войдите на портал Azure, затем перейдите к и выберите ранее опубликованное функциональное приложение.
Выберите проверку подлинности в левой области.
Выберите «Добавить поставщик удостоверений».
Выберите OpenID Connect в качестве поставщика удостоверений.
Укажите имя, например Contoso Microsoft Entra ID.
В разделе записи метаданных введите следующий URL-адрес в URL-адрес документа. Замените {tenantId} идентификатором клиента Microsoft Entra и {tenantname} именем клиента без суффикса 'onmicrosoft.com'.
```
https://{tenantname}.ciamlogin.com/{tenantId}/v2.0/.well-known/openid-configuration
```
В разделе Регистрация приложений введите идентификатор приложения (идентификатор клиента) регистрации приложения API событий аутентификации Azure Functions, которую вы создали ранее.
В центре администрирования Microsoft Entra:
1. Выберите регистрацию приложения API событий проверки подлинности Azure Functions, которую вы создали ранее.
2. Выберите сертификаты и секреты>секреты клиента>новый секрет клиента.
3. Добавьте описание секрета клиента.
4. Выберите срок действия секрета или укажите настраиваемое время существования.
5. Нажмите кнопку "Добавить".
6. Запишите значение секрета для использования в коде клиентского приложения. Это значение секрета больше нигде не отображается после закрытия страницы.
Вернитесь к функции Azure и в разделе Регистрация приложений введите секрет клиента.
Отмените выбор параметра хранилища токенов .
Выберите "Добавить ", чтобы добавить поставщика удостоверений OpenID Connect.

Шаг 6. Тестирование приложения

Чтобы протестировать пользовательского поставщика электронной почты, выполните следующие действия.

Откройте новое окно в режиме инкогнито и войдите на сайт через следующий URL-адрес.

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

Замените {tenant-id} на идентификатор арендатора, имя арендатора или одно из проверенных доменных имен. Например, contoso.onmicrosoft.com.
Замените {tenantname} именем арендатора без onmicrosoft.com.
Замените {App_to_sendotp_ID}идентификатором регистрации приложения "Мой тест".
Убедитесь, что вы используете учетную запись с одноразовым паролем из электронной почты. Затем нажмите кнопку "Отправить код". Убедитесь, что код, отправленный на зарегистрированные адреса электронной почты, использует настраиваемый поставщик, зарегистрированный выше.

Шаг 7. Возврат к поставщику Майкрософт

Если в API вашего расширения происходит ошибка, Entra ID по умолчанию не отправляет OTP пользователю. Вместо этого можно задать поведение при ошибке, чтобы вернуться к поставщику Майкрософт.

Чтобы включить это, выполните следующий запрос. Замените {customListenerObjectId} пользовательским идентификатором (ID) прослушивателя проверки подлинности, записанным ранее.

Для этого требуется делегированное разрешение 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"
            }
        }
    }
}

См. также

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-03-11