Share via

Создание REST API для события запуска выдачи маркеров в Функции Azure

  • Статья

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

Необходимые компоненты

  • Базовое понимание концепций, описанных в обзоре расширений пользовательской проверки подлинности.
  • Подписка Azure с возможностью создания Функции Azure. Если у вас нет существующей учетной записи Azure, зарегистрируйтесь на бесплатную пробную версию или воспользуйтесь преимуществами подписки Visual Studio при создании учетной записи.
  • Клиент идентификатора Microsoft Entra. Для этого руководства можно использовать клиент или клиент рабочей силы.

В этой статье описывается, как создать REST API для события запуска выдачи маркеров с помощью библиотеки NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents и настроить ее для проверки подлинности. Вы создадите функцию триггера HTTP в Visual Studio или Visual Studio Code, настройте ее для проверки подлинности и развернете ее в портал Azure, где ее можно получить через Функции Azure.

Необходимые компоненты

Примечание.

Библиотека NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents в настоящее время находится в предварительной версии. Действия, описанные в этой статье, могут быть изменены. Для реализации общедоступной реализации события запуска выдачи маркеров можно сделать это с помощью портал Azure.

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

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

  1. Войдите в портал Azure как минимум приложение Администратор istrator и Администратор istrator проверки подлинности.

  2. На домашней странице или в меню портала Azure выберите Создать ресурс.

  3. Найдите и выберите приложение-функцию и нажмите кнопку "Создать".

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

    Параметр Предлагаемое значение Description
    Подписка Ваша подписка Подписка, в которой будет создано новое приложение-функция.
    Группа ресурсов myResourceGroup Выберите и существующую группу ресурсов или имя новой, в которой вы создадите приложение-функцию.
    Имя приложения-функции Глобально уникальное имя Имя, определяющее новое приложение-функцию. Допустимые символы: a-z (без учета регистра), 0-9 и -.
    Развертывание кода или образа контейнера Код Параметр для публикации файлов кода или контейнера Docker. В этом руководстве выберите "Код".
    Стек среды выполнения .NET Предпочитаемый язык программирования. В этом руководстве выберите .NET.
    Версия 6 (LTS) in-process Версия среды выполнения .NET. В процессе вы можете создавать и изменять функции на портале, которые рекомендуется использовать для этого руководства.
    Регион Предпочтительный регион Выберите регион, ближайший к вам или к другим службам, к которым могут обращаться функции.
    Операционная система Windows Операционная система предварительно выбирается на основе выбора стека среды выполнения.
    Тип плана Потребление (бессерверный) План размещения, который определяет выделение ресурсов в приложении-функции.

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

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

Создание функции для триггеров HTTP

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

  1. На странице обзора приложения-функции выберите область "Функции" и выберите "Создать функцию" в разделе "Создать" в портал Azure.
  2. В окне "Создание функции" оставьте свойство среды разработки как "Разработка" на портале. В разделе "Шаблон" выберите триггер HTTP.
  3. В разделе "Сведения о шаблоне" введите CustomAuthenticationExtensionsAPI для свойства New Function .
  4. Для уровня авторизации выберите "Функция".
  5. Нажмите кнопку создания. Снимок экрана: выбор среды разработки и шаблона.

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

Код считывает входящий объект JSON, а идентификатор Microsoft Entra отправляет объект JSON в API. В этом примере он считывает значение идентификатора корреляции. Затем код возвращает коллекцию настраиваемых утверждений, включая исходную CorrelationId, ApiVersion функцию Azure и DateOfBirthCustomRoles возвращаемую идентификатору Microsoft Entra.

  1. В меню в разделе "Разработчик" выберите "Код и тест".

  2. Замените весь код следующим фрагментом кода, а затем нажмите кнопку "Сохранить".

    #r "Newtonsoft.Json"
