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

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

Fark vurguları

ADAL, Azure AD v1.0 uç noktasıyla çalışır. Microsoft Authentication Library (MSAL), daha önce Azure AD v2.0 uç noktası olarak bilinen Microsoft kimlik platformu ile çalışır. Microsoft kimlik platformu, Azure AD v1.0'dan farklıdır:

Destekler:

  • Kuruluş Kimliği (Microsoft Entra ID)

  • Outlook.com, Xbox Live gibi kuruluş dışı kimlikler

  • (yalnızca Azure AD B2C) Google, Facebook, X ve Amazon ile federasyonlu oturum açma

  • Standartların uyumlu olup olmadığını:

    • OAuth v2.0
    • OpenID Connect (OIDC)

MSAL genel API'si aşağıdakiler dahil olmak üzere önemli değişiklikler sunar:

  • Belirteçlere erişmek için yeni bir model:
    • ADAL, sunucuyu temsil eden AuthenticationContext aracılığıyla belirteçlere erişim sağlar. MSAL, istemciyi temsil eden PublicClientApplication aracılığıyla belirteçlere erişim sağlar. İstemci geliştiricilerin etkileşim kurmaları gereken her Yetki için yeni bir PublicClientApplication örneği oluşturmaları gerekmez. Yalnızca bir PublicClientApplication yapılandırma gereklidir.
    • Kaynak tanımlayıcılarına ek olarak kapsamları kullanarak erişim belirteçleri isteme desteği.
    • Artımlı onay desteği. Geliştiriciler, kullanıcı uygulamada giderek daha fazla işleve eriştikçe, uygulama kaydı sırasında dahil edilmemiş olanlar da dahil olmak üzere ek izin kapsamları isteyebilir.
    • Otoriteler artık çalışma zamanında doğrulanmamaktadır. Bunun yerine geliştirici, geliştirme sırasında 'bilinen yetkililerin' listesini bildirir.
  • Belirteç API'sinde yapılan değişiklikler:
    • ADAL'da AcquireToken() önce sessiz bir istekte bulunur. Bu başarısız olursa etkileşimli bir istekte bulunur. Bu davranış, bazı geliştiricilerin yalnızca AcquireTokenöğesine güvenmesine neden oldu ve bu da kullanıcının bazen beklenmedik bir şekilde kimlik bilgileri istemesine neden oldu. MSAL, kullanıcıya ne zaman bir kullanıcı arabirimi istemi gösterileceği konusunda geliştiricilerin bilinçli davranmasını gerektirir.
      • AcquireTokenSilent her zaman başarılı veya başarısız olan sessiz bir istekle sonuç verir.
      • AcquireToken her zaman kullanıcıya kullanıcı arayüzü üzerinden istem gösteren bir istekle sonuçlanır.
  • MSAL, varsayılan tarayıcıdan veya ekli web görünümünden oturum açmayı destekler:
    • Varsayılan olarak, cihazdaki varsayılan tarayıcı kullanılır. Bu, MSAL'nin bir veya daha fazla oturum açmış hesapta zaten mevcut olabilecek kimlik doğrulama durumunu (tanımlama bilgileri) kullanmasına olanak tanır. Kimlik doğrulama durumu yoksa, MSAL aracılığıyla yetkilendirme sırasında kimlik doğrulaması, aynı tarayıcıda kullanılacak diğer web uygulamalarının yararına oluşturulan kimlik doğrulama durumu (tanımlama bilgileri) ile sonuçlanır.
  • Yeni özel durum modeli:
    • Özel durumlar, oluşan hata türünü ve geliştiricinin sorunu çözmek için yapması gerekenleri daha net bir şekilde tanımlar.
  • MSAL, AcquireToken ve AcquireTokenSilent çağrıları için parametre nesnelerini destekler.
  • MSAL aşağıdakiler için bildirim temelli yapılandırmayı destekler:
    • İstemci Kimliği, Yeniden Yönlendirme URI'si.
    • Katıştırılmış ve Varsayılan Tarayıcı karşılaştırması
    • Yetkili
    • Okuma ve bağlantı zaman aşımı gibi HTTP ayarları

Uygulama kaydınız ve MSAL'ye geçişiniz

MSAL kullanmak için mevcut uygulama kaydınızı değiştirmeniz gerekmez. Artımlı/aşamalı onaydan yararlanmak istiyorsanız, artımlı olarak istemek istediğiniz belirli kapsamları belirlemek için kaydı gözden geçirmeniz gerekebilir. Kapsamlar ve artımlı onay hakkında daha fazla bilgi aşağıdadır.

