Вызов API в примере приложения управляющей программы .NET

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

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

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

• Visual Studio Code или любой другой редактор кода.
• .NET 7.0 или более поздней версии.

• Внешний клиент. Чтобы создать его, выберите один из следующих методов:
  • (Рекомендуется) Используйте расширение Внешняя идентификация Microsoft Entra для настройки внешнего клиента непосредственно в Visual Studio Code.
  • Создайте внешний клиент в Центре администрирования Microsoft Entra.

Регистрация приложения управляющей программы и веб-API

На этом шаге вы создадите управляющая программа и регистрации приложений веб-API, а также укажите области веб-API.

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

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

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

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

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

5. Откроется страница "Регистрация приложения", где необходимо ввести сведения о регистрации приложения:

   1. В разделе "Имя" введите понятное имя приложения, которое будет отображаться пользователям приложения, например ciam-ToDoList-api.

   2. В разделе Поддерживаемые типы учетных записей выберите Учетные записи только в этом каталоге организации.

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

7. Панель обзора приложения отображается при завершении регистрации. Запишите идентификатор каталога (клиента) и идентификатор приложения (клиента), которые будут использоваться в исходном коде приложения.

Настройка ролей приложения

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

1. На странице Регистрация приложений выберите созданное приложение (например, ciam-ToDoList-api), чтобы открыть страницу обзора.

2. В разделе "Управление" выберите роли приложения.

3. Выберите " Создать роль приложения", а затем введите следующие значения, а затем нажмите кнопку "Применить ", чтобы сохранить изменения:

   Свойство	Значение
   Отображаемое имя	ToDoList.Read.All
   Разрешенные типы элементов	Приложения
   Значение	ToDoList.Read.All
   Description	Разрешить приложению считывать список toDo каждого пользователя с помощью todopi TodoListApi.

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

   Свойство	Значение
   Отображаемое имя	ToDoList.ReadWrite.All
   Разрешенные типы элементов	Приложения
   Значение	ToDoList.ReadWrite.All
   Description	Разрешить приложению считывать и записывать список toDopi каждого пользователя с помощью toDoListApi

Настройка необязательных утверждений

Вы можете бездействующее утверждение, чтобы помочь веб-API определить, является ли токен маркером приложения или приложением и маркером пользователя. Хотя вы можете использовать сочетание утверждений scp и ролей для той же цели, используя утверждение idtyp, проще всего определить маркер приложения и приложение + маркер пользователя. Например, значение этого утверждения — это приложение , когда маркер является маркером только для приложений.

Регистрация приложения управляющей программы

Чтобы приложение входить в систему с помощью Microsoft Entra, Внешняя идентификация Microsoft Entra должны быть осведомлены о создаваемом приложении. Регистрация приложения устанавливает отношение доверия между приложением и Microsoft Entra. При регистрации приложения внешний идентификатор создает уникальный идентификатор, известный как идентификатор приложения (клиента), значение, используемое для идентификации приложения при создании запросов проверки подлинности.

Ниже показано, как зарегистрировать приложение в Центре администрирования Microsoft Entra:

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

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

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

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

5. На отображаемой странице регистрации приложения;

   1. Введите понятное имя приложения, отображаемое пользователям приложения, например ciam-client-app.
   2. В разделе Поддерживаемые типы учетных записей выберите Учетные записи только в этом каталоге организации.

6. Выберите Зарегистрировать.

7. Панель обзора приложения отображается при успешной регистрации. Запишите идентификатор приложения (клиента), который будет использоваться в исходном коде приложения.

Создание секрета клиента

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

1. На странице Регистрация приложений выберите созданное приложение (например, ciam-client-app), чтобы открыть страницу обзора.
2. В разделе Управление выберите Сертификаты и секреты.
3. Щелкните Создать секрет клиента.
4. В поле "Описание" введите описание секрета клиента (например, секрет клиента приложения ciam).
5. В разделе "Срок действия" выберите срок действия, для которого секрет действителен (для правил безопасности организации), а затем нажмите кнопку "Добавить".
6. Запишите значение секрета в поле Значение. Это значение будет использовано позже для конфигурации. Значение секрета не будет отображаться снова и не извлекается с помощью каких-либо средств после перехода от сертификатов и секретов. Обязательно запишите его.

