Включение приложений Java Tomcat для входа пользователей и доступа к Microsoft Graph

В этой статье демонстрируется приложение Java Tomcat, которое выполняет вход пользователей и получает токен доступа для вызова Microsoft Graph. Она использует библиотеку проверки подлинности Microsoft (MSAL) для Java.

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

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

Клиентское приложение использует MSAL для Java (MSAL4J) для входа пользователя в систему и получения маркера доступа для Microsoft Graph от Microsoft Entra ID. Токен доступа подтверждает, что пользователь авторизован для доступа к конечной точке API Microsoft Graph в соответствии с областью действия.

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

  • Java 8 или более поздней версии
  • Maven 3
  • Клиент идентификатора Microsoft Entra. Дополнительные сведения см. в статье Как получить арендатор Microsoft Entra ID.
  • Учетная запись пользователя в вашем собственном тенанте Microsoft Entra ID, если вы хотите работать только с учетными записями в каталоге вашей организации, то есть в однотенантном режиме. Если вы еще не создали учетную запись пользователя в вашем арендаторе, сделайте это, прежде чем продолжить. Дополнительные сведения см. в статье Как создать, пригласить и удалить пользователей.
  • Учетная запись пользователя в клиенте Microsoft Entra ID любой организации, если вы хотите работать с учетными записями в любом каталоге организации, то есть в мультитенантном режиме. Этот пример необходимо изменить для работы с личной учетной записью Майкрософт. Если вы еще не создали учетную запись пользователя в вашем арендаторе, сделайте это, прежде чем продолжить. Дополнительные сведения см. в статье Как создать, пригласить и удалить пользователей.
  • Личная учетная запись Майкрософт, например Xbox, Hotmail, Live и т. д., если вы хотите работать с личными учетными записями Майкрософт.
  • Tomcat 9
  • 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/2-Authorization-I/call-graph

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

Внимание

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

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

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

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

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

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

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

Зарегистрируйте приложение (java-servlet-webapp-call-graph)

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

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

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

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

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

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

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

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

    • Выберите персональные учетные записи Майкрософт для использования только пользователями личных учетных записей Майкрософт, например Hotmail, Live, Skype и Xbox.

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

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

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

  6. Выберите Сохранить, чтобы сохранить изменения.

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

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

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

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

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

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

  13. На странице регистрации приложения выберите API permissions на панели навигации, чтобы открыть страницу добавления доступа к API, необходимым вашему приложению.

  14. Выберите Добавить разрешения.

  15. Убедитесь, что выбрана вкладка API Майкрософт.

  16. В разделе Часто используемые интерфейсы API Microsoft выберите Microsoft Graph.

  17. В разделе "Делегированные разрешения" выберите User.Read из списка. При необходимости используйте поле поиска.

  18. Выберите Добавить разрешения.

Настройте приложение (java-servlet-webapp-call-graph) для использования вашей регистрации приложения

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

Примечание.

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

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

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

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

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

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

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

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

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

mvn clean package

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

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

  • Развертывание в Служба приложений Azure
  • Запуск локально

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

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

  • Плагин Maven для приложений Служба приложений Azure

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

    • IntelliJ IDEA
    • Eclipse
    • Visual Studio Code

Настройте плагин Maven

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

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

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

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

  2. Для Создать новую конфигурацию запуска нажмите Y, затем нажмите Enter.

  3. Для значения параметра ОС нажмите 1 для Windows или 2 для Linux, затем нажмите Enter.

  4. Для определения значения javaVersion нажмите 2 для Java 11, затем нажмите Enter.

  5. При появлении Define value for webContainer нажмите 4 для Tomcat 9.0, затем нажмите Enter.

  6. Чтобы задать значение для pricingTier, нажмите Enter, чтобы выбрать уровень P1v2 по умолчанию.

  7. Для подтверждения нажмите Y, затем нажмите Enter.

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

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>

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

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

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

Не забудьте сохранить отдельно значения и для дальнейшего использования.

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

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

  1. Откройте файл authentication.properties вашего приложения и измените значение на доменное имя вашего развернутого приложения, как показано в следующем примере. Например, если на предыдущем шаге вы выбрали в качестве имени приложения, то теперь необходимо использовать в качестве значения . Убедитесь, что вы также изменили протокол с на .

    # 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 у вас есть параметр для . Не рекомендуется развертывать это значение в App Service. Также не стоит оставлять это значение в коде, чтобы случайно не отправить его в репозиторий Git. Чтобы удалить этот секрет из кода, дополнительные сведения см. в разделе Развертывание в App Service — удаление секрета. В это руководство добавлены дополнительные шаги для передачи значения секрета в Key Vault, а также для использования Key Vault References.

Обновите регистрацию приложения Microsoft Entra ID

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

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

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

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

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

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

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

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

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

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

az login

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

mvn package azure-webapp:deploy

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

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

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

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

О коде

В этом примере используется MSAL для Java (MSAL4J) для входа пользователя в систему и получения токена для Microsoft API Graph. Он использует Microsoft Graph SDK for Java для получения данных из Microsoft Graph. Эти библиотеки необходимо добавить в проекты с помощью Maven.

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

Содержимое

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

Файл или папка Описание
src/main/java/com/microsoft/azuresamples/msal4j/callgraphwebapp/ Этот каталог содержит классы, определяющие серверную бизнес-логику приложения.
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);

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

    • : параметры, которые необходимо задать, чтобы сформировать .
    • : Куда 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 or groups claim(s)
app.protect.authenticated=/token_details, /call_graph

Граф вызовов

Когда пользователь переходит к , приложение создает экземпляр из Java Graph SDK, передавая токен доступа вошедшего в систему пользователя. Клиент Graph помещает маркер доступа в заголовки своих запросов . Затем приложение просит клиента Graph вызвать конечную точку , чтобы получить сведения о пользователе, вошедшем в систему.

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

//CallGraphServlet.java
User user = GraphHelper.getGraphClient(contextAdapter).me().buildRequest().get();

Области действия

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

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

Сведения об областях, запрошенных приложением, см. в authentication.properties. По умолчанию приложение задаёт значение параметра scopes как . Эта конкретная область API Microsoft Graph предназначена для доступа к сведениям текущего пользователя, вошедшего в систему. Конечная точка Graph для доступа к этой информации: . Все допустимые запросы, отправленные к этой конечной точке, должны содержать , который содержит область действия в заголовке .

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

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