Portaldaki uygulama kaydınızda bir API izinleri sekmesi görürsünüz. Bu, uygulamanızın şu anda erişim istemek üzere yapılandırıldığı API'lerin ve izinlerin (kapsamların) listesini sağlar. Ayrıca, her API izniyle ilişkili kapsam adlarının listesini de gösterir.

ADAL ve Azure AD v1.0 uç noktası ile, ilk kullanımda sahip oldukları kaynaklara kullanıcı onayı verildi. MSAL ve Microsoft kimlik platformu ile onay artımlı olarak istenebilir. Artımlı onay, kullanıcının yüksek ayrıcalık olarak değerlendirebileceği izinler için yararlıdır veya izin neden gerekli olduğuna ilişkin net bir açıklamayla sağlanmadıysa başka bir şekilde sorulabilir. ADAL'da bu izinler kullanıcının uygulamanızda oturum açmayı bırakmasına neden olmuş olabilir.

İpucu

Kullanıcılarınıza uygulamanızın neden izin gerektiği hakkında ek bağlam sağlamak için artımlı onay kullanın.

Kuruluş yöneticileri, kuruluşunuzun tüm üyeleri adına uygulamanızın gerektirdiği izinleri onaylayabilir. Bazı kuruluşlar yalnızca yöneticilerin uygulamalara onay vermesine izin verir. Yönetici onayı, uygulama kaydınıza uygulamanız tarafından kullanılan tüm API izinlerini ve kapsamlarını eklemenizi gerektirir.

İpucu

Uygulama kaydınıza dahil olmayan bir şey için MSAL kullanarak kapsam isteğinde bulunabilseniz de, uygulama kaydınızı bir kullanıcının izin verebileceği tüm kaynakları ve kapsamları içerecek şekilde güncelleştirmenizi öneririz.

Kaynak kimliklerinden kapsamlara geçiş

İlk kullanımdaki tüm izinler için kimlik doğrulaması ve yetkilendirme isteme

Şu anda ADAL kullanıyorsanız ve artımlı onay kullanmanız gerekmiyorsa, MSAL kullanmaya başlamanın en basit yolu yeni acquireToken nesneyi kullanarak istekte AcquireTokenParameter bulunmak ve kaynak kimliği değerini ayarlamaktır.

Caution

Hem kapsamları hem de kaynak kimliğini ayarlamak mümkün değildir. Her ikisini de ayarlamaya çalışmak bir IllegalArgumentExceptionile sonuçlanır.

Bu, alışık olduğunuz v1 davranışının aynısıyla sonuçlanır. Uygulama kaydınızda istenen tüm izinler ilk etkileşimleri sırasında kullanıcıdan istenir.

Kimlik doğrulaması yapın ve yalnızca gerektiğinde izin isteyin

Artımlı onaydan yararlanmak için, uygulamanızın uygulama kaydınızdan kullandığı izinlerin (kapsamların) listesini oluşturun ve bunları aşağıdakilere göre iki liste halinde düzenleyin:

  • Kullanıcının oturum açma sırasında uygulamanızla ilk etkileşimi sırasında istemek istediğiniz kapsamlar.
  • Uygulamanızın önemli bir özelliğiyle ilişkili olan ve kullanıcıya açıklamanız gereken izinler.

Kapsamları düzenledikten sonra, her listeyi belirteç istemek istediğiniz kaynağa (API) göre düzenleyin. Kullanıcının aynı anda yetkilendirmesini istediğiniz diğer kapsamların yanı sıra.

MSAL'ye isteğinizi yapmak için kullanılan parameters nesnesi aşağıdakileri destekler:

  • Scope: Yetkilendirme talep etmek ve erişim belirteci almak istediğiniz kapsamların listesi.
  • ExtraScopesToConsent: Başka bir kaynak için erişim belirteci isterken yetkilendirme istemek istediğiniz kapsamların ek listesi. Bu kapsam listesi, kullanıcıdan yetki istemeniz gereken sayıyı en aza indirmenize olanak tanır. Bu da daha az kullanıcı yetkilendirmesi veya onay istemleri anlamına gelir.

AuthenticationContext'ten PublicClientApplications'a geçiş

PublicClientApplication Oluşturma

