Защита приложений Java Spring Boot с помощью идентификатора Microsoft Entra

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

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

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

Клиентское приложение использует клиентскую библиотеку Microsoft Entra ID Spring Boot Starter для Java для входа пользователя в систему и получения токена идентификации от Microsoft Entra ID. Маркер идентификатора подтверждает, что пользователь проходит проверку подлинности с помощью идентификатора Microsoft Entra и позволяет пользователю получить доступ к защищенным маршрутам.

Предварительные требования

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

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

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

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

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

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

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 4-spring-web-app/1-Authentication/sign-in

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

Внимание

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

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

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

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

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

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

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

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

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

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

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

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

    • В разделе Name введите осмысленное название приложения, которое будет отображаться пользователям приложения, — например, java-spring-webapp-auth.
    • В разделе "Поддерживаемые типы учетных записей" выберите только один клиент — TENANT_NAME (TENANT_NAME зависит от клиента).
    • В разделе URI перенаправления (необязательно) выберите Web в раскрывающемся списке и введите следующий URI перенаправления: http://localhost:8080/login/oauth2/code/

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

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

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

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

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

  9. Выберите одну из доступных продолжительности: рекомендуется: 180 дней (6 месяцев),90 дней (3 месяца),365 дней (12 месяцев),545 дней (18 месяцев) или 730 дней (24 месяца).

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

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

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

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

Примечание.

В следующих шагах 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 и замените существующее значение идентификатором приложения java-spring-webapp-auth или clientId, скопированным на портале Azure.

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

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

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

Предварительные требования

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

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

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

    mvn clean verify

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

    mvn spring-boot:run

Настройка

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

az login

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

az upgrade

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

Если при выполнении команд az containerapp в Azure CLI возникают ошибки из-за отсутствующих параметров, убедитесь, что у вас установлена последняя версия расширения Контейнеры приложений Azure.

az extension add --name containerapp --upgrade

Примечание.

Начиная с мая 2024 г. расширения Azure CLI больше не поддерживают предварительные версии функций по умолчанию. Чтобы получить доступ к функциям предварительной версии Container Apps, установите расширение Container Apps с помощью --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 Container Apps из предыдущего шага и 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 ID

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

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

  2. Используйте поле поиска, чтобы найти регистрацию вашего приложения, — например, java-servlet-webapp-authentication.

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

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

  5. В разделе Web - 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-файл с помощью команды CLI az containerapp up.

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-адрес выходного приложения на странице Outputs раздела Deployment.

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

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

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

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

О коде

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

Содержимое

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

Файл или папка Описание
pom.xml Зависимости приложений.
src/main/resources/templates/ Шаблоны Thymeleaf для пользовательского интерфейса.
src/main/resources/application.yml Конфигурация библиотеки Boot Starter для приложения и Microsoft Entra ID.
src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootwebapp/ Этот каталог содержит основные классы входа приложения, контроллера и конфигурации.
.../MsIdentitySpringBootWebappApplication.java Основной класс.
.../SampleController.java Контроллер с сопоставлениями конечных точек.
.../SecurityConfig.java Конфигурация безопасности— например, маршруты, для которых требуется проверка подлинности.
.../Utilities.java Вспомогательный класс — например, для фильтрации утверждений токена ID.
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

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

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig  {
    
    @Value("${app.protect.authenticated}")
    private String[] allowedOrigins;
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // @formatter:off
        http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
            .and()
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(allowedOrigins).authenticated()
                .anyRequest().permitAll()
                );
        // @formatter:on
        return http.build();
    }

    @Bean
    @RequestScope
    public ServletUriComponentsBuilder urlBuilder() {
        return ServletUriComponentsBuilder.fromCurrentRequest();
    }    
}

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

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

  • Last updated on