Авторизация и Microsoft Graph Security API

  • Статья

Данные безопасности, доступные через API безопасности Microsoft Graph, конфиденциальны и защищены как разрешениями, так и ролями Microsoft Entra.

Microsoft Graph Security API поддерживает два типа авторизации:

  • Авторизация на уровне приложения: отсутствует вошедший в систему пользователь (например, сценарий SIEM). Разрешения, предоставленные приложению, определяют авторизацию.

    Примечание.

    Этот вариант также поддерживает сценарии, в которых управление доступом на основе ролей (RBAC) осуществляется приложением.

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

При вызове Microsoft Graph Security API из песочницы Graph:

  • Администратор клиента Microsoft Entra должен явно предоставить согласие на запрошенные разрешения для приложения Graph Explorer.

  • Пользователь должен быть членом роли ограниченного администратора читателя безопасности в Microsoft Entra ID (читатель безопасности или администратор безопасности).

    Примечание.

    Песочница Graph не поддерживает авторизацию на уровне приложения.

При вызове Microsoft Graph Security API из пользовательского или собственного приложения:

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

Управление авторизацией в клиентских приложениях API безопасности

Данные безопасности, предоставляемые посредством Microsoft Graph Security API, являются конфиденциальными и должны защищаться соответствующими механизмами аутентификации и авторизации. В таблице ниже перечислены необходимые действия, чтобы зарегистрировать и создать клиентское приложение, в котором есть доступ к Microsoft Graph Security API.

Кто Действие
Разработчик приложения или владелец Регистрация приложения в качестве корпоративного приложения.
Администратор клиента Предоставление разрешений для приложения.
Администратор клиента Назначение ролей пользователям
Разработчик приложения Вход в качестве пользователя и использование приложения для доступа к Microsoft Graph Security API.

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

Администратор клиента Microsoft Entra должен явно предоставить разрешения приложению. Это должно выполняться для каждого клиента каждый раз, когда разрешения приложения изменяются на портале регистрации приложения.

Например, предположим, что у вас есть приложение, два клиента Microsoft Entra, T1 и T2, а также два разрешения P1 и P2. Ниже приведен процесс авторизация.

  • Приложение регистрируется для затребования разрешения P1.

  • Когда пользователи в клиенте T1 получают маркер Microsoft Entra для этого приложения, маркер не содержит никаких разрешений.

  • Администратор клиента T1 Microsoft Entra явно предоставляет разрешения приложению. Когда пользователи в клиенте T1 получают маркер Microsoft Entra для приложения, он будет содержать разрешение P1.

  • Когда пользователи в клиенте T2 получают маркер Microsoft Entra для приложения, маркер не содержит разрешений, так как администратор клиента T2 еще не предоставил разрешения приложению. Разрешение должно быть предоставлено для каждого клиента и для каждого приложения.

  • Регистрация приложения изменяется и теперь требует разрешений P1 и P2.

  • Когда пользователи в клиенте T1 получают маркер Microsoft Entra для приложения, он содержит только разрешение P1. Разрешения, предоставленные приложению, фиксируются в виде снимков полученного. Они не изменяются автоматически после изменения регистрации приложения (разрешения).

  • Администратор клиента T2 предоставляет разрешения P1 и P2 для приложения. Теперь, когда пользователи в клиенте T2 получают маркер Microsoft Entra для приложения, маркер будет содержать разрешения P1 и P2.

    Примечание.

    Маркеры Microsoft Entra для приложения в клиенте T1 и приложения в клиенте T2 содержат разные разрешения, так как каждый администратор клиента предоставил приложению разные разрешения.

  • Чтобы приложение вновь заработало в клиенте T1, администратор клиента T1 должен явным образом предоставить разрешения P1 и P2 для приложения.

