Триггер событий проверки подлинности для клиентской библиотеки Функции Azure для Node

Статья
04/05/2023

Триггер события проверки подлинности для Функции Azure обрабатывает всю серверную обработку (например, проверку схемы токена или json) для входящих HTTP-запросов для событий проверки подлинности. И предоставляет разработчику строго типизированную объектную модель с версиями для работы. Это означает, что разработчик не должен иметь никаких предварительных знаний о полезных данных JSON запроса и ответа.

Эта платформа проекта предоставляет следующие возможности:

Проверка маркера для защиты вызова API
Объектная модель, ввод и intellisense интегрированной среды разработки
Входящая и исходящая проверка схем запросов и ответов API
Управление версиями
Не требуется стандартный код.

Начало работы

Установка пакета npm

npm install @azure/functions-authentication-events

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

Средства функций Azure
Средства Azure Function Core
При использовании Visual Studio Code следующие расширения:
- ms-azuretools.vscode-azurefunctions
- ms-dotnettools.csharp

Проверка подлинности клиента

Когда служба событий проверки подлинности Azure AD вызывает пользовательское расширение, она отправляет заголовок Authorization с Bearer {token}. Этот маркер будет представлять собой проверку подлинности между службами , в которой:

Ресурс, также известный как аудитория, — это приложение, которое вы регистрируете для представления API. Это представлено утверждением aud в маркере.
Клиент — это приложение Майкрософт, представляющее службу событий проверки подлинности Azure AD. Он имеет appId значение 99045fe1-7639-4a75-9d4a-577b6ca3810f. Это представляется следующим образом:
- Утверждение azp в маркере, если свойству приложения accessTokenAcceptedVersion присвоено значение 2.
- Утверждение appid в маркере, если свойству приложения accessTokenAcceptedVersion ресурсов присвоено значение 1 или null.

Существует три подхода к работе с маркером. Поведение можно настроить с помощью параметров приложения , как показано ниже, или с помощью файла local.settings.json в локальных средах.

Проверка маркеров с помощью интеграции проверки подлинности Функции Azure Azure AD

При запуске функции в рабочей среде настоятельно рекомендуется использовать интеграцию проверки подлинности Функции Azure Azure AD для проверки входящих маркеров.

Перейдите на вкладку "Проверка подлинности" в приложении-функции.
Щелкните "Добавить поставщика удостоверений".
Выберите "Майкрософт" в качестве поставщика удостоверений.
Выберите "Указать сведения о существующей регистрации приложения".
Application ID Введите приложение, представляющее API в Azure AD

Издатель и разрешенная аудитория зависят accessTokenAcceptedVersion от свойства приложения (можно найти в манифесте приложения).

accessTokenAcceptedVersion Если свойство имеет значение 2: 6. Задайте Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (appId')

Если свойству accessTokenAcceptedVersion1 присвоено значение или null: 6. Задайте Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asидентификаторUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}, если используется пользовательское доменное имя.

По умолчанию триггер события проверки подлинности проверяет, настроена ли интеграция проверки подлинности функции Azure, и проверка, что для клиента в маркере задано значение 99045fe1-7639-4a75-9d4a-577b6ca3810f (с помощью утверждений azp или appid в маркере).

Если вы хотите протестировать API на другом клиенте, который не Azure AD службе событий проверки подлинности, например с помощью Postman, можно настроить дополнительный параметр приложения:

AuthenticationEvents__CustomCallerAppId — guid нужного клиента. Если не указано, 99045fe1-7639-4a75-9d4a-577b6ca3810f предполагается.

Проверка маркера с помощью триггера

В локальных средах или средах, которые не размещены в службе функций Azure, триггер может выполнить проверку маркера. Задайте следующие параметры приложения:

AuthenticationEvents__TenantId — идентификатор клиента.
AuthenticationEvents__AudienceAppId — то же значение, что и "Разрешенная аудитория" в варианте 1.
AuthenticationEvents__CustomCallerAppId (необязательно) — guid нужного клиента. Если не указано, 99045fe1-7639-4a75-9d4a-577b6ca3810f предполагается.

Пример local.settings.json файла:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__TenantId": "8615397b-****-****-****-********06c8",
    "AuthenticationEvents__AudienceAppId": "api://46f98993-****-****-****-********0038",
    "AuthenticationEvents__CustomCallerAppId": "46f98993-****-****-****-********0038"
  }
}

Без проверки маркера

Если вы хотите не проверять подлинность маркера во время локальной разработки, задайте следующий параметр приложения:

