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

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

  • Статья

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

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

Необходимые условия

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

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

Совет

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

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

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

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

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

  3. Перейдите к Идентификации>Приложениям>Регистрация приложений и выберите "Новая регистрация".

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

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

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

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

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

    1. Для имени областивведите access_as_user.
    2. Чтобы кто может предоставить согласие, убедитесь, что выбран параметр администраторов и пользователей.
    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. Выберите Добавить область.

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

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

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

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

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

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

  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 как минимум в роли администратора облачных приложений.

  2. Перейдите к Идентификация>Приложения>Регистрация приложений и выберите Новая регистрация.

  3. Выберите Новая регистрация.

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

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

    Заметка

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

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

  5. На странице обзора приложения выберите Аутентификация, а затем выполните эти шаги, чтобы добавить платформу:

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

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

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

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

Настройте проект 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 и управлять списком To-Do, при входе также запрашивается токен доступа для области 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