Безопасные приложения Quarkus с идентификатором Microsoft Entra с помощью OpenID Connect

Статья
10/07/2024

В этой статье показано, как защитить приложения Red Hat Quarkus с помощью идентификатора Microsoft Entra с помощью OpenID Connect (OIDC).

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

Настройка поставщика OpenID Connect с помощью идентификатора Microsoft Entra.
Защита приложения Quarkus с помощью OpenID Connect.
Запустите и проверьте приложение Quarkus.

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

Подписка Azure. Если у вас еще нет подписки Azure, создайте бесплатную учетную запись Azure, прежде чем начать работу.
Удостоверение Azure с ролью "Администратор облачных приложений Microsoft Entra". Дополнительные сведения см. в разделе "Список назначений ролей Microsoft Entra" и встроенных ролей Microsoft Entra.
Клиент Microsoft Entra. Если у вас нет существующего клиента, см . краткое руководство. Настройка клиента.
Локальный компьютер с установленной операционной системой Unix, например Ubuntu, macOS или подсистема Windows для Linux.
Git.
Реализация Java SE версии 21 или более поздней — например, сборка Microsoft OpenJDK.
Maven версии 3.9.3 или более поздней.

Настройка поставщика OpenID Connect с помощью идентификатора Microsoft Entra

В этом разделе описана настройка поставщика OpenID Connect с идентификатором Microsoft Entra ДЛЯ использования с приложением Quarkus. В следующем разделе описана настройка приложения Quarkus с помощью OpenID Connect для проверки подлинности и авторизации пользователей в клиенте Microsoft Entra.

Создание пользователей в клиенте Microsoft Entra

Сначала создайте двух пользователей в клиенте Microsoft Entra, выполнив инструкции по созданию, приглашению и удалению пользователей. Вам просто нужен раздел "Создание нового пользователя ". Используйте следующие инструкции, как описано в этой статье, а затем вернитесь к этой статье после создания пользователей в клиенте Microsoft Entra.

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

Когда вы перейдете на вкладку "Основные сведения" в разделе "Создание нового пользователя ", выполните следующие действия.
1. Для имени участника-пользователя введите администратора. Сохраните значение, чтобы использовать его позже при входе в приложение.
2. Для псевдонима Mail выберите "Производный от имени участника-пользователя"
3. В поле Отображаемое имя введите admin.
4. В поле "Пароль" выберите "Автоматически создать пароль". Скопируйте и сохраните значение пароля , которое будет использоваться позже при входе в приложение.
5. Выберите "Учетная запись включена".
6. Выберите Просмотреть и создать>Создать. Подождите, пока пользователь не будет создан.
7. Подождите минуту или около этого и нажмите кнопку "Обновить". В списке должен появиться новый пользователь.

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

В поле "Имя участника-пользователя" введите пользователя.
В поле "Отображаемое имя" введите "Пользователь".

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

Затем зарегистрируйте приложение, выполнив действия, описанные в кратком руководстве. Регистрация приложения с помощью платформа удостоверений Майкрософт. Используйте следующие инструкции, как описано в статье, а затем вернитесь к этой статье после регистрации и настройки приложения.

Когда вы перейдете к разделу "Регистрация приложения ", выполните следующие действия.
1. Для поддерживаемых типов учетных записей выберите только учетные записи в этом каталоге организации (только каталог по умолчанию — один клиент).
2. После завершения регистрации сохраните значения идентификатора приложения (клиента) и идентификатора каталога (клиента), чтобы использовать его позже в конфигурации приложения.
Когда вы перейдете к разделу "Добавление URI перенаправления", пропустите шаги, как и сейчас. Вы добавляете URI перенаправления позже при запуске и тестировании примера приложения локально в этой статье.
Когда вы перейдете к разделу "Добавление учетных данных" , выберите вкладку "Добавить секрет клиента".
При добавлении секрета клиента запишите значение секрета клиента, которое будет использоваться позже в конфигурации приложения.

