Průvodce migrací ADAL do MSAL pro Java

Tento článek popisuje změny, které je potřeba provést při migraci aplikace, která používá knihovnu Azure Active Directory Authentication Library (ADAL) do knihovny Identity a ověřování Microsoftu (MSAL).

Knihovna Microsoft Authentication Library pro jazyk Java (MSAL4J) i knihovna Azure AD Authentication Library pro jazyk Java (ADAL4J) slouží k ověřování entit Microsoft Entra a k vyžádání tokenů z Microsoft Entra ID. Doteď většina vývojářů pracovala s Azure AD pro vývojáře (v1.0) k ověřování s různými identitami, jako jsou pracovní a školní účty, a to vyžádáním tokenů pomocí knihovny Azure AD Authentication Library (ADAL).

MSAL nabízí následující výhody:

• Vzhledem k tomu, že používá novější Microsoft identity platform, můžete ověřit širší sadu Microsoft identit, jako jsou Microsoft Entra identity, účty Microsoft, sociální a místní účty prostřednictvím Azure AD Business to Consumer (Azure AD B2C) a účty sociálních nebo místních zákazníků prostřednictvím Microsoft Entra Externí ID.
• Vaši uživatelé získají nejlepší prostředí jednotného přihlašování.
• Vaše aplikace může povolit přírůstkový souhlas a podporovat nové funkce, jako je podmíněný přístup.

Knihovna MSAL pro Java je knihovna pro ověřování, kterou doporučujeme používat s Microsoft identity platform. V ADAL4J nebudou implementovány žádné nové funkce. Veškeré úsilí v budoucnu se zaměřuje na zlepšení MSAL.

Další informace o knihovně MSAL a také úvod do práce s ní najdete v přehledu knihovny Identity a ověřování Microsoftu.

Obory, nikoli prostředky

ADAL4J získává tokeny pro prostředky, zatímco MSAL pro Java získává tokeny pro obory. Mnoho tříd MSAL pro Javu vyžaduje parametr scopes. Tento parametr je seznam řetězců, které deklarují požadovaná oprávnění a prostředky. Příklady oblastí oprávnění najdete v oblastech oprávnění Microsoft Graph.

K prostředku můžete přidat příponu oboru /.default, abyste usnadnili migraci svých aplikací z ADAL na MSAL. Například pro hodnotu prostředku https://graph.microsoft.com je ekvivalentní hodnota rozsahu https://graph.microsoft.com/.default. Pokud prostředek není ve formě adresy URL, ale má ID prostředku ve tvaru XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, stále můžete použít hodnotu scope jako XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Další informace o různých typech rozsahů najdete v článcích Oprávnění a souhlas v platformě Microsoft identity a Rozsahy pro webové rozhraní API přijímající tokeny v1.0.

Základní třídy

V ADAL4J AuthenticationContext třída představuje vaše připojení ke službě tokenů zabezpečení (STS) nebo autorizačnímu serveru prostřednictvím autority. MSAL pro Javu je však navržena s ohledem na klientské aplikace. Poskytuje dvě samostatné třídy: PublicClientApplication a ConfidentialClientApplication představují klientské aplikace. Ta druhá, ConfidentialClientApplication, představuje aplikaci, která je navržena tak, aby bezpečně uchovávala tajný údaj, například identifikátor aplikace pro démonickou aplikaci.

Následující tabulka ukazuje, jak funkce ADAL4J odpovídají novým funkcím MSAL pro Java:

IAccount místo IUser

ADAL4J zpracovával uživatele. I když uživatel představuje jednoho lidského nebo softwarového agenta, může mít jeden nebo více účtů v systému identit Microsoft. Uživatel může mít například několik Microsoft Entra ID, Azure AD B2C nebo Microsoft osobních účtů.

MSAL pro Java definuje koncept účtu prostřednictvím IAccount rozhraní. Jedná se o zásadní změnu z ADAL4J. Zachycuje skutečnost, že stejný uživatel může mít několik účtů a možná i v různých adresářích Microsoft Entra. MSAL pro Java poskytuje lepší informace ve scénářích hostů, protože jsou k dispozici informace o domovském účtu.

Trvalost mezipaměti

ADAL4J neměl podporu pro mezipaměť tokenů. MSAL pro Java přidá mezipaměť tokenů, která zjednodušuje správu životnosti tokenů tím, že automaticky aktualizuje tokeny s vypršenou platností, pokud je to možné, a zabraňuje zbytečným výzvám, aby uživatel zadal přihlašovací údaje, pokud je to možné.

Společná autorita

Pokud v1.0 použijete autorituhttps://login.microsoftonline.com/common, můžou se uživatelé přihlásit pomocí libovolného účtu Microsoft Entra (pro jakoukoli organizaci).

Pokud autoritu https://login.microsoftonline.com/common používáte ve verzi 2.0, můžou se uživatelé přihlásit pomocí libovolné Microsoft Entra organizace nebo dokonce pomocí Microsoft osobního účtu (MSA). V MSAL pro Java, pokud chcete omezit přihlášení k libovolnému Microsoft Entra účtu, použijte autoritu https://login.microsoftonline.com/organizations (což je stejné chování jako u ADAL4J). Pokud chcete zadat autoritu authority , nastavte parametr v PublicClientApplication.Builder metodě při vytvoření instance PublicClientApplication třídy.

Tokeny v1.0 a v2.0

Koncový bod v1.0 (používaný ADAL) generuje pouze tokeny v1.0.

Koncový bod v2.0 (používaný službou MSAL) může generovat tokeny v1.0 a v2.0. Vlastnost manifestu aplikace webového rozhraní API umožňuje vývojářům zvolit, která verze tokenu je přijata. Viz accessTokenAcceptedVersion v referenční dokumentaci k manifestu aplikace.

Další informace o tokenech v1.0 a v2.0 naleznete v článku Přístupové tokeny Microsoft Entra.

Migrace ADAL na MSAL

V ADAL4J byly vystaveny obnovovací tokeny, což vývojářům umožnilo je ukládat do mezipaměti. Pak by použili AcquireTokenByRefreshToken() k povolení řešení, jako je implementace dlouhotrvajících služeb, které aktualizují řídicí panely jménem uživatele, když už uživatel není připojený.

MsAL pro Java nezpřístupňuje obnovovací tokeny z bezpečnostních důvodů. Místo toho msAL zpracovává obnovovací tokeny za vás.

MSAL pro Java má rozhraní API, které umožňuje migrovat obnovovací tokeny získané pomocí ADAL4J do ClientApplication: RefreshTokenParameters. Pomocí této metody můžete zadat dříve použitý token pro obnovení spolu s jakýmikoli rozsahy (prostředky), které požadujete. Obnovovací token se vymění za nový a uloží se do mezipaměti pro použití vaší aplikací.

Následující fragment kódu ukazuje jednoduchý fragment kódu migrace v důvěrné klientské aplikaci:

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 vrací přístupový token a ID token, zatímco váš nový token pro obnovení je uložen v mezipaměti. Aplikace nyní bude obsahovat také IAccount:

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

Pokud chcete použít tokeny, které jsou teď v mezipaměti, zavolejte:

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