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

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

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

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

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

Предварительные требования

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

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

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

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

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

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

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

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 3-java-servlet-web-app/1-Authentication/sign-in

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

Внимание

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

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

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

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

Затем выполните следующие действия, чтобы завершить регистрацию:

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

  2. Выберите Новая регистрация.

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

    • В разделе Имя введите понятное название приложения, которое будет отображаться пользователям приложения, — например, .

    • В разделе "Поддерживаемые типы учетных записей" выберите один из следующих вариантов:

      • Выберите Учетные записи только в этом каталоге организации, если вы создаете приложение, предназначенное для использования только пользователями в вашем клиенте, то есть однотенантное приложение.
      • Выберите Учетные записи в любом каталоге организации, если хотите, чтобы пользователи в любом клиенте Microsoft Entra ID могли использовать ваше приложение, то есть это мультитенантное приложение.
      • Выберите вариант Учетные записи в любом каталоге организации и личные учетные записи Microsoft для максимально широкого круга клиентов, то есть мультитенантное приложение, которое также поддерживает личные учетные записи Microsoft.
      • Выберите персональные учетные записи Майкрософт для использования только пользователями личных учетных записей Майкрософт, например Hotmail, Live, Skype и Xbox.

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

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

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

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

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

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

  9. Выберите срок истечения действия секрета или укажите пользовательский срок его существования. Секреты клиента ограничены максимальным сроком существования 24 месяцев, и Microsoft рекомендует срок действия менее 12 месяцев. Для боевых приложений предпочтительнее использовать сертификат или учетные данные федеративной идентификации вместо секрета клиента.

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

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

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

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

Примечание.

В следующих шагах — это то же самое, что и или .

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

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

  3. Найдите строку . Замените существующее значение одним из следующих значений:

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

  4. Найдите строку и замените существующее значение на идентификатор приложения или приложения , скопированный из портала Azure.

  5. Найдите строку и замените текущее значение на значение, которое вы сохранили при создании приложения в портале Azure.

Соберите пример

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

mvn clean package

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

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

В этих инструкциях предполагается, что вы установили WebSphere и настроили сервер. Вы можете использовать инструкции в Развертывание кластера WebSphere Application Server (традиционного) на виртуальных машинах Azure для базовой конфигурации сервера.

Перед развертыванием в WebSphere выполните следующие действия, чтобы внести некоторые изменения конфигурации в сам пример, а затем создать или перестроить пакет:

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

    # 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://<server-url>:<port-number>/msal4j-servlet-auth/

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

    mvn clean package

  3. После завершения сборки кода скопируйте файл .war в файловую систему целевого сервера.

Кроме того, необходимо внести то же изменение в регистрацию приложения Azure, указав его в портале Azure в качестве значения URI перенаправления на вкладке Аутентификация.

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

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

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

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

  5. В разделе WebRedirect URIs выберите Add URI.

  6. Укажите URI приложения, добавив в конец /auth/redirect - например, .

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

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

  1. На вкладке "Приложения" выберите "Новое приложение", а затем "Новое корпоративное приложение".

  2. Выберите файл .war, который вы собрали, затем нажимайте Далее, пока не дойдёте до шага установки Сопоставление корней контекста для веб-модулей. Другие параметры по умолчанию должны подойти.

  3. Для корневого пути контекста задайте то же значение, что и после номера порта в 'Redirect URI', который вы указали в примере конфигурации/при регистрации приложения Azure. То есть, если URI перенаправления — , то корневой путь контекста должен быть .

  4. Выберите Готово.

  5. После завершения установки приложения перейдите в раздел корпоративных приложений WebSphere на вкладке "Приложения".

  6. Выберите в списке приложений файл .war, который вы установили, а затем выберите Start, чтобы выполнить развертывание.

  7. После завершения развертывания перейдите к , и вы должны увидеть приложение.

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

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

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

О коде

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

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

Содержимое

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

Файл или папка Описание
src/main/java/com/microsoft/azuresamples/msal4j/authwebapp/ Этот каталог содержит классы, определяющие серверную бизнес-логику приложения.
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ Этот каталог содержит классы, используемые для входа и выхода конечных точек.
*Servlet.java Все доступные конечные точки определяются в классах Java с именами, заканчивающимися Servlet.
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

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

// 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. Первым шагом в процессе входа является отправка запроса к конечной точке для вашего арендатора Microsoft Entra ID. Экземпляр MSAL4J используется для формирования 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);

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

    • : параметры, которые необходимо задать для формирования AuthorizationRequestUrl.

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

    • : Области действия — это разрешения, запрашиваемые приложением. Как правило, трех областей действия достаточно для получения ответа с токеном идентификации.

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

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

  3. Затем экземпляр обменивает этот код авторизации на маркер ID и маркер доступа от 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();

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

    • : Параметры, которые необходимо задать, чтобы обменять код авторизации на ID и/или маркер доступа.
    • : код авторизации, который был получен в конечной точке перенаправления.
    • : URI перенаправления, который использовался на предыдущем шаге, необходимо снова передать.
    • : Области действия, использованные на предыдущем шаге, необходимо снова передать.

  4. Если выполнение прошло успешно, извлекаются утверждения из токена. Если проверка nonce проходит успешно, результаты помещаются в — экземпляр — и сохраняются в сессии. Затем приложение может создать экземпляр из сеанса с помощью экземпляра всякий раз, когда ему требуется доступ к нему, как показано в следующем коде:

    // 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. В файле 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 отображает пользователю диалоговое окно согласия при входе в систему. Если пользователь соглашается с одной или несколькими областями действия и получает токен, то согласованные области действия кодируются в полученном .

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

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

  • Библиотека аутентификации Microsoft (MSAL) для Java
  • Справочная документация по MSAL Java
  • платформа идентификации Microsoft (Microsoft Entra ID для разработчиков)
  • Краткое руководство. Регистрация приложения на платформе удостоверений Майкрософт
  • Общие сведения о сценариях предоставления согласия для приложений в Microsoft Entra ID
  • Понимание согласия пользователя и администратора
  • Примеры кода MSAL

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

Развертывание Java-приложений WebSphere в Traditional WebSphere на виртуальных машинах Azure

  • Last updated on