using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;
public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");
    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);

    // Read the correlation ID from the Microsoft Entra request    
    string correlationId = data?.data.authenticationContext.correlationId;

    // Claims to return to Microsoft Entra
    ResponseContent r = new ResponseContent();
    r.data.actions[0].claims.CorrelationId = correlationId;
    r.data.actions[0].claims.ApiVersion = "1.0.0";
    r.data.actions[0].claims.DateOfBirth = "01/01/2000";
    r.data.actions[0].claims.CustomRoles.Add("Writer");
    r.data.actions[0].claims.CustomRoles.Add("Editor");
    return new OkObjectResult(r);
}
public class ResponseContent{
    [JsonProperty("data")]
    public Data data { get; set; }
    public ResponseContent()
    {
        data = new Data();
    }
}
public class Data{
    [JsonProperty("@odata.type")]
    public string odatatype { get; set; }
    public List<Action> actions { get; set; }
    public Data()
    {
        odatatype = "microsoft.graph.onTokenIssuanceStartResponseData";
        actions = new List<Action>();
        actions.Add(new Action());
    }
}
public class Action{
    [JsonProperty("@odata.type")]
    public string odatatype { get; set; }
    public Claims claims { get; set; }
    public Action()
    {
        odatatype = "microsoft.graph.tokenIssuanceStart.provideClaimsForToken";
        claims = new Claims();
    }
}
public class Claims{
    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public string CorrelationId { get; set; }
    [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
    public string DateOfBirth { get; set; }
    public string ApiVersion { get; set; }
    public List<string> CustomRoles { get; set; }
    public Claims()
    {
        CustomRoles = new List<string>();
    }
}

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

Создание и создание приложения-функции Azure

На этом шаге вы создадите API функции триггера HTTP с помощью интегрированной среды разработки, установите необходимые пакеты NuGet и скопируйте его в пример кода. Вы создаете проект и запускаете функцию, чтобы извлечь URL-адрес локальной функции.

Создание приложения

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

  1. Откройте Visual Studio и выберите элемент Создать проект.
  2. Найдите и выберите Функции Azure, а затем нажмите кнопку "Далее".
  3. Присвойте проекту имя, например AuthEventsTrigger. Рекомендуется сопоставить имя решения с именем проекта.
  4. Выберите расположение для проекта. Выберите Далее.
  5. Выберите .NET 6.0 (долгосрочная поддержка) в качестве целевой платформы.
  6. Выберите триггер Http в качестве типа функции, а уровень авторизации имеет значение Function. Нажмите кнопку создания.
  7. В Обозреватель решений переименуйте файл Function1.cs на AuthEventsTrigger.cs и примите предложение об изменении переименования.

Установка пакетов NuGet и сборка проекта

После создания проекта необходимо установить необходимые пакеты NuGet и создать проект.

  1. В верхнем меню Visual Studio выберите "Проект" и "Управление пакетами NuGet".
  2. Перейдите на вкладку "Обзор ", а затем найдите и выберите Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents в правой области. Выберите Установить.
  3. Примените и примите изменения в отображаемых всплывающих окнах.

Добавление примеров кода

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

В файле AuthEventsTrigger.cs замените все содержимое файла следующим кодом:

using System;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;

namespace AuthEventsTrigger
{
    public static class AuthEventsTrigger
    {
        [FunctionName("onTokenIssuanceStart")]
        public static WebJobsAuthenticationEventResponse Run(
            [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log)
        {
            try
            {
                // Checks if the request is successful and did the token validation pass
                if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful)
                {
                    // Fetches information about the user from external data store
                    // Add new claims to the token's response
                    request.Response.Actions.Add(
                        new WebJobsProvideClaimsForToken(
                            new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"),
                            new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"),
                            new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"),
                            new WebJobsAuthenticationEventsTokenClaim(
                                "correlationId", 
                                request.Data.AuthenticationContext.CorrelationId.ToString())));
                }
                else
                {
                    // If the request fails, such as in token validation, output the failed request status, 
                    // such as in token validation or response validation.
                    log.LogInformation(request.StatusMessage);
                }
                return request.Completed();
            }
            catch (Exception ex) 
            { 
                return request.Failed(ex);
            }
        }
    }
}

Сборка и запуск проекта локально

Проект был создан, и был добавлен пример кода. С помощью интегрированной среды разработки необходимо создать и запустить проект локально, чтобы извлечь URL-адрес локальной функции.

  1. Перейдите к разделу "Сборка" в верхнем меню и выберите "Создать решение".
  2. Нажмите клавишу F5 или выберите AuthEventsTrigger в верхнем меню, чтобы запустить функцию.
  3. Скопируйте URL-адрес функции из терминала, который всплывает при запуске функции. Это можно использовать при настройке настраиваемого расширения проверки подлинности.

Рекомендуется протестировать функцию локально перед развертыванием в Azure. Мы можем использовать фиктивный текст JSON, который имитирует запрос, который идентификатор Microsoft Entra отправляет в REST API. Используйте предпочитаемое средство тестирования API для вызова функции напрямую.