Добавление ролей приложения в приложение

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

Когда вы перейдете к ролям объявления для раздела приложения, используйте пользовательский интерфейс ролей приложения для создания ролей администратора и обычного пользователя.
1. Создайте роль администратора с помощью следующих значений:
  - В поле Отображаемое имя введите admin.
  - Для типов разрешенных элементов выберите "Пользователи или группы".
  - Для параметра Value введите администратора.
  - В поле "Описание" введите "Администратор".
  - Выберите " Включить эту роль приложения?".
2. Выберите Применить. Дождитесь создания роли.
3. Создайте обычную роль пользователя, выполнив те же действия, но со следующими значениями:
  - В поле "Отображаемое имя" введите "Пользователь".
  - Для параметра Value введите пользователя.
  - В поле "Описание" введите user.
Когда вы достигнете роли "Назначение пользователей и групп" ролей Microsoft Entra, выполните следующие действия.
1. Выберите Добавить пользователя или группу.
2. В области "Добавление назначения" для пользователей выберите "Администратор пользователя" и выберите роль "Администратор роли". Затем нажмите кнопку "Назначить". Дождитесь успешного назначения приложения. Чтобы увидеть назначенный ролями столбец роли, может потребоваться прокрутить таблицу.
3. Повторите предыдущие действия, чтобы назначить роль пользователя пользователю.
4. Выберите "Обновить" , и вы увидите пользователей и ролей, назначенных в области "Пользователи и группы ".
  
  Возможно, потребуется настроить ширину заголовков столбцов, чтобы представление выглядело как изображение.

Не выполняйте никаких других действий в разделе "Добавление ролей приложения в приложение" и их получение в маркере.

Защита приложения Quarkus с помощью OpenID Connect

В этом разделе описано, как защитить приложение Quarkus, которое выполняет проверку подлинности и авторизацию пользователей в клиенте Microsoft Entra с помощью OpenID Connect. Вы также узнаете, как предоставить пользователям доступ к определенным частям приложения с помощью управления доступом на основе ролей (RBAC).

Пример приложения Quarkus для этого краткого руководства находится на сайте GitHub в репозитории quarkus-azure и расположен в каталоге entra-id-quarkus .

Включение проверки подлинности и авторизации для безопасного приложения

Приложение имеет ресурс страницы приветствия, определенный в WelcomePage.java, который показан в следующем примере кода. Эта страница доступна для пользователей, не прошедших проверку подлинности. Корневой путь страницы приветствия находится в /.

@Path("/")
public class WelcomePage {

    private final Template welcome;

    public WelcomePage(Template welcome) {
        this.welcome = requireNonNull(welcome, "welcome page is required");
    }

    @GET
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get() {
        return welcome.instance();
    }

}

На странице приветствия пользователи могут войти в приложение, чтобы получить доступ к странице профиля. На странице приветствия есть ссылки на вход в качестве пользователя или администратора. Ссылки находятся в /profile/user и /profile/adminсоответственно. Пользовательский интерфейс страницы приветствия определен в welcome.qute.html и показан в следующем примере:

<html>
    <head>
        <meta charset="UTF-8">
        <title>Greeting</title>
    </head>
    <body>
        <h1>Hello, welcome to Quarkus and Microsoft Entra ID integration!</h1>
        <h1>
            <a href="/profile/user">Sign in as user</a>
        </h1>
        <h1>
            <a href="/profile/admin">Sign in as admin</a>
        </h1>
    </body>
</html>

/profile/admin И /profile/user ссылки указывают на ресурс страницы профиля, определенный в ProfilePage.java, как показано в следующем примере кода. Эта страница доступна только для пользователей, прошедших проверку подлинности, с помощью @RolesAllowed("**") заметки из jakarta.annotation.security.RolesAllowed пакета. Заметка @RolesAllowed("**") указывает, что доступ к пути может получить /profile только прошедший проверку подлинности.