MSAL’i kullandığınızda bir PublicClientApplication örneğini oluşturursunuz. Bu nesne, uygulama kimliğinizi modeller ve bir veya daha fazla yetkiliye istekte bulunmak için kullanılır. Bu nesneyle istemci kimliğinizi, yeniden yönlendirme URI'nizi, varsayılan authority'nizi, cihaz tarayıcısının mı yoksa gömülü web görünümünün mü kullanılacağını, günlükleme düzeyini ve daha fazlasını yapılandıracaksınız.

Dosya olarak sağladığınız veya APK'nızın içinde kaynak olarak depoladığınız JSON ile bu nesneyi bildirimli olarak yapılandırabilirsiniz.

Bu nesne bir singleton olmasa da, hem etkileşimli hem de sessiz istekler için dahili olarak paylaşılan Executors kullanır.

İşletmeden İşletmeye

ADAL'de, erişim belirteci talep ettiğiniz her kuruluş, AuthenticationContext öğesinin ayrı bir örneğini gerektirir. MSAL'de bu artık bir gereksinim değildir. Sessiz veya etkileşimli isteğinizin bir parçası olarak belirteç istemek istediğiniz yetkiliyi belirtebilirsiniz.

Otorite doğrulamasından bilinen otoritelere geçiş

MSAL'nin, yetkili doğrulamasını etkinleştirmek veya devre dışı bırakmak için bir bayrağı yoktur. Yetkili doğrulama, ADAL'da ve MSAL'nin ilk sürümlerinde kodunuzun kötü amaçlı olabilecek bir yetkiliden belirteç istemesini engelleyen bir özelliktir. MSAL artık Microsoft bilinen yetkililerin listesini alır ve bu listeyi yapılandırmanızda belirttiğiniz yetkililerle birleştirir.

İpucu

Azure İşletmeden Müşteriye (B2C) kullanıcısıysanız, bu artık yetkili doğrulamayı devre dışı bırakmanız gerekmediğini gösterir. Bunun yerine, desteklenen Azure AD B2C ilkelerinizin her birini MSAL yapılandırmanıza yetkili olarak ekleyin. 1 Mayıs 2025 tarihinden itibaren Azure AD B2C'nin artık yeni müşteriler tarafından satın alınamayacak olduğunu lütfen unutmayın. Daha fazla bilgi edinmek için SSS bölümünde Azure AD B2C hala satın alınabilir mi? bölümüne bakın.

Microsoft tarafından bilinmeyen ve yapılandırmanıza dahil olmayan bir yetkiliyi kullanmaya çalışırsanız, UnknownAuthorityException alırsınız.

Logging

Artık günlüğe kaydetmeyi yapılandırmanızın bir parçası olarak bildirimli olarak yapılandırabilirsiniz, örneğin:

"logging": {
  "pii_enabled": false,
  "log_level": "WARNING",
  "logcat_enabled": true
}

UserInfo'dan Hesaba Geçiş

ADAL'de, AuthenticationResult kimliği doğrulanmış hesap hakkındaki bilgileri almak için kullanılan bir UserInfo nesne sağlar. bir insan veya yazılım aracısı anlamına gelen "kullanıcı" terimi, bazı uygulamaların birden çok hesabı olan tek bir kullanıcıyı (ister bir insan ister yazılım aracısı) desteklediğini bildirmeyi zorlaştıracak şekilde uygulandı.

Bir banka hesabı düşünün. Birden fazla finans kurumunda birden fazla hesabınız olabilir. Bir hesabı açtığınızda, size (kullanıcıya) her hesap için bakiyenize, fatura ödemelerinize vb. erişmek için kullanılan ATM Kartı ve PIN gibi kimlik bilgileri verilir. Bu kimlik bilgileri yalnızca bunları veren finans kurumunda kullanılabilir.

Benzer şekilde, finans kurumundaki hesaplar gibi, Microsoft kimlik platformu hesaplara kimlik bilgileri kullanılarak erişilir. Bu kimlik bilgileri ya Microsoft’a kayıtlıdır ya da Microsoft tarafından verilmiştir. Ya da bir kuruluş adına Microsoft tarafından.

