Краткое руководство. Вызов веб-API ASP.NET, защищенного с помощью платформы удостоверений Майкрософт

  • Статья

В следующем кратком руководстве используется пример кода, демонстрирующий защиту веб-API ASP.NET путем ограничения доступа к ресурсам только авторизованным учетным записям. Пример поддерживает авторизацию личных учетных записей Майкрософт и учетных записей в любой организации Microsoft Entra.

В статье также используется приложение Windows Presentation Foundation (WPF) для демонстрации того, как запросить маркер доступа для доступа к веб-API.

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

Клонирование или скачивание примера

Пример кода можно получить двумя способами:

Совет

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

Регистрация веб-API (TodoListService)

Совет

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

Зарегистрируйте веб-API в разделе Регистрация приложений на портале Azure.

  1. Войдите в Центр администрирования Microsoft Entra как минимум облачные приложения Администратор istrator.

  2. Если у вас есть доступ к нескольким клиентам, используйте значок Параметры в верхнем меню, чтобы переключиться на клиент, в котором вы хотите зарегистрировать приложение из меню каталогов и подписок.

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

  4. Введите имя приложения, например AppModelv2-NativeClient-DotNet-TodoListService. Пользователи приложения могут видеть это имя. Вы можете изменить его позже.

  5. Для параметра Поддерживаемые типы учетных записей выберите Учетные записи в любом каталоге организации.

  6. Выберите Зарегистрировать, чтобы создать приложение.

  7. На странице приложения Обзор найдите идентификатор приложения (клиента) и запишите его, чтобы использовать позже. Вам потребуется настроить файл конфигурации Visual Studio для этого проекта (то есть ClientId в файле TodoListService\appsettings.json ).

  8. В разделе Управление выберите Предоставление API>Добавить группу. Примите предложенный код URI идентификатора приложения (api://{clientId}), выбрав Сохранить и продолжить, а затем введите следующие сведения:

    1. В поле Имя области введите access_as_user.
    2. Убедитесь, что для параметра Кто может давать согласие выбран вариант Admins and users (Администраторы и пользователи).
    3. В поле Отображаемое имя согласия администратора введите Access TodoListService as a user.
    4. В поле Описание согласия администратора введите Accesses the TodoListService web API as a user.
    5. В поле Отображаемое имя согласия пользователя введите Access TodoListService as a user.
    6. В поле Описание согласия пользователя введите Accesses the TodoListService web API as a user.
    7. Для параметра Состояние оставьте значение Включено.

  9. Выберите Добавить область.

Настройка проекта службы

Настройте проект службы в соответствии с зарегистрированным веб-API.

  1. Откройте решение в Visual Studio и откройте файл appsettings.json в корне проекта TodoListService.

  2. Замените значение значения Enter_the_Application_Id_here идентификатора клиента (идентификатор приложения) из приложения, зарегистрированного на портале Регистрация приложений, как в свойствах, так и на ClientID порталеAudience.

Добавление новой области в файл app.config

Чтобы добавить новую область в файл app.config проекта TodoListClient, выполните приведенные ниже действия.

  1. В корневой папке проекта TodoListClient откройте файл app.config.

  2. Вставьте идентификатор приложения из приложения, которое вы зарегистрировали для проекта TodoListService, в параметр TodoListServiceScope, заменив строку {Enter the Application ID of your TodoListService from the app registration portal}.

Примечание.

Идентификатор приложения должен быть задан в следующем формате: api://{TodoListService-Application-ID}/access_as_user (где {TodoListService-Application-ID} — это GUID, представляющий идентификатор приложения для TodoListService).

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

Зарегистрируйте приложение TodoListClient в разделе Регистрация приложений на портале Azure, а затем настройте код в проекте TodoListClient. Если клиент и сервер считаются одним и тем же приложением, вы можете повторно использовать приложение, зарегистрированное на шаге 2. Если вы хотите, чтобы пользователи могли выполнять вход с помощью личных учетных записей Майкрософт, используйте то же приложение.

Регистрация приложения

Чтобы зарегистрировать приложение TodoListClient, выполните приведенные ниже действия.

  1. Войдите в Центр администрирования Microsoft Entra как минимум облачные приложения Администратор istrator.

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

  3. Выберите Создать регистрацию.

  4. Когда откроется страница Регистрация приложения, введите сведения о регистрации приложения.

    1. В разделе Имя введите понятное имя приложения, которое будет отображаться пользователям приложения (например, NativeClient-DotNet-TodoListClient).
    2. Для параметра Поддерживаемые типы учетных записей выберите Учетные записи в любом каталоге организации.
    3. Выберите Зарегистрировать, чтобы создать приложение.

    Примечание.

    В файле app.config проекта TodoListClient в качестве значения по умолчанию для ida:Tenant задано common. Возможны следующие значения:

    • common. Вы можете войти с помощью рабочей или учебной учетной записи или личной учетной записи Майкрософт (так как на предыдущем шаге вы выбрали параметр Учетные записи в любом каталоге организации).
    • organizations: вы можете войти с помощью рабочей или учебной учетной записи.
    • consumers: вы можете войти только с помощью microsoft личная учетная запись.

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

    1. В разделе Конфигурации платформ нажмите кнопку Добавить платформу.
    2. Для параметра Мобильные и классические приложения выберите значение Мобильные и классические приложения.
    3. Для параметра URI перенаправления установите флажок https://login.microsoftonline.com/common/oauth2/nativeclient.
    4. Выберите Настроить.

  6. Выберите Разрешения API, а затем выполните приведенные ниже действия, чтобы добавить разрешения.

    1. Нажмите кнопку Добавить разрешение.
    2. Выберите вкладку Мои API.
    3. В списке интерфейсов API выберите ppModelv2-NativeClient-DotNet-TodoListService API или имя, введенное для веб-API.
    4. Установите флажок для разрешения access_as_user, если он еще не установлен. При необходимости используйте поле поиска.
    5. Нажмите кнопку Add permissions (Добавить разрешения).

Настройка проекта

Настройте проект TodoListClient, добавив идентификатор приложения в файл app.config.

  1. На портале Регистрация приложений на странице Обзор скопируйте значение идентификатора приложения (клиента).

  2. В корневой папке проекта TodoListClient откройте файл app.config и вставьте значение идентификатора приложения в параметр ida:ClientId.

Запуск проектов

Запустите оба проекта. Для пользователей Visual Studio;

  1. Щелкните правой кнопкой мыши решение Visual Studio проект и выберите пункт Свойства.

  2. В разделе Общие свойства выберите Запускаемый проект, затем Несколько запускаемых проектов.

  3. Для обоих проектов выберите Запуск в качестве действия.

  4. Убедитесь, что служба TodoListService начинается сначала, переместив ее на первую позицию в списке, используя стрелку вверх.

Выполните вход, чтобы запустить проект TodoListClient.

  1. Нажмите F5 для запуска проектов. Откроется страница службы, а также классическое приложение.

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

    Если вы впервые входите в систему, вам может быть предложено дать согласие на использование веб-API TodoListService.

    Для удобства доступа к веб-API TodoListService и работы со списком задач при входе также запрашивается маркер доступа к области access_as_user.

Предварительная авторизация клиентского приложения

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

  1. На портале Регистрация приложений откройте свойства приложения TodoListService.
  2. В разделе Предоставление API в подразделе Авторизованные клиентские приложения выберите Добавить клиентское приложение.
  3. В поле Идентификатор клиента вставьте идентификатор приложения TodoListClient.
  4. В разделе Авторизованные области выберите область для веб-API api://<Application ID>/access_as_user.
  5. Выберите Добавить приложение.

Запуск проекта

  1. Нажмите клавишу F5 для запуска проекта. Откроется приложение TodoListClient.
  2. В правом верхнем углу выберите Войти, а затем выполните вход с помощью личной учетной записи Майкрософт, например live.com или hotmail.com, рабочей или учебной учетной записи.

Необязательно. Ограничение доступа к входу определенным пользователям

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

Чтобы указать, кто может войти в приложение, измените TenantId свойство в файле appsettings.json .

Справка и поддержка

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

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

Дополнительные сведения см. в следующем руководстве по созданию защищенного веб-API ASP.NET Core:

Руководство по защищенному веб-API