@Path("/profile")
@RolesAllowed("**")
public class ProfilePage {

    private final Template profile;

    @Inject
    SecurityIdentity identity;

    @Inject
    JsonWebToken accessToken;

    public ProfilePage(Template profile) {
        this.profile = requireNonNull(profile, "profile page is required");
    }

    @Path("/admin")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed("admin")
    public TemplateInstance getAdmin() {
        return getProfile();
    }

    @Path("/user")
    @GET
    @Produces(MediaType.TEXT_HTML)
    @RolesAllowed({"user","admin"})
    public TemplateInstance getUser() {
        return getProfile();
    }

    private TemplateInstance getProfile() {
        return profile
                .data("name", identity.getPrincipal().getName())
                .data("roles", identity.getRoles())
                .data("scopes", accessToken.getClaim("scp"));
    }

}

Ресурс страницы профиля включает RBAC с помощью заметки @RolesAllowed . Аргументы заметки указывают, что только пользователи с ролью могут получить доступ к пути, а пользователи @RolesAllowed с admin user ролью могут admin получить доступ /profile/admin к /profile/user пути.

Обе конечные /profile/admin /profile/user точки возвращают страницу профиля. Пользовательский интерфейс страницы профиля определен в profile.qute.html, как показано в следующем примере. На этой странице отображаются имя пользователя, роли и области. На странице профиля также есть ссылка /logoutна выход, которая перенаправляет пользователя на поставщик OIDC для выхода. Страница профиля записывается с помощью обработчика шаблонов Qute. Обратите внимание на использование выражений {} на странице. Эти выражения используют значения, передаваемые TemplateInstance методу data() . Дополнительные сведения о подсистеме шаблонов Qute см. в разделе "Подсистема шаблонов Qute".

