Руководство по миграции ADAL в MSAL для Java

В этой статье описаны изменения, которые необходимо внести для переноса приложения, использующего библиотеку проверки подлинности Azure Active Directory (ADAL) на Microsoft Authentication Library (MSAL).

Для проверки подлинности сущностей Microsoft Entra и запроса токенов из Microsoft Entra ID используются как Microsoft Authentication Library for Java (MSAL4J), так и Azure AD Authentication Library for Java (ADAL4J). До сих пор большинство разработчиков использовали Azure AD for developers (v1.0) для аутентификации с использованием различных типов удостоверений, таких как рабочие или учебные учетные записи, запрашивая токены с помощью библиотеки аутентификации Azure AD (ADAL).

MSAL предлагает следующие преимущества:

• Поскольку используется более новая платформа удостоверений Microsoft, вы можете выполнять проверку подлинности для более широкого набора удостоверений Microsoft, таких как удостоверения Microsoft Entra, учетные записи Microsoft, социальные и локальные учетные записи через Azure AD B2C и социальные или локальные учетные записи клиентов через Внешняя идентификация Microsoft Entra.
• Пользователи получат лучший интерфейс единого входа.
• Приложение может включить добавочное согласие, а также поддерживать новые функции, такие как условный доступ.

MSAL для Java — это библиотека аутентификации, которую мы рекомендуем использовать с платформой платформа удостоверений Майкрософт. Новые функции не будут реализованы в ADAL4J. В дальнейшем все усилия будут сосредоточены на улучшении MSAL.

Вы можете узнать больше о MSAL и начать работу, ознакомившись с обзором библиотеки Microsoft Authentication Library.

Области, а не ресурсы

ADAL4J получает маркеры для ресурсов, а MSAL для Java получает маркеры для областей. Для многих классов MSAL для Java требуется параметр областей. Этот параметр представляет собой список строк, объявляющих требуемые разрешения и ресурсы, которые запрашиваются. Ознакомьтесь с областями Microsoft Graph, чтобы просмотреть примеры областей.

Вы можете добавить к ресурсу суффикс области /.default, чтобы упростить перенос ваших приложений с ADAL на MSAL. Например, значению ресурса https://graph.microsoft.com соответствует эквивалентное значение области https://graph.microsoft.com/.default. Если ресурс представлен не в форме URL, а в виде идентификатора ресурса формата XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, вы всё равно можете использовать значение scope в виде XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Дополнительные сведения о различных типах областей действия см. в статьях «Разрешения и согласие на платформе удостоверений Майкрософт» и «Области действия для веб-API, принимающего маркеры версии 1.0».

Основные классы

В ADAL4J класс AuthenticationContext представляет собой ваше подключение к службе маркеров безопасности (STS) или серверу авторизации через Authority. Однако MSAL для Java предназначен для клиентских приложений. Он предоставляет два отдельных класса: PublicClientApplication и ConfidentialClientApplication представлять клиентские приложения. ConfidentialClientApplicationПоследний представляет приложение, которое предназначено для безопасного поддержания секрета, например идентификатора приложения для управляющей программы.

В следующей таблице показано, как функции ADAL4J сопоставляют с новым MSAL для функций Java:

Метод ADAL4J	Метод MSAL4J
acquireToken(String resource, ClientCredential credential, AuthenticationCallback callback)	ClientCredentialParameters
acquireToken(String resource, утверждение ClientAssertion, обратный вызов AuthenticationCallback)	ClientCredentialParameters
acquireToken(String resource, AsymmetricKeyCredential credential, AuthenticationCallback callback)	ClientCredentialParameters
acquireToken(String resource, String clientId, String username, String password, AuthenticationCallback callback)	UserNamePasswordParameters
acquireToken(String resource, String clientId, String username, String password=null, AuthenticationCallback callback)	IntegratedWindowsAuthenticationParameters
acquireToken(String resource, UserAssertion userAssertion, ClientCredential credential, AuthenticationCallback callback)	OnBehalfOfParameters
acquireTokenByAuthorizationCode()	AuthorizationCodeParameters
acquireDeviceCode() и acquireTokenByDeviceCode()	DeviceCodeFlowParameters
acquireTokenByRefreshToken()	SilentParameters

