Поделиться через

Включение приложений Java Spring Boot для входа пользователей и доступа к Microsoft Graph

  • Статья

В этой статье показано веб-приложение Java Spring Boot, которое входит в систему пользователей и получает маркер доступа для вызова Microsoft Graph. Он использует клиентская библиотека Microsoft Entra ID Spring Boot Starter для Java для проверки подлинности, авторизации и получения маркеров. Он использует пакет SDK Microsoft Graph для Java для получения данных из Graph.

На следующей схеме показана топология приложения:

Схема, показывющая топологию приложения.

Приложение использует клиентская библиотека Microsoft Entra ID Spring Boot Starter для Java для получения маркера доступа для Microsoft Graph из идентификатора Microsoft Entra. Маркер доступа подтверждает, что пользователь может получить доступ к конечной точке API Microsoft Graph, как определено в области.

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

Рекомендации

  • Некоторые знания о Spring Framework.
  • Некоторые знания о терминале Linux/OSX.
  • jwt.ms для проверки маркеров.
  • Fiddler для мониторинга активности сети и устранения неполадок.
  • Следуйте блогу по идентификатору Microsoft Entra ID, чтобы оставаться в курсе последних разработок.

Настройка примера

В следующих разделах показано, как настроить пример приложения.

Клонирование или скачивание примера репозитория

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

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 4-spring-web-app/2-Authorization-I/call-graph

Кроме того, перейдите к репозиторию ms-identity-msal-java-samples , а затем скачайте его в виде файла .zip и извлеките его на жесткий диск.

Внимание

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

Регистрация примеров приложений в клиенте Идентификатора Microsoft Entra

В этом примере есть один проект. В следующих разделах показано, как зарегистрировать приложение с помощью портал Azure.

Выберите клиент Идентификатора Microsoft Entra, в котором вы хотите создать приложения

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

  1. Войдите на портал Azure.

  2. Если ваша учетная запись присутствует в нескольких клиентах идентификатора Microsoft Entra ID, выберите профиль в углу портал Azure, а затем выберите "Переключить каталог", чтобы изменить сеанс на нужный клиент Идентификатора Microsoft Entra.

Регистрация приложения (java-spring-webapp-call-graph)

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

  1. Перейдите к портал Azure и выберите идентификатор Microsoft Entra.

  2. Выберите "Регистрация приложений" на панели навигации и выберите "Создать регистрацию".

  3. На появившемся экране "Регистрация приложения" введите следующие сведения о регистрации приложения:

    • В разделе "Имя" введите понятное имя приложения для отображения пользователям приложения, напримерjava-spring-webapp-call-graph.
    • В разделе Поддерживаемые типы учетных записей выберите Учетные записи только в этом каталоге организации.
    • В разделе URI перенаправления (необязательно) выберите веб-файл в поле со списком и введите следующий URI перенаправления: http://localhost:8080/login/oauth2/code/

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

  5. На странице регистрации приложения найдите и скопируйте значение идентификатора приложения (клиента), которое будет использоваться позже. Это значение используется в файле конфигурации или файлах приложения.

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

  7. В разделе Секреты клиента выберите Создать секрет клиента.

  8. Введите описание, например секрет приложения.

  9. Выберите одну из доступных продолжительности: в течение 1 года, за 2 года или никогда не истекает.

  10. Выберите Добавить. Отображается созданное значение.

  11. Скопируйте и сохраните созданное значение для использования в последующих шагах. Это значение требуется для файлов конфигурации кода. Это значение не отображается снова, и его нельзя получить другими средствами. Таким образом, не забудьте сохранить его из портал Azure перед переходом на любой другой экран или область.

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

  13. Выберите " Добавить разрешения", а затем убедитесь, что выбрана вкладка API Майкрософт.

  14. В разделе Часто используемые интерфейсы API Microsoft выберите Microsoft Graph.

  15. В разделе "Делегированные разрешения" выберите User.Read из списка. При необходимости используйте поле поиска.

  16. Выберите Добавить разрешения.

Настройка приложения (java-spring-webapp-call-graph) для использования регистрации приложения

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

Примечание.

В следующих шагах ClientID выполняется то же самое, что Application ID и AppId.

  1. Откройте проект в интегрированной среде разработки.

  2. Откройте файл src\main\resources\application.yml.

  3. Найдите заполнитель Enter_Your_Tenant_ID_Here и замените существующее значение идентификатором клиента Microsoft Entra.

  4. Найдите заполнитель Enter_Your_Client_ID_Here и замените существующее значение идентификатором приложения или clientId java-spring-webapp-call-graph приложением, скопированным из портал Azure.

  5. Найдите заполнитель Enter_Your_Client_Secret_Here и замените существующее значение значением, сохраненным во время создания скопированного java-spring-webapp-call-graph из портал Azure.

Запуск примера

