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

  • Статья

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

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

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

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

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

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

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

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

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

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

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

git clone https://github.com/Azure-Samples/ms-identity-java-spring-tutorial.git
cd ms-identity-java-spring-tutorial
cd 1-Authentication/sign-in

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

Внимание

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

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

В этом примере есть один проект. Чтобы зарегистрировать приложение в портал Azure, можно выполнить действия по настройке вручную или использовать скрипт PowerShell. Скрипт выполняет следующие задачи:

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

Выполните следующие действия, чтобы запустить скрипт PowerShell:

  1. В Windows откройте PowerShell и перейдите к корню клонированного каталога.

  2. Используйте следующую команду, чтобы задать политику выполнения для PowerShell:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force

  3. Используйте следующие команды для запуска скрипта конфигурации:

    cd .\AppCreationScripts\
.\Configure.ps1

    Примечание.

    Другие способы выполнения скриптов описаны в сценариях создания приложений. Скрипты также предоставляют руководство по автоматической регистрации, настройке и удалению приложений, которые могут помочь в сценариях CI/CD.

Настройка приложения (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 Apps.

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

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

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

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

    mvn clean package

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

    mvn spring-boot:run

Настройка подключаемого модуля Maven

Выполните следующую команду в корне проекта, чтобы настроить приложение с помощью подключаемого модуля Maven для Azure Spring Apps:

mvn com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config

В следующем списке описаны взаимодействия с командами:

  • Вход OAuth2: необходимо авторизовать вход в Azure на основе протокола OAuth2.
  • Выберите подписку: выберите номер списка подписок, в котором вы хотите создать экземпляр Azure Spring Apps, который по умолчанию соответствует первой подписке в списке. Если вы хотите использовать номер по умолчанию, нажмите клавишу ВВОД.
  • Введите имя Azure Spring Apps: введите имя экземпляра spring apps, который вы хотите создать. Если вы хотите использовать имя по умолчанию, нажмите клавишу ВВОД.
  • Введите имя группы ресурсов: введите имя группы ресурсов, в которой вы хотите создать экземпляр spring apps. Если вы хотите использовать имя по умолчанию, нажмите клавишу ВВОД.
  • Skus: выберите номер SKU, который вы хотите использовать для экземпляра spring apps. Если вы хотите использовать номер по умолчанию, нажмите клавишу ВВОД.
  • Введите имя приложения (демонстрация): укажите имя приложения. Если вы хотите использовать идентификатор артефакта проекта по умолчанию, нажмите клавишу ВВОД.
  • Среда выполнения. Выберите среду выполнения, которую вы хотите использовать для экземпляра spring apps. В этом случае следует использовать номер по умолчанию, поэтому нажмите клавишу ВВОД.
  • Предоставление общедоступного доступа для этого приложения (boot-for-azure): нажмите клавишу y.
  • Подтвердите сохранение всех указанных выше конфигураций: нажмите клавишу Y. Если нажать клавишу N, конфигурация не сохраняется в pom-файле .

В следующем примере показаны выходные данные процесса развертывания:

Summary of properties:
Subscription id   : 12345678-1234-1234-1234-123456789101
Resource group name : rg-ms-identity-spring-boot-webapp
Azure Spring Apps name : cluster-ms-identity-spring-boot-webapp
Runtime Java version : Java 11
Region            : eastus
Sku               : Standard
App name          : ms-identity-spring-boot-webapp
Public access     : true
Instance count/max replicas : 1
CPU count         : 1
Memory size(GB)   : 2
Confirm to save all the above configurations (Y/n):
[INFO] Configurations are saved to: /home/user/ms-identity-java-spring-tutorial/1-Authentication/sign-in/pom.    xml
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:57 min
[INFO] Finished at: 2024-02-14T13:50:44Z
[INFO] ------------------------------------------------------------------------

После подтверждения выбора подключаемый модуль добавляет необходимый элемент подключаемого модуля и параметры в файл pom.xml проекта, чтобы настроить приложение для запуска в Azure Spring Apps.

Соответствующая часть файла pom.xml должна выглядеть примерно так:

<plugin>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-spring-apps-maven-plugin</artifactId>
    <version>1.19.0</version>
    <configuration>
        <subscriptionId>12345678-1234-1234-1234-123456789101</subscriptionId>
        <resourceGroup>rg-ms-identity-spring-boot-webapp</resourceGroup>
        <clusterName>cluster-ms-identity-spring-boot-webapp</clusterName>
        <region>eastus</region>
        <sku>Standard</sku>
        <appName>ms-identity-spring-boot-webapp</appName>
        <isPublic>true</isPublic>
        <deployment>
            <cpu>1</cpu>
            <memoryInGB>2</memoryInGB>
            <instanceCount>1</instanceCount>
            <runtimeVersion>Java 11</runtimeVersion>
            <resources>
                <resource>
                    <directory>${project.basedir}/target</directory>
                    <includes>
                        <include>*.jar</include>
                    </includes>
                </resource>
            </resources>
        </deployment>
    </configuration>
</plugin>

Конфигурации Azure Spring Apps можно изменить непосредственно в файле pom.xml . Некоторые распространенные конфигурации перечислены в следующей таблице:

Свойство Обязательное поле Описание
subscriptionId false Идентификатор подписки.
resourceGroup true Группа ресурсов Azure для экземпляра Azure Spring Apps.
clusterName true Имя кластера Azure Spring Apps. Если вы используете подписку и группу ресурсов, в которых уже развернут экземпляр Azure Spring Apps, можно также использовать этот существующий кластер для развертывания.
appName true Имя приложения в Azure Spring Apps.
region false Регион, в котором размещается экземпляр Azure Spring Apps. Значение по умолчанию — eastus. Допустимые регионы см. в разделе "Поддерживаемые регионы".
sku false Ценовая категория для экземпляра Azure Spring Apps. Значение по умолчанию — это Basicзначение, которое подходит только для сред разработки и тестирования.
runtime false Конфигурация среды выполнения. Дополнительные сведения см. в разделе Дополнительные сведения о конфигурации.
deployment false Конфигурация развертывания. Дополнительные сведения см. в разделе Дополнительные сведения о конфигурации.

Полный список конфигураций см. в справочной документации по подключаемым модулям. Все подключаемые модули Azure Maven используют общий набор конфигураций. Сведения об этих конфигурациях см. в разделе "Общие конфигурации". Сведения о конфигурациях, относящихся к Azure Spring Apps, см. в статье Azure Spring Apps: сведения о конфигурации.

Не забудьте сохранить в стороне clusterName и appName значения для последующего использования.

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

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

  1. Перейдите к файлу src\main\resources\application.yml приложения и измените значение post-logout-redirect-uri доменного имени развернутого приложения, как показано в следующем примере. Например, если вы выбрали cluster-ms-identity-spring-boot-webapp экземпляр Azure Spring Apps на предыдущем шаге и ms-identity-spring-boot-webapp для имени приложения, необходимо использовать https://cluster-ms-identity-spring-boot-webapp-ms-identity-spring-boot-webapp.azuremicroservices.io для post-logout-redirect-uri значения.

    post-logout-redirect-uri: https://<cluster-name>-<app-name>.azuremicroservices.io

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

    mvn clean package

Внимание

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

В качестве дополнительного шага безопасности вы можете сохранить это значение в Azure Key Vault и загрузить секрет из Key Vault , чтобы сделать его доступным в приложении.

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

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

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

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

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

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

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

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

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

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

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

mvn azure-spring-apps:deploy

В следующем списке описывается взаимодействие с командой:

  • Вход OAuth2: необходимо авторизовать вход в Azure на основе протокола OAuth2.

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

[INFO] Deployment(default) is successfully created
[INFO] Starting Spring App after deploying artifacts...
[INFO] Deployment Status: Running
[INFO]   InstanceName:demo-default-x-xxxxxxxxxx-xxxxx  Status:Running Reason:null       DiscoverStatus:UNREGISTERED
[INFO]   InstanceName:demo-default-x-xxxxxxxxx-xxxxx  Status:Terminating Reason:null       DiscoverStatus:UNREGISTERED
[INFO] Getting public url of app(demo)...
[INFO] Application url: https://<your-Azure-Spring-Apps-instance-name>-demo.azuremicroservices.io

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

После завершения развертывания получите доступ к приложению с URL-адресом выходного приложения. Выполните следующие действия, чтобы проверка журналы приложения, чтобы изучить любую проблему развертывания:

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

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

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

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

  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
AppCreationScripts/ Скрипты для автоматической настройки регистрации приложений идентификатора Microsoft Entra.
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.