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

Защита приложений Java Spring Boot с помощью ролей и утверждений ролей

  • Статья

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

Роли приложений, а также группы безопасности, являются популярными средствами для реализации авторизации. Используя управление доступом на основе ролей (RBAC) с ролями приложений и утверждениями ролей, вы можете безопасно применять политики авторизации с минимальными усилиями. Другим подходом является использование групп идентификаторов Microsoft Entra и утверждений групп. Группы идентификаторов и роли приложений Microsoft Entra не являются взаимоисключающими. Их можно использовать для точного управления доступом.

Видео, которое охватывает аналогичный сценарий, см. в статье "Реализация авторизации в приложениях с помощью ролей приложений, групп безопасности, областей и ролей каталога".

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

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

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

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

Такая авторизация реализуется с помощью RBAC. С помощью RBAC администратор предоставляет разрешения ролям, а не отдельным пользователям или группам. Затем администратор может назначать роли разным пользователям и группам для управления доступом к определенному содержимому и функциям.

В этом примере приложения определены следующие две роли приложения:

  • PrivilegedAdmin: авторизован для доступа только к администраторам и страницам обычных пользователей.
  • RegularUser: авторизовано для доступа к странице "Обычные пользователи ".

Эти роли приложения определяются на портале Azure в манифесте регистрации приложения. Когда пользователь входит в приложение, идентификатор Microsoft Entra выдает утверждение ролей для каждой роли, предоставленной отдельно пользователю в виде членства в роли.

Вы можете назначить пользователей и группы ролям с помощью портал Azure.

Примечание.

Утверждения роли не присутствуют для гостевых пользователей в клиенте, если https://login.microsoftonline.com/common/ конечная точка используется в качестве центра входа пользователей. Необходимо войти пользователя в клиентную конечную точку, например https://login.microsoftonline.com/tenantid.

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

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

  • Некоторые знания о 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/3-Authorization-II/roles

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

Внимание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Определение ролей приложения

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

  1. По-прежнему на той же регистрации приложения выберите роли приложений на панели навигации.

  2. Выберите " Создать роль приложения", а затем введите следующие значения:

    • Для отображаемого имени введите подходящее имя, например PrivilegedAdmin.
    • Для типов разрешенных элементов выберите "Пользователь".
    • Для параметра Value введите PrivilegedAdmin.
    • В поле "Описание" введите PrivilegedAdmins, который может просмотреть страницу администрирования.

  3. Выберите " Создать роль приложения", а затем введите следующие значения:

    • В поле Отображаемое имя введите подходящее имя, например RegularUser.
    • Для типов разрешенных элементов выберите "Пользователь".
    • Для параметра Value введите RegularUser.
    • В поле "Описание" введите RegularUsers, которые могут просматривать страницу пользователя.

  4. Щелкните Применить, чтобы сохранить изменения.

Назначение пользователей ролям приложений

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

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

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

Примечание.

В следующих шагах 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-roles приложением, скопированным из портал Azure.

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

  6. Откройте файл src/main/java/com/microsoft/azuresamples/msal4j/msidentityspringbootapplication/Sample.Controller.java.

  7. Найдите ссылки на PrivilegedAdmin роли приложения и RegularUser роли приложения в этом файле. При необходимости измените их, чтобы отразить имена ролей приложения, выбранные на предыдущих шагах.

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

В следующих разделах показано, как развернуть пример в приложениях контейнеров 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. Выберите администраторов только для просмотра /admin_only. Только пользователи с ролью PrivilegedAdmin приложения могут просматривать эту страницу. В противном случае отображается сообщение об ошибке авторизации.
  9. Выберите "Обычные пользователи", чтобы просмотреть страницу /regular_user . Только пользователи с ролью RegularUser приложения или PrivilegedAdmin могут просматривать эту страницу. В противном случае отображается сообщение об ошибке авторизации.
  10. Нажмите кнопку в углу, чтобы выйти из нее. Страница состояния отражает новое состояние.

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

В этом примере показано, как использовать клиентская библиотека 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();
}

Обработка утверждения ролей в маркере идентификатора

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

{
  ...
  "roles": [
    "PrivilegedAdmin",
    "RegularUser",]
  ...
}

Распространенный способ доступа к именам ролей описан в разделе утверждений маркера идентификатора.

Microsoft Entra ID Boot Starter версии 3.3 и более поздних версий также анализирует утверждения ролей автоматически и добавляет каждую роль в вход Authoritiesпользователя, префиксируя каждую строку APPROLE_. Эта конфигурация позволяет разработчикам использовать роли приложения с заметками условия Spring PrePost с помощью hasAuthority метода. Например, в SampleController.java можно найти следующие @PreAuthorize условия:

@GetMapping(path = "/admin_only")
@PreAuthorize("hasAuthority('APPROLE_PrivilegedAdmin')")
public String adminOnly(Model model) {
    // restrict to users who have PrivilegedAdmin app role only
}
@GetMapping(path = "/regular_user")
@PreAuthorize("hasAnyAuthority('APPROLE_PrivilegedAdmin','APPROLE_RegularUser')")
public String regularUser(Model model) {
    // restrict to users who have any of RegularUser or PrivilegedAdmin app roles
}

Следующий код получает полный список центров для данного пользователя:

@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
   Collection<? extends GrantedAuthority> authorities = principal.getAuthorities();
}

Для входа приложение отправляет запрос на конечную точку входа в систему 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, /admin_only, /regular_user)
      .antMatchers("/**").permitAll();                  // allow all other routes.
    }
}

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

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