Регистрация приложения с помощью конечной точки платформы удостоверений Майкрософт

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

  • Имя приложения: строка, используемая в качестве имени приложения.
  • URL-адрес перенаправления: URL-адрес, по которому отправляется ответ проверки подлинности из идентификатора Microsoft Entra. Чтобы начать, можно использовать домашнюю страницу веб-приложения тестового клиента.
  • Требуемые разрешения: разрешения, необходимые для вашего приложения, чтобы вызвать Microsoft Graph.

Чтобы зарегистрировать приложение:

  1. Перейдите на портал регистрации приложений Azure и выполните вход.

    Примечание.

    Вам не нужно быть администратором клиента. Вы будете перенаправлены в список Мои приложения.

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

  3. На странице регистрации нового приложения введите значение в поле Имя и выберите поддерживаемые типы учетных записей. В поле URI перенаправления введите URL-адрес перенаправления.

  4. Нажмите кнопку Зарегистрировать, чтобы создать приложение и посмотреть его обзорную страницу. *

  5. Перейдите на страницу Разрешения API приложения.

  6. Нажмите кнопку Добавить разрешение и выберите вариант Microsoft Graph во всплывающем окне. Выберите Делегированные разрешения. Чтобы найти и выбрать требующиеся разрешения, используйте поле поиска. Список разрешений см. в статье Разрешения безопасности.

    Примечание.

    Microsoft Graph Security API требуется область *.Read.All для запросов GET и область *.ReadWrite.All для запросов PATCH/POST/DELETE.

    Разрешение Объект Поддерживаемые запросы
    SecurityActions.Read.All • securityActions (предварительная версия) GET
    SecurityActions.ReadWrite.All • securityActions (предварительная версия) GET, POST
    SecurityEvents.Read.All • оповещения
    • secureScores
    • secureScoreControlProfiles    		 GET
    SecurityEvents.ReadWrite.All • оповещения
    • secureScores
    • secureScoreControlProfiles    		 GET, POST, PATCH
    ThreatIndicators.ReadWrite.OwnedBy • tiIndicator (предварительная версия) GET, POST, PATCH, DELETE

  7. Нажмите кнопку Добавить разрешения.

Сохраните следующие сведения:

  • Идентификатор приложения (клиента)
  • URL-адрес перенаправления
  • Список необходимых разрешений

*Для расширенной защиты от угроз в Защитнике Windows (WDATP) требуются дополнительные роли пользователей , чем требуется API безопасности Microsoft Graph. таким образом, только пользователи с ролями WDATP и API безопасности Microsoft Graph могут иметь доступ к данным WDATP. Это ограничение не распространяется на проверку подлинности только для приложений, поэтому рекомендуется использовать маркер проверки подлинности только для приложений.

Дополнительные сведения см. в статье Регистрация приложения с помощью платформы удостоверений Майкрософт.

Предоставление разрешений для приложения

Регистрация приложения лишь определяет, какое разрешение требуется для приложение. Она не предоставляет эти разрешения для приложения. Администратор клиента Microsoft Entra должен явно предоставить эти разрешения, выполнив вызов к конечной точке согласия администратора. Дополнительные сведения см. в статье Использование конечной точки разрешения администратора.

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

  • Идентификатор приложения: идентификатор приложения из портала регистрации приложений Azure.
  • URL-адрес перенаправления: строка, настроенная на портале регистрации приложений Azure для отклика проверки подлинности.

Чтобы предоставить разрешения:

  • В текстовом редакторе создайте следующую строку URL-адреса:

    https://login.microsoftonline.com/common/adminconsent?client_id=<Application Id>&state=12345&redirect_uri=<Redirect URL>

  • В веб-браузере перейдите на этот URL-адрес и войдите в качестве администратора клиента. Диалоговое окно отображает список разрешений, требуемых для приложения, как указано на портале регистрации приложений. Нажмите кнопку OK, чтобы предоставить эти разрешения для приложения.

    Примечание.

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

Назначение ролей Microsoft Entra пользователям

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

Примечание.

