Share via

Включение входа для приложений Java Tomcat с помощью идентификатора Microsoft Entra

  • Статья

В этой статье демонстрируется приложение Java Tomcat, которое входит в клиент Идентификатора Microsoft Entra с помощью библиотеки проверки подлинности Майкрософт (MSAL) для Java.

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

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

Клиентское приложение использует MSAL для Java (MSAL4J) для входа пользователей в собственный клиент Идентификатора Microsoft Entra ИД и получения маркера идентификатора от идентификатора Microsoft Entra ID. Маркер идентификатора подтверждает, что пользователь проходит проверку подлинности с помощью этого клиента. Приложение защищает маршруты в соответствии с состоянием проверки подлинности пользователя.

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

  • JDK версии 8 или более поздней
  • Maven 3
  • Клиент идентификатора Microsoft Entra. Дополнительные сведения см. в разделе "Как получить клиент идентификатора Microsoft Entra".
  • Учетная запись пользователя в собственном клиенте Идентификатора Microsoft Entra, если вы хотите работать только с учетными записями в каталоге организации , то есть в режиме одного клиента. Если вы не создали учетную запись пользователя в клиенте идентификатора Microsoft Entra ID, прежде чем продолжить. Дополнительные сведения см. в статье "Создание, приглашение и удаление пользователей".
  • Учетная запись пользователя в клиенте идентификатора Microsoft Entra в любой организации, если вы хотите работать с учетными записями в любом каталоге организации, то есть в режиме с несколькими клиентами. Этот пример необходимо изменить для работы с личной учетной записью Майкрософт. Если вы еще не создали учетную запись пользователя в клиенте идентификатора Microsoft Entra ID, прежде чем продолжить. Дополнительные сведения см. в статье "Создание, приглашение и удаление пользователей".
  • Личная учетная запись Майкрософт, например Xbox, Hotmail, Live и т. д., если вы хотите работать с личными учетными записями Майкрософт.

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

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

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

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

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

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

git clone https://github.com/Azure-Samples/ms-identity-java-servlet-webapp-authentication.git
cd 1-Authentication/sign-in

Кроме того, перейдите к репозиторию ms-identity-java-servlet-webapp-authentication , а затем скачайте его в виде файла .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.

Настройка приложения для использования регистрации приложения

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

Примечание.

В следующих шагах ClientID выполняется то же самое, что Application ID и AppId.

  1. Откройте проект в интегрированной среде разработки.

  2. Откройте файл ./src/main/resources/authentication.properties.

  3. Найдите строку {enter-your-tenant-id-here}. Замените существующее значение одним из следующих значений:

    • Идентификатор клиента Microsoft Entra ID, если вы зарегистрировали приложение с учетными записями в этом каталоге организации.
    • Слово organizations , если вы зарегистрировали приложение в учетных записях в любом каталоге организации.
    • Слово common , если вы зарегистрировали приложение в учетных записях в любом каталоге организации и личных учетных записях Майкрософт.
    • Слово consumers , если вы зарегистрировали приложение с помощью личных учетных записей Майкрософт.

  4. Найдите строку {enter-your-client-id-here} и замените существующее значение идентификатором приложения или clientIdjava-servlet-webapp-authentication приложением, скопированным из портал Azure.

  5. Найдите строку {enter-your-client-secret-here} и замените существующее значение значением, сохраненным во время создания java-servlet-webapp-authentication приложения, в портал Azure.

Сборка примера

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

mvn clean package

Эта команда создает WAR-файл , который можно запускать на различных серверах приложений.

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

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

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

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

При развертывании в службе приложение Azure развертывание автоматически использует учетные данные Azure из Azure CLI. Если Azure CLI не установлен локально, подключаемый модуль Maven проходит проверку подлинности с помощью OAuth или входа устройства. Дополнительные сведения см. в статье о проверке подлинности с помощью подключаемых модулей Maven.

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

  1. Выполните следующую команду, чтобы настроить развертывание. Эта команда помогает настроить операционную систему службы приложение Azure, версию Java и версию Tomcat.

    mvn com.microsoft.azure:azure-webapp-maven-plugin:2.12.0:config

  2. Для создания конфигурации запуска нажмите клавишу Y, а затем нажмите клавишу ВВОД.

  3. Для определения значения ос нажмите клавишу 1 для Windows или 2 для Linux, а затем нажмите клавишу ВВОД.

  4. Для определения значения javaVersion нажмите клавишу 2 для Java 11, а затем нажмите клавишу ВВОД.

  5. Для определения значения для webContainer нажмите клавишу 4 для Tomcat 9.0, а затем нажмите клавишу ВВОД.

  6. Чтобы определить значение для ценообразования, нажмите клавишу ВВОД, чтобы выбрать уровень P1v2 по умолчанию.

  7. Для подтверждения нажмите клавишу Y, а затем нажмите клавишу ВВОД.

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

