Java için ADAL'dan MSAL'ye geçiş kılavuzu

Bu makalede, Azure Active Directory Kimlik Doğrulama Kitaplığı'nı (ADAL) kullanan bir uygulamayı Microsoft Authentication Library 'a (MSAL) geçirmek için yapmanız gereken değişiklikler vurgulanır.

Java için Microsoft Authentication Library (MSAL4J) ve Java için Azure AD Authentication Library (ADAL4J), Microsoft Entra varlıklarının kimliklerini doğrulamak ve Microsoft Entra ID’den belirteç istemek için kullanılır. Şimdiye kadar çoğu geliştirici, Azure AD Kimlik Doğrulama Kitaplığı (ADAL) kullanarak belirteçler isteyerek iş ve okul hesapları gibi çeşitli kimliklerle kimlik doğrulaması yapmak üzere geliştiriciler için Azure AD (v1.0) ile çalışmıştır.

MSAL aşağıdaki avantajları sunar:

  • Daha yeni Microsoft kimlik platformunu kullandığından, Microsoft Entra kimlikleri, Microsoft hesapları, Azure AD Kurumdan Müşteriye (Azure AD B2C) aracılığıyla sosyal ve yerel hesaplar ve Microsoft Entra Dış Kimlik aracılığıyla sosyal veya yerel müşteri hesapları gibi daha geniş bir Microsoft kimlikleri kümesinde kimlik doğrulaması yapabilirsiniz.
  • Kullanıcılarınız en iyi çoklu oturum açma deneyimini elde eder.
  • Uygulamanız artımlı onayı etkinleştirebilir ve Koşullu Erişim gibi yeni özellikleri destekleyebilir.

Java için MSAL, Microsoft kimlik platformu ile kullanmanızı önerdiğimiz kimlik doğrulama kitaplığıdır. ADAL4J'de yeni özellik uygulanmaz. İleriye dönük tüm çalışmalar MSAL'yi geliştirmeye odaklanmıştır.

MSAL hakkında daha fazla bilgi edinebilir ve Microsoft Authentication Library genel bakışını kullanmaya başlayabilirsiniz.

Kapsamlar, kaynaklar değildir

ADAL4J kaynaklar için belirteçleri alırken, Java için MSAL kapsamlar için belirteçler alır. Java sınıfları için birçok MSAL bir kapsam parametresi gerektirir. Bu parametre, istenen izinleri ve istenen kaynakları bildiren dizelerin listesidir. Örnek kapsamları görmek için Microsoft Graph kapsamlarına bakın.

Uygulamalarınızı ADAL'dan MSAL'ye geçirmenize yardımcı olmak için kaynağa /.default kapsam son ekini ekleyebilirsiniz. Örneğin, kaynak değeri https://graph.microsoft.comiçin eşdeğer kapsam değeri şeklindedir https://graph.microsoft.com/.default. Kaynak URL biçiminde değilse, ancak XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX biçiminde bir kaynak kimliğiyse, kapsam değerini yine de XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default olarak kullanabilirsiniz.

Farklı kapsam türleri hakkında daha fazla ayrıntı için Microsoft kimlik platformu vev1.0 belirteçlerini kabul eden bir Web API'sinin Kapsamları makalelerindeki İzinler ve onay konusuna bakın.

Temel sınıflar

ADAL4J'de AuthenticationContext sınıfı, Bir Yetkili aracılığıyla Güvenlik Belirteci Hizmeti (STS) veya yetkilendirme sunucusuna bağlantınızı temsil eder. Ancak Java için MSAL, istemci uygulamaları çevresinde tasarlanmıştır. İki ayrı sınıf sağlar: PublicClientApplication ve ConfidentialClientApplication istemci uygulamalarını temsil eder. İkincisi, ConfidentialClientApplication, bir arka plan uygulaması için uygulama tanımlayıcısı gibi bir gizli bilgiyi güvenli bir şekilde saklamak üzere tasarlanmış bir uygulamayı temsil eder.

Aşağıdaki tabloda, ADAL4J işlevlerinin Java işlevleri için yeni MSAL ile nasıl eş olduğu gösterilmektedir:

ADAL4J yöntemi MSAL4J yöntemi
acquireToken(Dize kaynağı, ClientCredential kimlik bilgisi, AuthenticationCallback geri çağırma) ClientCredentialParameters
acquireToken(Dize kaynağı, ClientAssertion onaylama, AuthenticationCallback geri çağırma) ClientCredentialParameters
acquireToken(Dize kaynağı, AsymmetricKeyCredential kimlik bilgisi, AuthenticationCallback geri çağırma) ClientCredentialParameters
acquireToken(Dize kaynağı, Dize clientId, Dize kullanıcı adı, Dize parolası, AuthenticationCallback geri çağırma) UserNamePasswordParameters
acquireToken(String resource, String clientId, String username, String password=null, AuthenticationCallback callback) IntegratedWindowsAuthenticationParameters
acquireToken(Dize kaynağı, UserAssertion userAssertion, ClientCredential kimlik bilgisi, AuthenticationCallback geri çağırma) OnBehalfOfParameters
acquireTokenByAuthorizationCode() AuthorizationCodeParameters
acquireDeviceCode() ve acquireTokenByDeviceCode() DeviceCodeFlowParameters
acquireTokenByRefreshToken() SilentParameters

