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

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

  • Статья

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

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

Diagram that shows the topology of the app.Схема, показывющая топологию приложения.

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

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

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

  • Некоторые знания о 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/1-Authentication/sign-in

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

Внимание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  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 и замените существующее значение идентификатором приложения или clientIdjava-spring-webapp-auth приложением, скопированным из портал 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 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 Entra ID Spring Boot Starter для Java для входа пользователей в клиент Идентификатора Microsoft Entra ID. В этом примере также используются начальные серверы клиента Spring Oauth2 и Spring Web. В примере используются утверждения из маркера идентификатора, полученного от идентификатора Microsoft Entra, для отображения сведений о входе пользователя.

Содержимое

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

Файл или папка 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 . Чтобы настроить конкретные требования приложения, примените 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.