AuthenticationEvents__BypassTokenValidation — значение true будет делать триггер не проверка для проверки маркера.

Краткое руководство

Visual Studio Code
- Запустите Visual Studio Code.
- Выполнение команды func init . --worker-runtime node терминала с помощью палитры команд
- Выполнение команды func new терминала с помощью палитры команд
- Следуйте инструкциям по созданию проекта.
- Выполнение команды npm install @azure/functions-authentication-events терминала с помощью палитры команд
- Выполнение команды npm install терминала с помощью палитры команд
- Выполнение команды npm run-script build терминала с помощью палитры команд
Для целей разработки очередь проверки маркера для тестирования:
Добавьте ключ приложения AuthenticationEvents__BypassTokenValidation в раздел "Значения" в файле local.settings.json и задайте для него значение true. Если в локальной среде нет файла local.settings.json, создайте его в корне приложения-функции.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}

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

Основные понятия

Основные понятия пакета SDK для Azure .NET можно найти здесь.

Документация

Одна функция была опубликована, есть некоторые хорошие сведения о ведении журнала и метрики, которые можно найти здесь
Документацию по API см. в разделе (Link TBD)
После перехода на предварительную версию мы не изменим критических изменений и будем так же просто, как удалить источник Nuget, указывающий на закрытую предварительную версию.

Примеры

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

Откройте проект, созданный на предыдущем шаге. (Краткое руководство)
Запустите приложение. func host start
После запуска приложения разработчика функций Azure скопируйте URL-адрес прослушивания, который отображается при запуске приложения.
Примечание. Все функции проверки подлинности перечислены. В случае, если у нас есть один прослушиватель функций с именем "OnTokenIssuanceStart".
Конечная точка функции будет сочетанием URL-адреса прослушивания и функции, например: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& function=OnTokenIssuanceStart"
Опубликуйте следующие полезные данные, используя что-то вроде Postman или Fiddler.
Инструкции по использованию Postman можно найти (Link TBD)

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/00000001-0000-0ff1-ce00-000000000000/applications/ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "00000001-0000-0ff1-ce00-000000000000",
        "authenticationEventListenerId": "f2390d57-9664-4dde-b625-f0115925e1e2",
        "customAuthenticationExtensionId": "9cc1c1ed-5f04-4fdf-85c0-94a7c6ea819c",
        "authenticationContext": {
            "correlationId": "f4bd1870-b774-4fa5-ba78-e08ac6be14c0",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "resourceServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "user": {
                "companyName": "Evo Sts Test",
                "country": "",
                "id": "69d24544-c420-4721-a4bf-106f2378d9f6",
                "mail": "testadmin@evostsoneboxtest.com",
                "onPremisesSamAccountName": "testadmin",
                "onPremisesSecurityIdentifier": "testadmin",
                "preferredDataLocation": "",
                "userPrincipalName": "testadmin@evostsoneboxtest.com"
            }
        }
    }
}

Вы должны увидеть следующий ответ:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

Устранение неполадок

Visual Studio Code
- Если вы работаете в Visual Studio Code, вы получите сообщение об ошибке, если локальный эмулятор службы хранилища Azure недоступен, вы можете запустить эмулятор вручную. (Примечание. Эмулятор службы хранилища Azure теперь не рекомендуется использовать и рекомендуется заменить Azurite.
- При использовании Visual Studio Code на Mac используйте Azurite
- Если вы видите следующую ошибку в Windows (это ошибка) при попытке запустить созданный проецируемый объект.
- Эту проблему можно устранить, выполнив эту команду в PowerShellSet-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine. Дополнительные сведения об этом можно найти здесь и здесь.

Дальнейшие действия

Дополнительные сведения о пакете AZURE SDK см. на этом веб-сайте.

Публикация

Следуйте инструкциям здесь, чтобы создать и опубликовать приложение Azure. </azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure>
Чтобы определить опубликованную конечную точку публикации, объедините созданную конечную точку функции Azure, направляйте маршрут к прослушивателю и коду прослушивателя. Код прослушивания можно найти, перейдя в приложение-функцию Azure, выбрав "Ключи приложения" и скопировав значение AuthenticationEvents_extension.
Например: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& function=OnTokenIssuanceStart"
Убедитесь, что в рабочей среде заданы правильные параметры приложения для проверки подлинности по маркеру.
Еще раз вы можете протестировать опубликованную функцию, опубликовав приведенные выше полезные данные в новой конечной точке.

Участие

Дополнительные сведения об участии в этом репозитории см. в руководстве по участию.

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

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

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.

Поделиться через