Авторизация доступа к API с помощью библиотеки проверки подлинности Майкрософт

  • 5 мин

Теперь вы можете предоставить пользователям компании возможность входа в веб-приложение. Затем вы хотите отобразить такие сведения, как название должности, рабочий адрес электронной почты и т. д. из профиля сотрудника на странице. Вы обнаружите, что API Microsoft Graph предоставляет доступ к данным, связанным с пользователем.

В этом уроке вы узнаете, как MSAL может помочь вам получить авторизованный доступ к службы Майкрософт, например API Microsoft Graph.

Разрешения и области API

Веб-службы, защищенные идентификатором Microsoft Entra, определяют набор разрешений, которые предоставляют доступ к функциям API и данным, предоставляемым службой. Приложение может запрашивать эти разрешения у пользователей и администраторов. Они должны подтвердить такой запрос, прежде чем приложение получит доступ к данным или начнет действовать от имени пользователя. Например, в Microsoft Graph определены разрешения для выполнения таких задач, как:

  • чтение календаря пользователя;
  • запись в календарь пользователя;
  • отправка сообщений в качестве пользователя.

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

Идентификатор Microsoft Entra поддерживает два типа разрешений: делегированные разрешения и разрешения приложения.

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

  • Разрешения приложений используются в приложениях, работающих без авторизованного пользователя (например, приложения, работающие как фоновые службы или управляющие программы). Только администратор может дать согласие на разрешения приложения.

Эти разрешения API можно назначить регистрации приложения из портал Azure.

Области

Идентификатор Microsoft Entra реализует протокол авторизации OAuth 2.0, с помощью которого приложение может получать доступ к ресурсам, размещенным в Интернете от имени пользователя.

В OAuth 2.0 наборы разрешений такого типа называются областями. При выполнении запроса авторизации в идентификатор Microsoft Entra приложение запрашивает необходимые разрешения, указав разрешение в параметре запроса запроса scope . Например, значение области https://graph.microsoft.com/Calendars.Read используется для запроса разрешения на чтение календарей пользователя в Microsoft Graph.

Получение маркеров доступа с помощью MSAL

Маркеры доступа позволяют клиентским приложениям безопасно вызывать веб-API, защищенные идентификатором Microsoft Entra. Получить маркер доступ с использованием библиотеки проверки подлинности Майкрософт (MSAL) можно несколькими способами. Как правило, метод, используемый для получения маркера, зависит от того, является приложение общедоступным клиентским приложением, например классическим или мобильным, или же конфиденциальным клиентским приложением, например веб-приложением, веб-API или управляющей программой.

Для некоторых методов получения маркеров MSAL требуется параметр scopes, который представляет собой список строк, объявляющих нужные разрешения и запрошенные ресурсы.

MSAL кэширует токен после его получения. Для веб-приложений, использующих поток кода авторизации OpenID Connect, рекомендуется следующий шаблон действий в контроллерах:

  • Сначала попытайтесь получить маркер из кэша автоматически, прежде чем применять другие способы. Следующий код представляет собой фрагмент реализации acquireTokenSilently метода в AuthHelper классе.

    final SilentParameters parameters = SilentParameters
                                        .builder(Collections.singleton(Config.SCOPES), context.getAccount())
                                        .build();

final ConfidentialClientApplication client = getConfidentialClientInstance();

client.tokenCache().deserialize(context.getTokenCache());

final IAuthenticationResult result = client.acquireTokenSilently(parameters).get();

  • Если в кэше нет маркера, а запрос автоматического маркера не удается получить, можно получить маркер с помощью потока кода авторизации:

    final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
                                                    .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES))
                                                    .build();

final IAuthenticationResult result = app.acquireToken(authParams).get();

MSAL также может обновлять маркер, когда срок его действия заканчивается (тот же кэш маркеров содержит и маркеры обновления).

Результаты аутентификации

Когда клиент запрашивает маркер доступа, идентификатор Microsoft Entra также возвращает результат проверки подлинности, содержащий метаданные о маркере доступа. Благодаря этим данным приложение может выполнять интеллектуальное кэширование маркеров доступа, не анализируя сам маркер. MSAL AuthenticationResult возвращает следующие сведения:

  • Маркер доступа для веб-API.
  • Маркер идентификации пользователя (JWT).
  • Срок действия токена, то есть дата и время завершения его применимости.
  • Идентификатор клиента содержит сведения о клиенте, в котором был найден пользователь.
  • Области, для которых выдан токен.
  • Уникальный идентификатор пользователя.

Общие сведения о Microsoft Graph

API Microsoft Graph предлагает одну конечную точку, https://graph.microsoft.com, которая предоставляет доступ к полным и понятным данным и аналитическим сведениям в облаке Майкрософт. Вы можете использовать REST API или пакеты SDK для доступа к конечной точке и создания приложений, поддерживающих сценарии Microsoft 365, например, повышение производительности, совместная работа, образование, интеллектуальные функции для сотрудников и рабочего места и многое другое. Microsoft Graph также включает мощный набор служб для управления удостоверениями пользователей и устройств.

Например, вы можете читать свойства пользователя, выполнившего вход, путем доступа к конечной точке https://graph.microsoft.com/v1.0/me.