bu benzetmede Microsoft kimlik platformu bir finans kurumundan farklı olduğu durumlarda, Microsoft kimlik platformu bir kullanıcının birden çok kişiye ve kuruluşa ait kaynaklara erişmesi için bir hesabı ve ilişkili kimlik bilgilerini kullanmasına olanak tanıyan bir çerçeve sağlamasıdır. Bu, bir banka tarafından verilen bir kartı başka bir finans kurumunda kullanmak gibidir. Bu işe yarar çünkü söz konusu kuruluşların tümü Microsoft kimlik platformu kullanır ve bu da bir hesabın birden çok kuruluşta kullanılmasına olanak tanır. Bir örnek aşağıda verilmiştir:

Sam Contoso.com için çalışır ancak Fabrikam.com ait Azure sanal makineleri yönetir. Sam'in Fabrikam'ın sanal makinelerini yönetmesi için bunlara erişim yetkisine sahip olması gerekir. Bu erişim, Sam'in hesabını Fabrikam.com ekleyip hesabına sanal makinelerle çalışmasına olanak tanıyan bir rol vererek verilebilir. Bu, Azure portalıyla yapılır.

Sam'in Contoso.com hesabının Fabrikam.com üyesi olarak eklenmesi, sam için Fabrikam.com Microsoft Entra ID yeni bir kayıt oluşturulmasına neden olur. Sam'in Microsoft Entra ID'daki kaydı kullanıcı nesnesi olarak bilinir. Bu durumda, bu kullanıcı nesnesi Contoso.com'da Sam'in kullanıcı nesnesine işaret eder. Sam'in Fabrikam kullanıcı nesnesi Sam'in yerel gösterimidir ve Sam ile ilişkili hesap hakkındaki bilgileri Fabrikam.com bağlamında depolamak için kullanılır. Contoso.com'da Sam'in unvanı Kıdemli DevOps Danışmanı'dır. Fabrikam'da Sam'in başlığı Contractor-Sanal Makineler'tir. Contoso.com'da, Sam sanal makineleri yönetmek için sorumlu veya yetkilendirilmemektedir. Fabrikam.com'da tek iş işlevi bu. Ancak Sam’in hâlâ takip etmesi gereken yalnızca tek bir kimlik bilgileri takımı vardır ve bunlar Contoso.com tarafından verilen kimlik bilgileridir.

Başarılı acquireToken bir çağrı yapıldıktan sonra, sonraki IAccount isteklerde kullanılabilecek bir acquireTokenSilent nesneye başvuru görürsünüz.

IMultiTenantAccount

Hesabın temsil edildiği kiracıların her birinde hesapla ilgili claim’lere erişen bir uygulamanız varsa, IAccount nesnelerini IMultiTenantAccount türüne dönüştürebilirsiniz. Bu arabirim, geçerli hesaba göre belirteç isteğinde bulunduğunuz kiracıların her birinde hesaba ait taleplere erişmenizi sağlayan, kiracı kimliğine göre anahtarlanmış bir eşlemesi ITenantProfilessağlar.

ve kök IAccountIMultiTenantAccount dizinindeki talepler her zaman ev kiracısından gelen talepleri içerir. Ev kiracısı içinde henüz bir belirteç isteğinde bulunmadıysanız, bu koleksiyon boş olur.

Diğer değişiklikler

Yeni AuthenticationCallback'i kullanma

// Existing ADAL Interface
public interface AuthenticationCallback<T> {

    /**
     * This will have the token info.
     *
     * @param result returns <T>
     */
    void onSuccess(T result);

    /**
     * Sends error information. This can be user related error or server error.
     * Cancellation error is AuthenticationCancelError.
     *
     * @param exc return {@link Exception}
     */
    void onError(Exception exc);
}

// New Interface for Interactive AcquireToken
public interface AuthenticationCallback {

    /**
     * Authentication finishes successfully.
     *
     * @param authenticationResult {@link IAuthenticationResult} that contains the success response.
     */
    void onSuccess(final IAuthenticationResult authenticationResult);

    /**
     * Error occurs during the authentication.
     *
     * @param exception The {@link MsalException} contains the error code, error message and cause if applicable. The exception
     *                  returned in the callback could be {@link MsalClientException}, {@link MsalServiceException}
     */
    void onError(final MsalException exception);

    /**
     * Will be called if user cancels the flow.
     */
    void onCancel();
}

// New Interface for Silent AcquireToken
public interface SilentAuthenticationCallback {

    /**
     * Authentication finishes successfully.
     *
     * @param authenticationResult {@link IAuthenticationResult} that contains the success response.
     */
    void onSuccess(final IAuthenticationResult authenticationResult);