Вы должны быть администратором клиента, чтобы выполнить это действие.

Назначение роли пользователю:

  1. Войдите в центр администрирования Microsoft Entra .
  2. Разверните меню >Удостоверение, разверните пункт Пользователи>выберите Все пользователи.
  3. Выберите пользователя.
  4. Выберите Назначенные роли, затем Добавление назначения.
  5. Установите флажок Читатель сведений о безопасности и нажмите кнопку Добавить.

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

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

  • Идентификатор приложения: идентификатор приложения из портала регистрации приложений.
  • URL-адрес перенаправления: URL-адрес, по которому отправляется ответ проверки подлинности из идентификатора Microsoft Entra. Чтобы начать, можно использовать https://localhost или домашнюю страницу веб-приложения тестового клиента.
  • Ключ приложения (необязательно): ключ приложения. Это применимо, если вы разрабатываете приложение, которое будет использовать код проверки подлинности только для приложения (т. е. не будет поддерживать проверку подлинности, делегированную пользователю).

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

Тип приложения Библиотека проверки подлинности
Классические приложения — iOS MSAL.framework: предварительная версия библиотеки проверки подлинности (Майкрософт) для iOS
Классические приложения — Android Библиотека проверки подлинности Майкрософт (MSAL)
Классические приложения — .Net Библиотека проверки подлинности Майкрософт (MSAL)
Веб-приложения — JavaScript SPA Библиотека проверки подлинности Майкрософт для предварительной версии JavaScript
Веб-приложения — веб-сервер .NET OpenIdConnection, Cookies, SystemWeb
Веб-приложения — веб-приложение NodeJS

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

  1. Получите код из Идентификатора Microsoft Entra. Запрос на вызов содержит параметр для идентификатора приложения, URL-адрес перенаправления и необходимые разрешения.
  2. Используйте код, чтобы получить маркер доступа.

Если вы используете библиотеку OpenId Connect, см. статью Проверка подлинности с помощью Microsoft Entra ID и OpenID Connect и вызов .app.UseOpenIdConnectAuthentication()

Примечание.

Если вы запрашиваете маркеры проверки подлинности, делегированной пользователю, параметр для библиотеки — Требуемые области. Для этого параметра используйте User.Read, вместо того, что требует зарегистрированное приложение. Параметр требуемые области НЕ влияет на разрешения, содержащиеся в возвращаемых маркерах проверки подлинности. Они определяются разрешениями, которые предоставил администратор клиента для приложения.

Например, если вы используете библиотеку MSAL .NET, выполните следующий вызов:

var accessToken = (await client.AcquireTokenAsync(scopes)).AccessToken;

Примечание.

В этом примере следует использовать наименее привилегированное разрешение, например User.Read. Тем не менее, возвращаемый маркер доступа может содержать разрешения, которые были предоставлены администратором клиента для текущего пользователя клиента, например User.Read.All или User.ReadWrite.All.

Маркер (строка) возвращается идентификатором Microsoft Entra, который содержит сведения о проверке подлинности и разрешения, необходимые приложению. Назначьте этот маркер для заголовка HTTP в качестве маркера носителя, как показано в примере ниже.

request.Headers.Authorization = new AuthenticationHeaderValue("bearer", accessToken);

Microsoft Graph проверяет сведения, содержащиеся в этом маркере и предоставляет или отклоняет доступ.

Чтобы просмотреть утверждения, содержащиеся в возвращаемом маркере, используйте библиотеку NuGet System.IdentityModel.Tokens.Jwt.

JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler();
var securityToken = tokenHandler.ReadToken(accessToken) as JwtSecurityToken;

Ответ от Microsoft Graph содержит заголовок под названием идентификатор запроса клиента, который является идентификатором GUID. Если доступ отклонен, укажите GUID при обращении за помощью в сообщество Microsoft Tech, чтобы мы смогли помочь разобраться в причинах этой ошибки проверки подлинности.