<html>
    <head>
        <meta charset="UTF-8">
        <title>Profile</title>
    </head>
    <body>
        <h1>Hello, {name}</h1>
        <h2>Roles</h2>
        <ul>
            {#if roles}
                {#for role in roles}
                    <li>{role}</li>
                {/for}
            {#else}
                <li>No roles found!</li>
            {/if}
        </ul>
        <h2>Scopes</h2>
        <p>
            {scopes}
        </p>
        <h1>
            <b><a href="/logout">Sign out</a></b>
        </h1>
    </body>
</html>

После выхода пользователь перенаправляется на страницу приветствия и снова сможет войти.

Запуск и тестирование приложения Quarkus

В этом разделе описано, как приложение Quarkus работает с идентификатором Microsoft Entra в качестве поставщика OpenID Connect.

Добавление URI перенаправления в регистрацию приложения

Чтобы успешно запустить и протестировать приложение локально, необходимо добавить URI перенаправления в регистрацию приложения. Следуйте инструкциям в разделе "Добавление URI перенаправления" краткого руководства. Регистрация приложения с помощью платформа удостоверений Майкрософт и использование следующих значений:

Для настройки платформ выберите "Веб".
Для URI перенаправления введите http://localhost:8080.

Подготовка примера

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

Используйте следующие команды, чтобы клонировать пример приложения Quarkus из GitHub и перейти к каталогу entra-id-quarkus :
```
git clone https://github.com/Azure-Samples/quarkus-azure
cd quarkus-azure/entra-id-quarkus
git checkout 2024-09-26
```
Если появится сообщение об отключенном состоянии HEAD , это сообщение безопасно игнорировать. Так как в этой статье нет фиксаций, отсоединяемое состояние HEAD подходит.
Используйте следующие команды, чтобы определить следующие переменные среды со значениями, которые вы записали ранее:
```
export QUARKUS_OIDC_CLIENT_ID=<application/client-ID>
export QUARKUS_OIDC_CREDENTIALS_SECRET=<client-secret>
export QUARKUS_OIDC_AUTH_SERVER_URL=https://login.microsoftonline.com/<directory/tenant-ID>/v2.0
```
Эти переменные среды предоставляют значения встроенной поддержки OpenID Connect в Quarkus. Соответствующие свойства application.properties показаны в следующем примере.
```
quarkus.oidc.client-id=
quarkus.oidc.credentials.secret=
quarkus.oidc.auth-server-url=
```
Если значение свойства пусто, Quarkus преобразует имя свойства в application.propertiesпеременную среды и считывает значение из среды. Дополнительные сведения о преобразовании именования см . в спецификации Конфигурации MicroProfile.

Запуск приложения Quarkus

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

Запустите приложение Quarkus в режиме разработки:
```
mvn quarkus:dev
```
Запустите приложение Quarkus в режиме JVM:
```
mvn install
java -jar target/quarkus-app/quarkus-run.jar
```

Запустите приложение Quarkus в собственном режиме:

mvn install -Dnative -Dquarkus.native.container-build
./target/quarkus-ad-1.0.0-SNAPSHOT-runner

Если вы хотите попробовать различные режимы, нажмите клавиши CTRL+C, чтобы остановить приложение Quarkus, а затем запустить приложение Quarkus в другом режиме.

Тестирование приложения Quarkus

После запуска приложения Quarkus откройте веб-браузер с частной вкладкой и перейдите к http://localhost:8080ней. Вы увидите страницу приветствия со ссылками для входа в качестве пользователя или администратора. Использование частной вкладки позволяет не загрязнять существующие действия идентификатора Microsoft Entra, которые могут быть в обычном браузере.

Сбор учетных данных для двух пользователей

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

Войдите в Центр администрирования Microsoft Entra как минимум администратор облачных приложений.
Если у вас есть доступ к нескольким клиентам, используйте значок параметров ( ) в верхнем меню, чтобы переключиться на клиент, в котором вы хотите зарегистрировать приложение из меню каталогов и подписок .
Перейдите к пользователям удостоверений > всех пользователей>.
Найдите пользователя администратора в списке и выберите его.
Найдите поле имени участника-пользователя.
Используйте значок копирования рядом со значением поля, чтобы сохранить адрес электронной почты пользователя в буфер обмена. Сохраните значение для последующего использования.
Чтобы получить адрес электронной почты для обычного пользователя, выполните те же действия.

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

Выполнение функциональных возможностей приложения

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

Выберите ссылку для входа в качестве пользователя . Войдите с помощью обычного пользователя, созданного ранее. После входа идентификатор Microsoft Entra перенаправляет вас на страницу профиля, где отображаются имена, роли и области.
Если это первый вход, вам будет предложено обновить пароль. Следуйте инструкциям по обновлению пароля.
Если вам будет предложено в вашей организации, требуются дополнительные сведения о безопасности. Следуйте инструкциям, чтобы скачать и настроить приложение Microsoft Authenticator, вы можете выбрать "Попросить позже ", чтобы продолжить тест.
Если вам будет предложено запрашивать разрешения, просмотрите разрешения, запрошенные приложением. Нажмите кнопку "Принять" , чтобы продолжить тест.
Выберите выход , чтобы выйти из приложения Quarkus. Идентификатор Microsoft Entra выполняет выход. После выхода идентификатор Microsoft Entra перенаправляет вас на страницу приветствия.
Выберите ссылку для входа в качестве администратора . Идентификатор Microsoft Entra перенаправляет вас на страницу входа. Войдите с помощью созданного ранее пользователя администратора. После входа идентификатор Microsoft Entra перенаправляет вас на аналогичную страницу профиля с другой ролью admin.
Выйдите еще раз и попробуйте войти в качестве администратора с помощью обычного пользователя, созданного ранее. Должно появиться сообщение об ошибке, так как обычный пользователь не имеет admin роли.

Очистка ресурсов

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

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

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

Следующие шаги

В этом кратком руководстве описано, как защитить приложения Quarkus с помощью идентификатора Microsoft Entra с помощью OpenID Connect. Дополнительные сведения см. в следующих ресурсах:

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