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

Добро пожаловать! Возможно, это не та страница, которую вы ожидали. Пока мы работаем над исправлением, воспользуйтесь этой ссылкой, чтобы перейти к нужной статье:

Краткое руководство. Вызов защищенного веб-API ASP.NET

Приносим извинения за неудобства и благодарим за терпение! Мы работаем над устранением этой проблемы.

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

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

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

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
• Visual Studio 2017 или 2019. Скачайте Visual Studio бесплатно.

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

Пример можно получить одним из двух способов:

• Клонировать его из оболочки или командной строки:

  git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git
  

• Скачать его в виде ZIP-файла.

Совет

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

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

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

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

2. Перейдите к приложениям> удостоверений>Регистрация приложений.

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

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

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

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

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

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, а затем откройте файл Web.config в корневом каталоге проекта TodoListService.

2. Замените значение параметра ida:ClientId на значение идентификатора клиента (идентификатор приложения) из приложения, которое вы зарегистрировали на портале Регистрация приложений.

Добавление новой области в файл 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. Перейдите на портал Регистрация приложений платформы удостоверений Майкрософт для разработчиков.

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

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

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

   Примечание.

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

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

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

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

5. Выберите Разрешения 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.

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

Вариант 1. Ограничение доступа к одной организации (одному клиенту)

Вы можете ограничить доступ к приложению учетным записям пользователей, которые находятся в одном клиенте Microsoft Entra, включая гостевые учетные записи этого клиента. Это распространенный сценарий для бизнес-приложений.

1. Откройте файл App_Start\Startup.Auth, а затем измените значение конечной точки метаданных, передаваемое в OpenIdConnectSecurityTokenProvider, на https://login.microsoftonline.com/{Tenant ID}/v2.0/.well-known/openid-configuration. Можно также использовать имя арендатора, например contoso.onmicrosoft.com.
2. В том же файле задайте для свойства ValidIssuer в TokenValidationParameters значение https://sts.windows.net/{Tenant ID}/, а для аргумента ValidateIssuer укажите значение true.

Вариант 2. Использование пользовательского метода для проверки издателей

Вы можете реализовать настраиваемый метод для проверки издателей с помощью IssuerValidator параметра. Дополнительные сведения об этом параметре, представлены в описании класса TokenValidationParameters.

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

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

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

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

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