В следующих разделах показано, как развернуть пример в приложениях контейнеров Azure.

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

  • Учетная запись Azure. Если ее нет, создайте бесплатную учетную запись. Чтобы продолжить, вам потребуется разрешение участника или владельца подписки Azure. Дополнительные сведения см. в разделе Назначение ролей Azure с помощью портала Azure.
  • Интерфейс командной строки Azure.
  • Расширение ИНТЕРФЕЙСА командной строки для приложений контейнеров Azure или более поздней версии 0.3.47 . Чтобы установить последнюю версию, используйте az extension add --name containerapp --upgrade --allow-preview команду.
  • Пакет средств разработки Java версии 17 или более поздней.
  • Maven.

Подготовка проекта Spring

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

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

    mvn clean verify

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

    mvn spring-boot:run

Настройка

Чтобы войти в Azure из ИНТЕРФЕЙСА командной строки, выполните следующую команду и следуйте инструкциям, чтобы завершить процесс проверки подлинности.

az login

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

az upgrade

Затем установите или обновите расширение "Приложения контейнеров Azure" для интерфейса командной строки.

Если при выполнении az containerapp команд в Azure CLI возникают ошибки, связанные с отсутствующими параметрами, убедитесь, что установлена последняя версия расширения azure Container Apps.

az extension add --name containerapp --upgrade

Примечание.

Начиная с мая 2024 г. расширения Azure CLI больше не поддерживают предварительные версии функций по умолчанию. Чтобы получить доступ к функциям предварительной версии контейнерных приложений, установите расширение "Приложения контейнеров" с --allow-preview trueпомощью .

az extension add --name containerapp --upgrade --allow-preview true

Теперь, когда установлено текущее расширение или модуль, зарегистрируйте Microsoft.App пространства имен и Microsoft.OperationalInsights пространств имен.

Примечание.

Ресурсы Контейнеров приложений Azure перенесены из пространства имен Microsoft.Web в пространство имен Microsoft.App. Дополнительные сведения см. в статье о миграции пространства имен из Microsoft.Web в Microsoft.App в марте 2022 г..

az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

Создание среды "Приложения контейнеров Azure"

После завершения настройки Azure CLI вы можете определить переменные среды, которые используются в этой статье.

Определите следующие переменные в оболочке Bash.

export RESOURCE_GROUP="ms-identity-containerapps"
export LOCATION="canadacentral"
export ENVIRONMENT="env-ms-identity-containerapps"
export API_NAME="ms-identity-api"
export JAR_FILE_PATH_AND_NAME="./target/ms-identity-spring-boot-webapp-0.0.1-SNAPSHOT.jar"

Создать группу ресурсов.

az group create  \
    --name $RESOURCE_GROUP \
    --location $LOCATION \

Создайте среду с автоматически созданной рабочей областью Log Analytics.

az containerapp env create \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION

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

az containerapp env show \
    --name $ENVIRONMENT \
    --resource-group $RESOURCE_GROUP \
    --query properties.defaultDomain

Подготовка приложения к развертыванию

При развертывании приложения в приложениях контейнеров Azure URL-адрес перенаправления изменяется на URL-адрес перенаправления развернутого экземпляра приложения в приложениях контейнеров Azure. Чтобы изменить эти параметры в файле application.yml , выполните следующие действия.

  1. Перейдите к файлу src\main\resources\application.yml приложения и измените значение post-logout-redirect-uri доменного имени развернутого приложения, как показано в следующем примере. Обязательно замените <API_NAME> <default-domain-of-container-app-environment> и на ваши фактические значения. Например, с доменом по умолчанию для среды приложения контейнеров Azure из предыдущего шага и ms-identity-api для имени приложения вы будете использовать https://ms-identity-api.<default-domain> значение post-logout-redirect-uri .

    post-logout-redirect-uri: https://<API_NAME>.<default-domain-of-container-app-environment>

  2. После сохранения этого файла используйте следующую команду, чтобы перестроить приложение:

    mvn clean package

Внимание

Файл application.yml приложения в настоящее время содержит значение секрета клиента в параметре client-secret . Не рекомендуется хранить это значение в этом файле. Вы также можете рисковать, если зафиксировать файл в репозитории Git. Рекомендуемый подход см. в статье "Управление секретами в приложениях контейнеров Azure".

Обновление регистрации приложения идентификатора Microsoft Entra

Так как URI перенаправления изменяется в развернутом приложении в приложениях контейнеров Azure, необходимо также изменить URI перенаправления в регистрации приложения Идентификатора Microsoft Entra. Чтобы внести это изменение, выполните следующие действия:

  1. Перейдите на страницу Регистрация приложений Платформы удостоверений Майкрософт для разработчиков.

  2. Используйте поле поиска для поиска регистрации приложения, например java-servlet-webapp-authentication.

  3. Откройте регистрацию приложения, выбрав его имя.

  4. Выберите Проверка подлинности в меню.

  5. В разделе URI веб-перенаправления - выберите "Добавить URI".

  6. Заполните универсальный код ресурса (URI) приложения, добавляя /login/oauth2/code/ например https://<containerapp-name>.<default domain of container app environment>/login/oauth2/code/.

  7. Выберите Сохранить.

