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

  • Статья

Данные безопасности, доступные через Microsoft Graph Security API, являются конфиденциальными и защищаются как разрешениями, так и ролями Azure Active Directory (Azure AD).

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

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

    Примечание.

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

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

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

  • Администратор клиента Azure AD должен явным образом предоставить согласие на требуемые разрешения для приложения песочницы Graph.

  • Пользователь должен быть участником с ограниченной административной ролью читателя безопасности в Azure AD (читателем безопасности или администратором безопасности).

    Примечание.

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

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

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

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

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

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

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

Администратор клиента Azure AD ДОЛЖЕН явным образом предоставить разрешения для приложения. Это должно выполняться для каждого клиента каждый раз, когда разрешения приложения изменяются на портале регистрации приложения.

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

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

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

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

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

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

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

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

    Примечание.

    Маркеры Azure AD для приложения в клиенте T1 и приложения в клиенте T2 содержат разные разрешения, потому что каждый администратор клиента предоставил разные разрешения для приложения.

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

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

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

  • Имя приложения: строка, используемая в качестве имени приложения.
  • URL-адрес перенаправления: URL-адрес, куда направляется ответ по проверке подлинности из Azure AD. Чтобы начать, можно использовать домашнюю страницу веб-приложения тестового клиента.
  • Требуемые разрешения: разрешения, необходимые для вашего приложения, чтобы вызвать 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 Advanced Threat Protection (WDATP) требует дополнительных ролей пользователей, чем требуется API безопасности Microsoft Graph. Таким образом, доступ к данным WDATP и Microsoft Graph могут иметь только пользователи ролей WDATP и Microsoft Graph API безопасности. Это ограничение не распространяется на проверку подлинности только для приложений, поэтому рекомендуется использовать маркер проверки подлинности только для приложений.

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

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

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

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

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

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

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

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

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

    Примечание.

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

Назначение ролей Azure AD для пользователей

После получения приложением разрешений все обладатели доступа к приложению (т. е. участники клиента Azure AD) получат предоставленные разрешения. Чтобы обеспечить дополнительную защиту конфиденциальных данных безопасности, Microsoft Graph Security API также требует, чтобы пользователям была назначена роль читателя безопасности Azure AD. Подробности см. в статьях Разрешения роли администратора в Azure Active Directory и Назначение ролей администратора и других ролей пользователям с помощью Azure Active Directory.

Примечание.

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

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

  1. Войдите в портал Azure (https://portal.azure.com).
  2. Щелкните значок в левом верхнем углу, чтобы развернуть меню портала Azure. Выберите Azure Active Directory>Пользователи.
  3. Щелкните имя пользователя.
  4. Выберите Назначенные роли, затем Добавление назначения.
  5. Установите флажок Читатель сведений о безопасности и нажмите кнопку Добавить.

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

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

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

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

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

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

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

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

Примечание.

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

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

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

Примечание.

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

Azure AD возвращает маркер (строку), который содержит сведения проверки подлинности и разрешения, требуемые для приложения. Назначьте этот маркер для заголовка 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, чтобы мы смогли помочь разобраться в причинах этой ошибки проверки подлинности.