  1. В интегрированной среде разработки откройте local.settings.json и замените код следующим json. Мы можем задать "AuthenticationEvents__BypassTokenValidation" значение true для локальных целей тестирования.

    {
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "AzureWebJobsSecretStorageType": "files",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__BypassTokenValidation" : true
  }
}

  2. Используя предпочитаемое средство тестирования API, создайте новый HTTP-запрос и задайте для метода HTTP значение POST.

  3. Используйте следующий текст JSON, который имитирует запрос идентификатора Microsoft Entra, отправляется в REST API.

    {
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
        "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
        "authenticationContext": {
            "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2023-08-16T00:00:00Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "Casey Jensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

  4. Выберите "Отправить", и вы должны получить ответ JSON, аналогичный следующему:

    {
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "customClaim1": "customClaimValue1",
                    "customClaim2": [
                        "customClaimString1",
                        "customClaimString2" 
                    ]
                }
            }

        ]
    }
}

Развертывание функции и публикация в Azure

Эта функция должна быть развернута в Azure с помощью нашей интегрированной среды разработки. Убедитесь, что вы правильно вошли в учетную запись Azure, чтобы функция была опубликована.

  1. В Обозреватель решений щелкните проект правой кнопкой мыши и выберите "Опубликовать".

  2. В целевом объекте выберите Azure, а затем нажмите кнопку "Далее".

  3. Выберите приложение-функцию Azure (Windows) для конкретного целевого объекта, выберите приложение-функцию Azure (Windows), а затем нажмите кнопку "Далее".

  4. В экземпляре функции используйте раскрывающийся список "Имя подписки", чтобы выбрать подписку, в которой будет создано новое приложение-функция.

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

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

    Параметр Предлагаемое значение Описание:
    Имя Глобально уникальное имя Имя, определяющее новое приложение-функцию. Допустимые символы: a-z (без учета регистра), 0-9 и -.
    Подписка Ваша подписка Подписка, в которой создается новое приложение-функция.
    Группа ресурсов myResourceGroup Выберите существующую группу ресурсов или назовите новую, в которой вы создадите приложение-функцию.
    Тип плана Потребление (бессерверный) План размещения, который определяет выделение ресурсов в приложении-функции.
    Местонахождение Предпочтительный регион Выберите регион, ближайший к вам или к другим службам, к которым могут обращаться функции.
    Хранилище Azure Ваша учетная запись хранения Учетная запись хранения Azure — обязательный ресурс для среды выполнения Функций. Выберите Создать, чтобы настроить учетную запись хранения общего назначения.
    Application Insights По умолчанию Функция Azure Monitor. Это автоматически выбрано, выберите тот, который вы хотите использовать или настроить новый.

  7. Подождите несколько минут, пока приложение-функция будет развернуто. После закрытия окна нажмите кнопку "Готово".

  8. Откроется новая область публикации . В верхней части нажмите кнопку "Опубликовать". Подождите несколько минут, пока приложение-функция будет развернуто и отобразится в портал Azure.

Настройка проверки подлинности для функции Azure

Существует три способа настройки проверки подлинности для функции Azure:

По умолчанию код был настроен для проверки подлинности в портал Azure с помощью переменных среды. Используйте приведенные ниже вкладки, чтобы выбрать предпочтительный метод реализации переменных среды или также обратиться к встроенной приложение Azure проверке подлинности и авторизации службы. Для настройки переменных среды используйте следующие значения:

Имя. Значение
AuthenticationEvents__AudienceAppId Пользовательский идентификатор приложения расширения проверки подлинности, настроенный в настройке пользовательского поставщика утверждений для события выдачи маркера
AuthenticationEvents__AuthorityUrl • Клиент рабочей силы https://login.microsoftonline.com/<tenantID>
• Внешний клиент https://<mydomain>.ciamlogin.com
AuthenticationEvents__AuthorizedPartyAppId 99045fe1-7639-4a75-9d4a-577b6ca3810f или другую авторизованную сторону

Настройка проверки подлинности в портал Azure с помощью переменных среды

  1. Войдите в портал Azure как минимум приложение Администратор istrator или authentication Администратор istrator.
  2. Перейдите к созданному приложению-функции и в разделе Параметры выберите "Конфигурация".
  3. В разделе "Параметры приложения" выберите новый параметр приложения и добавьте переменные среды из таблицы и связанные с ними значения.
  4. Нажмите кнопку Сохранить, чтобы сохранить параметры приложения.

Следующий шаг

Настройка события выдачи маркера маркера пользовательского поставщика утверждений