Развертывание приложения

Разверните пакет JAR в приложениях контейнеров Azure.

Примечание.

При необходимости можно указать версию JDK в переменных среды сборки Java. Дополнительные сведения см. в статье "Создание переменных среды для Java" в приложениях контейнеров Azure.

Теперь вы можете развернуть WAR-файл с помощью az containerapp up команды CLI.

az containerapp up \
    --name $API_NAME \
    --resource-group $RESOURCE_GROUP \
    --location $LOCATION \
    --environment $ENVIRONMENT \
    --artifact <JAR_FILE_PATH_AND_NAME> \
    --ingress external \
    --target-port 8080 \
    --query properties.configuration.ingress.fqdn

Примечание.

Версия JDK по умолчанию — 17. Если необходимо изменить версию JDK для совместимости с приложением, можно использовать --build-env-vars BP_JVM_VERSION=<YOUR_JDK_VERSION> аргумент для настройки номера версии.

Дополнительные переменные среды сборки см. в статье "Создание переменных среды для Java" в приложениях контейнеров Azure.

Проверка приложения

В этом примере containerapp up команда включает --query properties.configuration.ingress.fqdn аргумент, который возвращает полное доменное имя (FQDN), также известное как URL-адрес приложения. Выполните следующие действия, чтобы проверить журналы приложения, чтобы изучить любую проблему развертывания:

  1. Перейдите по URL-адресу выходного приложения на странице "Выходные данные" раздела "Развертывание".

  2. На панели навигации на странице "Обзор экземпляра приложений контейнеров Azure" выберите журналы, чтобы проверить журналы приложения.

Анализ примера

Чтобы изучить пример, выполните следующие действия.

  1. Обратите внимание, что состояние входа или выхода отображается в центре экрана.
  2. Нажмите кнопку с учетом контекста в углу. Эта кнопка считывает вход при первом запуске приложения. Кроме того, выберите сведения о маркере или граф вызова. Так как эта страница защищена и требует проверки подлинности, вы автоматически перенаправляетесь на страницу входа.
  3. На следующей странице следуйте инструкциям и войдите с учетной записью в клиенте идентификатора Microsoft Entra ID.
  4. На экране согласия обратите внимание на запрашиваемые области.
  5. После успешного завершения потока входа необходимо перенаправить на домашнюю страницу, в которой отображается состояние входа или одна из других страниц в зависимости от того, какая кнопка активировала поток входа.
  6. Обратите внимание, что кнопка с учетом контекста теперь говорит выход и отображает имя пользователя.
  7. Если вы находитесь на домашней странице, выберите "Сведения о маркере идентификатора", чтобы просмотреть некоторые декодированные утверждения маркера идентификатора.
  8. Выберите "Граф вызовов", чтобы вызвать конечную точку Microsoft Graph /me и просмотреть выбор полученных сведений о пользователе.
  9. Нажмите кнопку в углу, чтобы выйти из нее. Страница состояния отражает новое состояние.

Примечания о коде

В этом примере показано, как использовать клиентную библиотеку Microsoft Entra ID Spring Boot Starter для Java для входа пользователей в клиент Идентификатора Microsoft Entra ID и получить маркер доступа для вызова Microsoft Graph. В этом примере также используются начальные серверы клиента Spring Oauth2 и Spring Web.

Содержимое

В следующей таблице показано содержимое папки примера проекта:

Файл или папка Description
pom.xml Зависимости приложений.
src/main/resources/templates/ Шаблоны Thymeleaf для пользовательского интерфейса.
src/main/resources/application.yml Конфигурация начальной библиотеки начального начального файла приложения и идентификатора Microsoft Entra.
src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootwebapp/ Этот каталог содержит основные классы входа приложения, контроллера и конфигурации.
.../MsIdentitySpringBootWebappApplication.java Основной класс.
.../SampleController.java Контроллер с сопоставлениями конечных точек.
.../SecurityConfig.java Конфигурация безопасности— например, маршруты, для которых требуется проверка подлинности.
.../Utilities.java Класс служебной программы— например, утверждения маркера идентификатора фильтра.
CHANGELOG.md Список изменений в примере.
CONTRIBUTING.md Рекомендации по участию в образце.
ЛИЦЕНЗИЯ Лицензия для примера.

Утверждения маркера идентификатора