IAccount вместо IUser

ADAL4J работал с пользователями. Хотя пользователь соответствует одному человеку или программному агенту, у него может быть одна или несколько учетных записей в системе идентификации Microsoft. Например, у пользователя может быть несколько Microsoft Entra ID, Azure AD B2C или Microsoft личных учетных записей.

MSAL для Java определяет концепцию учетной записи через IAccount интерфейс. Это критическое изменение с ADAL4J. Он фиксирует тот факт, что один и тот же пользователь может иметь несколько учетных записей, и, возможно, даже в разных каталогах Microsoft Entra. MSAL для Java предоставляет более подробную информацию в гостевых сценариях, так как предоставляются сведения о домашней учетной записи.

Сохраняемость кэша

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

Общий центр

В версии v1.0, если вы используете центр полномочий https://login.microsoftonline.com/common, пользователи могут выполнить вход с любой учетной записью Microsoft Entra из любой организации.

Если вы используете authority https://login.microsoftonline.com/common в v2.0, пользователи могут войти с учетной записью из любой организации Microsoft Entra или даже с личной учетной записью Microsoft (MSA). В MSAL для Java, если вы хотите ограничить вход учетными записями Microsoft Entra, используйте authority https://login.microsoftonline.com/organizations (это соответствует поведению ADAL4J). Чтобы указать центр сертификации, задайте параметр authority в методе PublicClientApplication.Builder при создании экземпляра класса PublicClientApplication.

Маркеры версии 1.0 и версии 2.0

Конечная точка версии v1.0 (которую использует ADAL) возвращает только токены v1.0.

Конечная точка версии 2.0 (используется MSAL) может выдавать токены версии 1.0 и версии 2.0. Свойство манифеста приложения веб-API позволяет разработчикам выбирать версию токена. См. accessTokenAcceptedVersion в справочной документации по манифесту приложения.

Дополнительные сведения о токенах доступа v1.0 и v2.0 см. в статье Токены доступа Microsoft Entra.

Переход с ADAL на MSAL

В ADAL4J токены обновления были доступны, что позволяло разработчикам сохранять их в кэше. Затем они будут использовать AcquireTokenByRefreshToken() для включения таких решений, как реализация длительных служб, которые обновляют панели мониторинга от имени пользователя, когда пользователь больше не подключен.

MSAL для Java не раскрывает токены обновления по соображениям безопасности. Вместо этого MSAL автоматически обрабатывает обновление токенов для вас.

MSAL для Java предоставляет API, который позволяет перенести токены обновления, полученные с помощью ADAL4J, в ClientApplication: RefreshTokenParameters. С помощью этого метода вы можете предоставить ранее использованный маркер обновления вместе с любыми необходимыми вам областями (ресурсами). Маркер обновления будет заменен на новый и кэширован для использования приложением.

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

String rt = GetCachedRefreshTokenForSignedInUser(); // Get refresh token from where you have them stored
Set<String> scopes = Collections.singleton("SCOPE_FOR_REFRESH_TOKEN");

RefreshTokenParameters parameters = RefreshTokenParameters.builder(scopes, rt).build();

PublicClientApplication app = PublicClientApplication.builder(CLIENT_ID) // ClientId for your application
                .authority(AUTHORITY)  //plug in your authority
                .build();

IAuthenticationResult result = app.acquireToken(parameters);

IAuthenticationResult возвращает токен доступа и ID-токен, а ваш новый токен обновления сохраняется в кэше. Приложение теперь также будет содержать IAccount:

Set<IAccount> accounts =  app.getAccounts().join();

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

SilentParameters parameters = SilentParameters.builder(scope, accounts.iterator().next()).build();
IAuthenticationResult result = app.acquireToken(parameters);