Share via

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

  • Makale

Bu makalede, Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) kullanmak üzere 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 Kimlik Doğrulama Kitaplığı (MSAL), eski adıyla 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:

Destekledikleri:

  • Kuruluş Kimliği (Microsoft Entra Id)

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

  • (yalnızca Azure AD B2C) Google, Facebook, Twitter ve Amazon ile federasyon oturumu açma

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

    • OAuth v2.0
    • OpenID Bağlan (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 aracılığıyla belirteçlere AuthenticationContexterişim sağlar. MSAL, istemcisini PublicClientApplicationtemsil eden aracılığıyla belirteçlere erişim sağlar. İstemci geliştiricilerin etkileşim kurmaları gereken her Yetkili için yeni PublicClientApplication bir örnek 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 uygulama kaydı sırasında dahil olmayanlar da dahil olmak üzere daha fazla işleve eriştiğinde kapsamlar isteyebilir.
    • Yetkililer artık çalışma zamanında doğrulanmaz. Bunun yerine geliştirici, geliştirme sırasında 'bilinen yetkililerin' listesini bildirir.
  • Belirteç API'sinde yapılan değişiklikler:
    • ADAL'da ilk AcquireToken() olarak 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, geliştiricilerin kullanıcı arabirimi istemi aldığında kasıtlı olarak kullanılmasını gerektirir.
      • AcquireTokenSilent her zaman başarılı veya başarısız olan sessiz bir istekle sonuç verir.
      • AcquireToken her zaman kullanıcı arabirimi aracılığıyla kullanıcıya soran bir istekle sonuçilir.
  • 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, ve AcquireTokenSilent çağrıları için AcquireToken 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ı dahil etmenizi 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 AcquireTokenParameter nesneyi kullanarak istekte acquireToken bulunmak ve kaynak kimliği değerini ayarlamaktır.

Dikkat

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, kullandığınız aynı v1 davranışına neden olur. Uygulama kaydınızda istenen tüm izinler ilk etkileşimleri sırasında kullanıcıdan istenir.

Kimlik doğrulaması ve yalnızca gerektiğinde izin isteme

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: Erişim belirteci için yetkilendirme istemek ve 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ı yetkilendirmesi istemek için gereken sayısını 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 kullandığınızda bir örneği oluşturursunuz PublicClientApplication. 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 yetkilinizi, cihaz tarayıcısının kullanılıp kullanılmayacağını ve ekli web görünümünün, günlük düzeyinin 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 tekil olmasa da, hem etkileşimli hem de sessiz istekler için dahili olarak paylaşılan Executors kullanır.

İşletmeden İşletmeye

ADAL'da, erişim belirteçleri istediğiniz her kuruluş için ayrı bir örneği AuthenticationContextgerekir. 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.

Yetkili doğrulamadan bilinen yetkililere 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 tarafından bilinen bir yetkili 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.

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

Günlük Kaydı

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.

Benzetmeyle, finans kurumundaki hesaplar gibi, Microsoft kimlik platformu hesaplara kimlik bilgileri kullanılarak erişilir. Bu kimlik bilgileri Microsoft'a kaydedilir veya microsoft tarafından verilir. Veya microsoft tarafından bir kuruluş adına.

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şmek için bir hesap 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 makinelerini 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ı ile yapılır.

Sam'in Contoso.com hesabının Fabrikam.com üyesi olarak eklenmesi, Fabrikam.com'nin Sam için Microsoft Entra Kimliği'nde yeni bir kayıt oluşturulmasına neden olur. Sam'in Microsoft Entra Id'deki 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 unvanı Contractor-Sanal Makineler'dir. Contoso.com'da, Sam sanal makineleri yönetmek için sorumlu veya yetkilendirilmemektedir. Fabrikam.com'da tek iş işlevi bu. Ancak Sam'in izleyebileceğiniz yalnızca bir kimlik bilgisi kümesi vardır ve bunlar Contoso.com tarafından verilen kimlik bilgileridir.

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

IMultiTenantAccount

Hesabın temsilildiği kiracıların her birinden bir hesap hakkındaki taleplere erişen bir uygulamanız varsa, nesnesine IMultiTenantAccountyayınlayabilirsinizIAccount. 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, sabit listesi değerini almak ADALError için bir yöntem içeren bir özel durum AuthenticationExceptiontürü vardır. MSAL'de özel durum hiyerarşisi vardır ve her birinin kendi ilişkili belirli hata kodları kümesi vardır.

Özel durum Açıklama
MsalArgumentException Bir veya daha fazla giriş bağımsız değişkeni geçersizse oluşturulur.
MsalClientException Hata istemci tarafıysa oluşturulur.
MsalDeclinedScopeException İstenen bir veya daha fazla kapsam sunucu tarafından reddedildiyse oluşturulur.
MsalException MSAL tarafından varsayılan olarak denetlenen özel durum oluştu.
MsalIntuneAppProtectionPolicyRequiredException Kaynağın MAMCA koruma ilkesi etkinleştirilmişse oluşturulur.
MsalServiceException Hata sunucu tarafıysa oluşturulur.
MsalUiRequiredException Belirteç sessizce yenilenemiyorsa oluşturulur.
MsalUserCancelException Kullanıcı kimlik doğrulama akışını iptal ederse oluşturulur.

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
}