Чтобы извлечь сведения о маркере, приложение использует объект Spring Security AuthenticationPrincipal и OidcUser объект в сопоставлении запросов, как показано в следующем примере. Полные сведения об использовании утверждений маркера идентификатора см. в примере контроллера .

import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
//...
@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
    Map<String, Object> claims = principal.getIdToken().getClaims();
}

Для входа приложение отправляет запрос на конечную точку входа в систему Microsoft Entra ID автоматически, настроенную клиентской библиотекой Microsoft Entra ID Spring Boot Starter для Java, как показано в следующем примере:

<a class="btn btn-success" href="/oauth2/authorization/azure">Sign In</a>

Для выхода приложение выполняет запрос POST к logout конечной точке, как показано в следующем примере:

<form action="#" th:action="@{/logout}" method="post">
  <input class="btn btn-warning" type="submit" value="Sign Out" />
</form>

Элементы пользовательского интерфейса, зависящие от проверки подлинности

Приложение имеет простую логику на страницах шаблона пользовательского интерфейса для определения содержимого, отображаемого на основе проверки подлинности пользователя, как показано в следующем примере с помощью тегов Spring Security Thymeleaf:

<div sec:authorize="isAuthenticated()">
  this content only shows to authenticated users
</div>
<div sec:authorize="isAnonymous()">
  this content only shows to not-authenticated users
</div>

Защита маршрутов с помощью AADWebSecurityConfigurerAdapter

По умолчанию приложение защищает страницы маркера идентификатора и графа вызовов, чтобы доступ к ним могли получить только пользователи, выполнившего вход. Приложение настраивает эти маршруты из свойства из app.protect.authenticated файла application.yml . Чтобы настроить конкретные требования приложения, вы можете расширить AADWebSecurityConfigurationAdapter один из классов. Пример см. в классе SecurityConfig этого приложения, показанном в следующем коде:

@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends AADWebSecurityConfigurerAdapter{
  @Value( "${app.protect.authenticated}" )
  private String[] protectedRoutes;

    @Override
    public void configure(HttpSecurity http) throws Exception {
    // use required configuration form AADWebSecurityAdapter.configure:
    super.configure(http);
    // add custom configuration:
    http.authorizeRequests()
      .antMatchers(protectedRoutes).authenticated()     // limit these pages to authenticated users (default: /token_details, /call_graph)
      .antMatchers("/**").permitAll();                  // allow all other routes.
    }
}

Граф вызовов

Когда пользователь перейдет/call_graph, приложение создает экземпляр с помощью Oauth2AuthorizedClient graphAuthorizedClient начального или подготовленного GraphServiceClient начального загрузчика идентификатора Microsoft Entra. Приложение запрашивает GraphServiceClient вызов конечной /me точки и отображает сведения о текущем вошедшего пользователя. GraphServiceClient находится в пакете SDK Microsoft Graph для Java версии 3.

Необходимо Oauth2AuthorizedClient подготовиться с правильными областями. Ознакомьтесь с файлом application.yml и приведенным ниже разделом "Области". Используется Oauth2AuthorizedClient для поверхности маркера доступа и его размещения в Authorization заголовке GraphServiceClient запросов, как показано в следующем примере:

//see SampleController.java
@GetMapping(path = "/call_graph")
public String callGraph(@RegisteredOAuth2AuthorizedClient("graph") OAuth2AuthorizedClient graphAuthorizedClient) {
  // See the Utilities.graphUserProperties() method for the full example of the following operation:
  GraphServiceClient graphServiceClient = Utilities.getGraphServiceClient(graphAuthorizedClient);
  User user = graphServiceClient.me().buildRequest().get();
  return user.displayName;
}

В следующем примере из файла application.yml показаны запрошенные области:

# see application.yml file
authorization-clients:
  graph:
    # Specifies the Microsoft Graph scopes that your app needs access to:
    scopes: https://graph.microsoft.com/User.Read

Области

Области сообщают Microsoft Entra ID уровень доступа, который запрашивает приложение. Области Microsoft Graph, запрошенные этим приложением, см . в application.yml.

По умолчанию приложение задает значение https://graph.microsoft.com/User.Readобластей. Область User.Read действия заключается в доступе к сведениям текущего вошедшего пользователя из конечной точки /me. Допустимые запросы к конечной точке /me должны содержать User.Read область.

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

В этом приложении отображается маркер доступа, который подтверждает, graphAuthorizedClient какие области пользователь согласился. Приложение использует этот маркер для создания экземпляра, обрабатывающего GraphServiceClient запросы Graph.

Используя GraphServiceClient.me().buildRequest().get()запрос, создается и выполняется в https://graph.microsoft.com/v1.0/me. Маркер доступа помещается в Authorization заголовок запроса.

Дополнительные сведения

Дополнительные сведения о работе протоколов OAuth 2.0 в этом сценарии и других сценариях см. в сценариях проверки подлинности для идентификатора Microsoft Entra.