Предоставление разрешений API приложению управляющей программы

1. На странице Регистрация приложений выберите созданное приложение, например ciam-client-app.

2. В разделе Управление выберите Разрешения API.

3. В разделе Настроенные разрешения выберите Добавить разрешение.

4. Щелкните вкладку API, используемые моей организацией.

5. В списке API выберите API, например ciam-ToDoList-api.

6. Выберите параметр "Разрешения приложения". Мы выбираем этот параметр в качестве самого приложения, но не от имени пользователя.

7. В списке разрешений выберите TodoList.Read.All, ToDoList.ReadWrite.All (при необходимости используйте поле поиска).

8. Нажмите кнопку Add permissions (Добавить разрешения).

9. На этом этапе вы правильно назначили разрешения. Однако, так как приложение управляющей программы не позволяет пользователям взаимодействовать с ним, сами пользователи не могут согласиться на эти разрешения. Чтобы устранить эту проблему, администратор должен согласиться с этими разрешениями от имени всех пользователей в клиенте:

   1. Выберите "Предоставить согласие администратора" для <имени> клиента, а затем нажмите кнопку "Да".
   2. Выберите "Обновить", а затем убедитесь, что <имя> клиента предоставлено в разделе "Состояние" для обоих разрешений.

Клонирование или скачивание примера приложения управляющей программы и веб-API

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

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

  git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git
  

• Скачайте файл .zip. Извлеките его в путь к файлу, где длина имени меньше 260 символов.

Настройка примера приложения управляющей программы и API

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

1. В редакторе кода откройте ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListClient/appsettings.json файл.

2. Найдите заполнитель:

   • Enter_the_Application_Id_Here и замените его идентификатором приложения (клиента) управляющей программы, зарегистрированного ранее.
   • Enter_the_Tenant_Subdomain_Here и замените его поддоменом каталога (клиента). Например, если основной домен клиента — это contoso.onmicrosoft.com, используйте contoso. Если у вас нет имени клиента, узнайте, как прочитать сведения о клиенте.
   • Enter_the_Client_Secret_Here и замените его значением секрета приложения управляющей программы, скопированным ранее.
   • Enter_the_Web_Api_Application_Id_Here и замените его идентификатором приложения (клиента) веб-API, скопированного ранее.

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

1. В редакторе кода откройте ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI/appsettings.json файл.

2. Найдите заполнитель:

   • Enter_the_Application_Id_Here и замените его идентификатором приложения (клиента) скопированного веб-API.
   • Enter_the_Tenant_Id_Here и замените его идентификатором каталога (клиента), скопированным ранее.
   • Enter_the_Tenant_Subdomain_Here и замените его поддоменом каталога (клиента). Например, если основной домен клиента — это contoso.onmicrosoft.com, используйте contoso. Если у вас нет имени клиента, узнайте, как прочитать сведения о клиенте.

Запуск и тестирование примера приложения управляющей программы и API

1. Откройте окно консоли, а затем запустите веб-API с помощью следующих команд:

   cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListAPI
   dotnet run
   

2. Запустите клиент управляющей программы с помощью следующих команд:

   cd 2-Authorization\3-call-own-api-dotnet-core-daemon\ToDoListClient
   dotnet run
   

Если приложение управляющей программы и веб-API успешно запущены, в окне консоли должно появиться примерно то же, что и следующий массив JSON:

Posting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
Posting a second to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Bake bread
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Deleting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Butter bread
Editing a to-do...
Retrieving to-do's from server...
To-do data:
ID: 2
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Message: Eat bread
Deleting remaining to-do...
Retrieving to-do's from server...
There are no to-do's in server

Принцип работы

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

На стороне API веб-API должен убедиться, что маркер доступа имеет необходимые разрешения (разрешения приложения). Веб-API отклоняет маркеры доступа, у которых нет необходимых разрешений.

Связанный контент

• Создание этого приложения управляющей программы .NET с нуля с помощью серии учебников с несколькими частью
• Включите сброс пароля.
• Настройка фирменной символики по умолчанию.
• Настройка входа в Google.