Please confirm webapp properties
AppName : msal4j-servlet-auth-1707209552268
ResourceGroup : msal4j-servlet-auth-1707209552268-rg
Region : centralus
PricingTier : P1v2
OS : Linux
Java Version: Java 11
Web server stack: Tomcat 9.0
Deploy to slot : false
Confirm (Y/N) [Y]: [INFO] Saving configuration to pom.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  37.112 s
[INFO] Finished at: 2024-02-06T08:53:02Z
[INFO] ------------------------------------------------------------------------

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

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

<build>
    <plugins>
        <plugin>
            <groupId>com.microsoft.azure</groupId>
            <artifactId>>azure-webapp-maven-plugin</artifactId>
            <version>x.xx.x</version>
            <configuration>
                <schemaVersion>v2</schemaVersion>
                <resourceGroup>your-resourcegroup-name</resourceGroup>
                <appName>your-app-name</appName>
            ...
            </configuration>
        </plugin>
    </plugins>
</build>

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

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

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

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

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

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

  1. Перейдите к файлу authentication.properties приложения и измените значение app.homePage имени домена развернутого приложения, как показано в следующем примере. Например, если вы выбрали example-domain имя приложения на предыдущем шаге, необходимо использовать https://example-domain.azurewebsites.net для app.homePage значения. Убедитесь, что вы также изменили протокол на httphttps.

    # app.homePage is by default set to dev server address and app context path on the server
# for apps deployed to azure, use https://your-sub-domain.azurewebsites.net
app.homePage=https://<your-app-name>.azurewebsites.net

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

    mvn clean package

Внимание

В этом же файле authentication.properties у вас есть параметр aad.secret. Это не рекомендуется развертывать это значение в Служба приложений. Не рекомендуется оставить это значение в коде и потенциально отправить его в репозиторий Git. Чтобы удалить это значение секрета из кода, см. более подробные инструкции в разделе "Развертывание в Служба приложений. Удаление секрета". В этом руководстве добавлены дополнительные шаги для отправки значения секрета в Key Vault и использования ссылок на Key Vault.

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

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

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

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

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

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

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

  6. Заполните универсальный код ресурса (URI) приложения, добавляя /auth/redirect например https://<your-app-name>.azurewebsites.net/auth/redirect.

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

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

Теперь вы готовы развернуть приложение в службе приложение Azure. Используйте следующую команду, чтобы убедиться, что вы вошли в среду Azure для выполнения развертывания:

az login

Все конфигурации, готовые к использованию в файле pom.xml , теперь можно использовать следующую команду для развертывания приложения Java в Azure:

mvn package azure-webapp:deploy

После завершения развертывания приложение будет готово http://<your-app-name>.azurewebsites.net/. Откройте URL-адрес в локальном веб-браузере, где должна появиться начальная страница msal4j-servlet-auth приложения.

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

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

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

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

В этом примере показано, как использовать MSAL для Java (MSAL4J) для входа пользователей в клиент Идентификатора Microsoft Entra. Если вы хотите использовать MSAL4J в собственных приложениях, необходимо добавить его в проекты с помощью Maven.

Если вы хотите реплика копировать файл pom.xml и содержимоевспомогательных папок и папок authservlets в папке src/main/java/com/microsoft/azuresamples/msal4j. Вам также нужен файл authentication.properties . Эти классы и файлы содержат универсальный код, который можно использовать в широком массиве приложений. Вы также можете скопировать остальную часть примера, но другие классы и файлы создаются специально для решения задачи этого примера.

Содержимое

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

Файл или папка Description
AppCreationScripts/ Скрипты для автоматической настройки регистрации приложений идентификатора Microsoft Entra.
src/main/java/com/microsoft/azuresamples/msal4j/authwebapp/ Этот каталог содержит классы, определяющие серверную бизнес-логику приложения.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Этот каталог содержит классы, используемые для входа и выхода конечных точек.
____Servlet.java Все доступные конечные точки определяются в классах .java, заканчивающиеся ____Servlet.java..
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ Вспомогательные классы для проверки подлинности.
AuthenticationFilter.java Перенаправляет запросы без проверки подлинности на защищенные конечные точки на страницу 401.
src/main/resources/authentication.properties Идентификатор и конфигурация программы Microsoft Entra.
src/main/webapp/ Этот каталог содержит шаблоны JSP пользовательского интерфейса
CHANGELOG.md Список изменений в примере.
CONTRIBUTING.md Рекомендации по участию в образце.
ЛИЦЕНЗИИ Лицензия для примера.