    /**
     * Error occurs during the authentication.
     *
     * @param exception The {@link MsalException} contains the error code, error message and cause if applicable. The exception
     *                  returned in the callback could be {@link MsalClientException}, {@link MsalServiceException} or
     *                  {@link MsalUiRequiredException}.
     */
    void onError(final MsalException exception);
}

Yeni özel durumlara geçiş

ADAL'de, ADALError enum değerini almak için bir yöntem içeren tek bir özel durum türü vardır: AuthenticationException. MSAL'de özel durum hiyerarşisi vardır ve her birinin kendi ilişkili belirli hata kodları kümesi vardır.

Exception Description
MsalArgumentException Bir veya daha fazla giriş bağımsız değişkeni geçersizse fırlatılır.
MsalClientException Hata istemci tarafındaysa fırlatılır.
MsalDeclinedScopeException Sunucu tarafından istenen kapsamların bir veya daha fazlası reddedilirse fırlatılır.
MsalException MSAL tarafından varsayılan olarak oluşturulan denetlenen özel durum.
MsalIntuneAppProtectionPolicyRequiredException Kaynağın MAMCA koruma ilkesi etkinleştirilmişse oluşturulur.
MsalServiceException Hata sunucu tarafındaysa fırlatılır.
MsalUiRequiredException Belirteç arka planda yenilenemiyorsa fırlatılır.
MsalUserCancelException Kullanıcı kimlik doğrulama akışını iptal ederse fırlatılır.

ADALError to MsalException çevirisi

ADAL'da bu hataları yakalıyorsanız... ... şu MSAL özel durumlarını yakalayın:
Eşdeğer ADALError yok MsalArgumentException
  • ADALError.ANDROIDKEYSTORE_FAILED
  • ADALError.AUTH_FAILED_USER_MISMATCH
  • ADALError.DECRYPTION_FAILED
  • ADALError.DEVELOPER_AUTHORITY_CAN_NOT_BE_VALIDED
  • ADALError.DEVELOPER_AUTHORITY_IS_NOT_VALID_INSTANCE
  • ADALError.DEVELOPER_AUTHORITY_IS_NOT_VALID_URL
  • ADALError.DEVICE_CONNECTION_IS_NOT_AVAILABLE
  • ADALError.DEVICE_NO_SUCH_ALGORITHM
  • ADALError.ENCODING_IS_NOT_SUPPORTED
  • ADALError.ENCRYPTION_ERROR
  • ADALError.IO_EXCEPTION
  • ADALError.JSON_PARSE_ERROR
  • ADALError.NO_NETWORK_CONNECTION_POWER_OPTIMIZATION
  • ADALError.SOCKET_TIMEOUT_EXCEPTION
 MsalClientException
Eşdeğer ADALError yok MsalDeclinedScopeException
  • ADALError.APP_PACKAGE_NAME_NOT_FOUND
  • ADALError.BROKER_APP_VERIFICATION_FAILED
  • ADALError.PACKAGE_NAME_NOT_FOUND
 MsalException
Eşdeğer ADALError yok MsalIntuneAppProtectionPolicyRequiredException
  • ADALError.SERVER_ERROR
  • ADALError.SERVER_INVALID_REQUEST
 MsalServiceException
  • ADALError.AUTH_REFRESH_FAILED_PROMPT_NOT_ALLOWED
 MsalUiRequiredException
Eşdeğer ADALError yok MsalUserCancelException

MSAL Günlüğüne ADAL Günlüğü

// Legacy Interface
    StringBuilder logs = new StringBuilder();
    Logger.getInstance().setExternalLogger(new ILogger() {
            @Override
            public void Log(String tag, String message, String additionalMessage, LogLevel logLevel, ADALError errorCode) {
                logs.append(message).append('\n');
            }
        });

// New interface
  StringBuilder logs = new StringBuilder();
  Logger.getInstance().setExternalLogger(new ILoggerCallback() {
      @Override
      public void log(String tag, Logger.LogLevel logLevel, String message, boolean containsPII) {
          logs.append(message).append('\n');
      }
  });

// New Log Levels:
public enum LogLevel
{
    /**
     * Error level logging.
     */
    ERROR,
    /**
     * Warning level logging.
     */
    WARNING,
    /**
     * Info level logging.
     */
    INFO,
    /**
     * Verbose level logging.
     */
    VERBOSE
}
  • Last updated on