IUser yerine IAccount

ADAL4J kullanıcıları yönetti. Bir kullanıcı tek bir insan veya yazılım aracısını temsil etse de, Microsoft kimlik sisteminde bir veya daha fazla hesabı olabilir. Örneğin, bir kullanıcının birden fazla Microsoft Entra ID, Azure AD B2C veya Microsoft kişisel hesabı olabilir.

Java için MSAL, hesap kavramını IAccount arabirimi üzerinden tanımlar. Bu, ADAL4J'ye kıyasla geriye dönük uyumluluğu bozan bir değişikliktir. Aynı kullanıcının birkaç hesabı olabileceği ve hatta farklı Microsoft Entra dizinlerinde bile olabileceği gerçeğini yakalar. Java için MSAL, ev hesabı bilgileri sağlandığından konuk senaryolarında daha iyi bilgiler sağlar.

Önbellek kalıcılığı

ADAL4J belirteç önbelleği desteğine sahip değildi. Java için MSAL, süresi dolan belirteçleri mümkün olduğunda otomatik olarak yenileyerek ve mümkün olduğunda kullanıcının kimlik bilgilerini sağlamasına yönelik gereksiz istemleri önleyerek belirteç yaşam sürelerini yönetmeyi basitleştirmek için bir belirteç önbelleği ekler.

Ortak Yetkili

v1.0'da, yetkiliyi https://login.microsoftonline.com/common kullanırsanız, kullanıcılar herhangi bir Microsoft Entra hesabıyla (herhangi bir kuruluş için) oturum açabilir.

v2.0'da yetkiliyi https://login.microsoftonline.com/common kullanırsanız, kullanıcılar herhangi bir Microsoft Entra kuruluşuyla, hatta bir Microsoft kişisel hesabıyla (MSA) oturum açabilir. Java için MSAL'de, herhangi bir Microsoft Entra hesabıyla oturum açmayı kısıtlamak istiyorsanız, yetkiliyi https://login.microsoftonline.com/organizations kullanın (ADAL4J ile aynı davranıştır). Bir yetki belirtmek için, PublicClientApplication sınıfını örneklediğinizde PublicClientApplication.Builder yönteminde authority parametresini ayarlayın.

v1.0 ve v2.0 belirteçleri

v1.0 uç noktası (ADAL tarafından kullanılır) yalnızca v1.0 belirteçleri yayar.

v2.0 uç noktası (MSAL tarafından kullanılır) v1.0 ve v2.0 belirteçleri yayar. Web API'sinin uygulama bildiriminin özelliği, geliştiricilerin belirtecin hangi sürümünün kabul edilirse seçmesine olanak tanır. uygulama bildirimi başvuru belgelerinde yer alan accessTokenAcceptedVersion bölümüne bakın.

v1.0 ve v2.0 belirteçleri hakkında daha fazla bilgi için bkz. Microsoft Entra erişim belirteçleri.

ADAL'dan MSAL'ye geçiş

ADAL4J'de yenileme belirteçleri kullanıma sunuldu ve bu sayede geliştiriciler bunları önbelleğe alabilir. Ardından, kullanıcı artık bağlı değilken kullanıcı adına panoları yenileyen uzun süre çalışan hizmetler uygulamak gibi çözümleri mümkün kılmak için AcquireTokenByRefreshToken() kullanırlardı.

Java için MSAL, güvenlik nedeniyle yenileme belirteçlerini kullanıma sunmaz. Bunun yerine, MSAL sizin için erişim belirteçlerini yeniler.

Java için MSAL, ADAL4J ile edinilen yenileme belirteçlerini ClientApplication içine aktarmanıza olanak tanıyan bir API sunar: RefreshTokenParameters. Bu yöntemle, daha önce kullanılan yenileme belirtecini ve istediğiniz kapsamları (kaynakları) sağlayabilirsiniz. Yenileme belirteci yeni bir belirteçle değiştirilir ve uygulamanız tarafından kullanılmak üzere önbelleğe alınır.

Aşağıdaki kod parçacığı, gizli bir istemci uygulamasında basit bir geçiş kodu parçacığını gösterir:

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, yeni yenileme belirteciniz önbellekte depolanırken bir erişim belirteci ve kimlik belirteci döndürür. Uygulama artık bir IAccount de içerecek:

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

Şimdi önbellekte olan belirteçleri kullanmak için şunu çağırın:

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