ConfidentialClientApplication

ConfidentialClientApplication Экземпляр создается в файле AuthHelper.java, как показано в следующем примере. Этот объект помогает создать URL-адрес авторизации идентификатора Microsoft Entra, а также помогает обмениваться маркером проверки подлинности для маркера доступа.

// getConfidentialClientInstance method
IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .authority(AUTHORITY)
                     .build();

Для создания экземпляров используются следующие параметры:

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

В этом примере эти значения считываются из файла authentication.properties с помощью средства чтения свойств в файле Config.java .

Пошаговое руководство

Ниже приведены пошаговые инструкции по функциональным возможностям приложения:

  1. Первым шагом процесса входа является отправка запроса /authorize в конечную точку для клиента Идентификатора Microsoft Entra. Экземпляр MSAL4J ConfidentialClientApplication используется для создания URL-адреса запроса авторизации. Приложение перенаправляет браузер на этот URL-адрес, где пользователь входит в систему.

    final ConfidentialClientApplication client = getConfidentialClientInstance();
AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters.builder(Config.REDIRECT_URI, Collections.singleton(Config.SCOPES))
        .responseMode(ResponseMode.QUERY).prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();

final String authorizeUrl = client.getAuthorizationRequestUrl(parameters).toString();
contextAdapter.redirectUser(authorizeUrl);

    В следующем списке описываются функции этого кода:

    • AuthorizationRequestUrlParameters: параметры, которые должны быть заданы для сборки AuthorizationRequestUrl.

    • REDIRECT_URI: где идентификатор Microsoft Entra перенаправляет браузер вместе с кодом проверки подлинности после сбора учетных данных пользователя. Он должен соответствовать URI перенаправления в регистрации приложения идентификатора Записи Майкрософт в портал Azure.

    • SCOPES: области — это разрешения, запрашиваемые приложением. Как правило, три область openid profile offline_access достаточно для получения ответа маркера идентификатора.

      Полный список область, запрошенных приложением, можно найти в файле authentication.properties. Можно добавить дополнительные область, напримерUser.Read.

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

  3. Затем ConfidentialClientApplication экземпляр обменивается этим кодом авторизации для маркера идентификатора и маркера доступа из идентификатора Microsoft Entra ID.

    // First, validate the state, then parse any error codes in response, then extract the authCode. Then:
// build the auth code params:
final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
        .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES)).build();

// Get a client instance and leverage it to acquire the token:
final ConfidentialClientApplication client = AuthHelper.getConfidentialClientInstance();
final IAuthenticationResult result = client.acquireToken(authParams).get();

    В следующем списке описываются функции этого кода:

    • AuthorizationCodeParameters: параметры, которые необходимо задать для обмена кодом авторизации для идентификатора и (или) маркера доступа.
    • authCode: код авторизации, полученный в конечной точке перенаправления.
    • REDIRECT_URI: URI перенаправления, используемый на предыдущем шаге, должен быть передан еще раз.
    • SCOPES: снова необходимо передать область, используемые на предыдущем шаге.

  4. При успешном выполнении acquireToken извлекаются утверждения токена. Если проверка неисключения проходит, результаты помещаются в context экземпляр сеанса IdentityContextData и сохраняются в сеансе. Затем приложение может создать экземпляр IdentityContextData сеанса путем экземпляра IdentityContextAdapterServlet , когда ему требуется доступ, как показано в следующем коде:

    // parse IdToken claims from the IAuthenticationResult:
// (the next step - validateNonce - requires parsed claims)
context.setIdTokenClaims(result.idToken());

// if nonce is invalid, stop immediately! this could be a token replay!
// if validation fails, throws exception and cancels auth:
validateNonce(context);

// set user to authenticated:
context.setAuthResult(result, client.tokenCache().serialize());

Защита маршрутов

Сведения о том, как пример приложения фильтрует доступ к маршрутам, см. в AuthenticationFilter.java. В файле app.protect.authenticated authentication.properties свойство содержит разделенные запятыми маршруты, к которым могут получить доступ только прошедшие проверку подлинности пользователи, как показано в следующем примере:

# for example, /token_details requires any user to be signed in and does not require special roles claim(s)
app.protect.authenticated=/token_details

Области

Области сообщают Microsoft Entra ID уровень доступа, который запрашивает приложение.

На основе запрошенных область идентификатор Microsoft Entra id представляет диалог согласия для пользователя при входе. Если пользователь дает согласие на одно или несколько область и получает маркер, то область,предоставленные согласием, кодируются в результирующий access_tokenкод.

Сведения о область, запрошенных приложением, см. в разделе authentication.properties. Эти три область запрашиваются MSAL и предоставляются идентификатором Microsoft Entra по умолчанию.

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