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

• Visual Studio 2022. Скачайте Visual Studio бесплатно.

• Visual Studio Code

1. В разделе "Управление" выберите "Открыть 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. Для состояния сохраните значение "Включено".

2. Выберите «Добавить область».

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

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

2. В разделе "Управление" выберите "Предоставить API".

3. В верхней части страницы рядом с URI идентификатора приложения выберите ссылку "Добавить ", чтобы создать универсальный код ресурса (URI), уникальный для этого приложения.

4. Примите предлагаемый URI идентификатора приложения, например api://{clientId}, и нажмите кнопку "Сохранить". Когда веб-приложение запрашивает маркер доступа для веб-API, он добавляет URI в качестве префикса для каждой области, определяемой для API.

5. В разделе "Области", определенные этим API, выберите "Добавить область".

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

   Развернуть таблицу

   Недвижимость	Ценность
   Имя области	ToDoList.Read
   Кто может согласиться	Только администраторы
   Имя для отображения согласия администратора	Прочитать пользовательский список дел с помощью 'TodoListApi'
   Описание согласия администратора	Разрешить приложению читать список задач пользователя с помощью API TodoListApi.
   Государство	Включен

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

   Развернуть таблицу

   Недвижимость	Ценность
   Имя области	ToDoList.ReadWrite
   Кто может согласиться	Только администраторы
   Имя для отображения согласия администратора	Чтение и запись списка задач пользователей с использованием 'ToDoListApi'
   Описание согласия администратора	Разрешить приложению читать и записывать список ToDo пользователя с помощью toDoListApi
   Государство	Включен

Узнайте больше о принципе минимальных привилегий при публикации разрешений для веб-API.

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

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

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

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

   Развернуть таблицу

   Недвижимость	Ценность
   Показать имя	ToDoList.Read.All
   Допустимые типы членов	Приложения
   Ценность	ToDoList.Read.All
   Описание	Разрешить приложению считывать список задач каждого пользователя с помощью TodoListApi.
   Вы хотите активировать эту роль приложения?	Оставьте это отмеченным

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

   Развернуть таблицу

   Недвижимость	Ценность
   Показать имя	ToDoList.ReadWrite.All
   Допустимые типы членов	Приложения
   Ценность	ToDoList.ReadWrite.All
   Описание	Разрешить приложению считывать и записывать список ToDo каждого пользователя с помощью ToDoListApi
   Вы хотите активировать эту роль приложения?	Оставьте это отмеченным

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

• Скачайте его как ZIP-файл.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   Примечание

   В проекте TodoListClient, в файле app.config, значение 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 параметр.

1. В вашей интегрированной среде разработки откройте папку проекта ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI, содержащую пример.

2. Откройте файл appsettings.json, содержащий следующий фрагмент кода:

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   Найдите следующие значения:

   • ClientId — идентификатор приложения, который также называется клиентом. Замените value текст в кавычках идентификатором приложения (клиента), записанным ранее на странице обзора зарегистрированного приложения.
   • TenantId — идентификатор клиента, в котором зарегистрировано приложение. Замените value текст в кавычках значением идентификатора каталога (клиента), записанным ранее на странице обзора зарегистрированного приложения.
   • Instance — Указывает каталог, из которого библиотека проверки подлинности Майкрософт (MSAL) может запрашивать маркеры. Замените Enter_the_Authority_URL_Here любой из следующих значений в зависимости от вашего сценария:
     • Для арендаторов, являющихся рабочей силой, используйте https://login.microsoftonline.com/ в качестве примера.
     • Для внешних арендаторов добавьте URL-адрес уполномоченного органа в виде https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/

Запустите оба проекта. Для пользователей 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://<Application ID>/access_as_user веб-API.
5. Выберите "Добавить приложение".

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

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

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

1. Выполните следующую команду из корневого каталога проекта веб-API, чтобы запустить приложение:

   dotnet run
   

2. Если все работает правильно, терминал отображает выходные данные, аналогичные следующим:

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   Запишите номер порта в URL-адресе https://localhost:{port} .

3. Чтобы убедиться, что конечная точка защищена, обновите базовый URL-адрес в следующей команде cURL, чтобы она соответствовала полученной на предыдущем шаге, а затем выполните команду:

   curl -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   Ожидаемый ответ — 401 Несанкционированный.