ADAL–MSAL migrálási útmutató Androidhoz

Ez a cikk azokat a módosításokat emeli ki, amelyek az Azure Active Directory Authentication Libraryt (ADAL) használó alkalmazások a Microsoft Authentication Library (MSAL) használatára való áttelepítéséhez szükséges módosításokat emeli ki.

A különbség kiemelése

Az ADAL az Azure Active Directory 1.0-s végponttal működik. A Microsoft Authentication Library (MSAL) a Microsoft Identitásplatform - korábbi nevén a Azure Active Directory 2.0-s végponttal működik. A Microsoft Identitásplatform abban különbözik Azure Active Directory 1.0-stól, hogy:

Támogatja:

  • Szervezeti identitás (Azure Active Directory)

  • Nem szervezeti identitások, például Outlook.com, Xbox Live stb.

  • (csak Azure AD B2C) Összevont bejelentkezés a Google-nal, a Facebookkal, a Twitteren és az Amazonon

  • A szabványok kompatibilisek a következővel:

    • OAuth v2.0
    • OpenID Csatlakozás (OIDC)

A nyilvános MSAL API fontos változásokat vezet be, többek között a következőket:

  • Új modell a jogkivonatok eléréséhez:
    • Az ADAL a kiszolgálón keresztül biztosít hozzáférést a AuthenticationContext jogkivonatok számára. Az MSAL hozzáférést biztosít a jogkivonatok számára az ügyfélen PublicClientApplication keresztül. Az ügyfélfejlesztőknek nem kell új példányt létrehoznia minden olyan hitelesítésszolgáltatóhoz, PublicClientApplication amelykkel kapcsolatba kell lépniük. Csak egy PublicClientApplication konfiguráció szükséges.
    • Hozzáférési jogkivonatok kérésének támogatása az erőforrás-azonosítók mellett hatókörök használatával.
    • A növekményes hozzájárulás támogatása. A fejlesztők hatókört kérhetnek, amikor a felhasználó egyre több funkcióhoz fér hozzá az alkalmazásban, beleértve azokat is, amelyek nem szerepelnek az alkalmazásregisztráció során.
    • A rendszer futásidőben már nem ellenőrzi a hitelesítéseket. Ehelyett a fejlesztő deklarál egy "ismert hatóság" listáját a fejlesztés során.
  • A Token API változásai:
    • Az ADAL-ban AcquireToken() először csendes kérést ad. Ennek hiányában interaktív kérést ad. Ez a viselkedés azt eredményezte, hogy egyes fejlesztők csak a-t használják, ami miatt a felhasználónak időnként váratlanul meg kell adnia AcquireToken a hitelesítő adatokat. Az MSAL megköveteli, hogy a fejlesztők szándékosak, amikor a felhasználó felhasználói felületi kérést kap.
      • AcquireTokenSilent A mindig olyan csendes kérést ad vissza, amely sikeres vagy sikertelen.
      • AcquireToken A mindig olyan kérést ad vissza, amely felhasználói felületen keresztül kéri a felhasználót.
  • Az MSAL támogatja az alapértelmezett böngészőből vagy beágyazott webes nézetből való bejelentkezést:
    • Alapértelmezés szerint a rendszer az eszköz alapértelmezett böngészőjét használja. Ez lehetővé teszi, hogy az MSAL hitelesítési állapotot (cookie-kat) használjon, amelyek esetleg már jelen vannak egy vagy több bejelentkezett fiókhoz. Ha nincs hitelesítési állapot, az MSAL-hitelesítés során történő hitelesítés hitelesítési állapotot (cookie-kat) hoz létre az ugyanazon böngészőben használt egyéb webalkalmazások számára.
  • Új kivételmodell:
    • A kivételek egyértelműbben határozzák meg a hiba típusát és azt, hogy mit kell tenni a fejlesztőnek a probléma megoldásához.
  • Az MSAL a és a hívás AcquireToken AcquireTokenSilent paraméterobjektumait támogatja.
  • Az MSAL a következő deklaratív konfigurációkat támogatja:
    • Ügyfél-azonosító, Átirányítási URI.
    • Beágyazott és alapértelmezett böngésző
    • Hatóságok
    • HTTP-beállítások, például olvasás és kapcsolati időtúllépés

Az alkalmazás regisztrációja és migrálás az MSAL-be

Az MSAL-hez nem kell módosítania a meglévő alkalmazásregisztrációt. Ha ki szeretné használni a növekményes/progresszív hozzájárulás előnyeit, előfordulhat, hogy át kell vizsgálnia a regisztrációt a növekményesen kérelmezni kívánt hatókörök azonosításához. A hatókörökről és a növekményes hozzájárulásról az alábbi további információk adatokat tartalmaznak.

A portálon az alkalmazásregisztrációban egy API-engedélyek lap látható. Ez felsorolja azokat az API-kat és engedélyeket (hatóköröket), amelyekhez az alkalmazás jelenleg konfigurálva van a hozzáférés igényléséhez. Az egyes API-engedélyekhez társított hatókörnevek listáját is megjeleníti.

Az ADAL és az Azure AD v1-végpont használatával a felhasználó első használatra megadta a saját erőforrásaihoz adott hozzájárulását. Az MSAL és a Microsoft Identitásplatform esetén a jóváhagyás növekményesen kérhető. A növekményes hozzájárulás olyan engedélyekhez hasznos, amelyekhez a felhasználó magas jogosultságot is megfontolhat, vagy ha nincs egyértelmű magyarázata az engedély szükségességére, más módon is felteheti a kérdést. Az ADAL-ban ezek az engedélyek azt eredményezhették, hogy a felhasználó nem jelentkezik be az alkalmazásba.

Tipp

A növekményes hozzájárulással további kontextust nyújthat a felhasználóknak arról, hogy miért van szüksége az alkalmazásnak engedélyre.

A szervezeti rendszergazdák a szervezet összes tagja nevében járulnak hozzá az alkalmazáshoz szükséges engedélyekhez. Egyes szervezetek csak a rendszergazdáknak engedélyezik az alkalmazásokhoz való hozzájárulásukat. A rendszergazdai jóváhagyáshoz bele kell foglalnia az alkalmazás által használt összes API-engedélyt és hatókört az alkalmazásregisztrációba.

Tipp

Annak ellenére, hogy az MSAL használatával kérhet hatókört az alkalmazásregisztrációban nem szereplő dologhoz, javasoljuk, hogy frissítse az alkalmazásregisztrációt úgy, hogy tartalmazza az összes olyan erőforrást és hatókört, amelyekhez a felhasználó engedélyt adhat.

Áttelepítés erőforrás-iról hatókörökre

Hitelesítés és engedélyezés kérése az összes engedélyhez az első használatra

Ha jelenleg az ADAL-t használja, és nem kell növekményes jóváhagyást használnia, az MSAL használatának legegyszerűbb módja, ha az új objektummal kérést indít, és az erőforrás-azonosító értékét adja acquireToken AcquireTokenParameter meg.

Figyelemfelhívás

Nem lehet hatókört és erőforrás-azonosítót is beállítani. Ha mindkettőt megkísérli beállítani, az egy et IllegalArgumentException eredményez.

Ez ugyanazt a v1 viselkedést eredményezi, mint amit Ön használ. Az alkalmazásregisztrációban kért összes engedélyt a rendszer az első interakció során kéri a felhasználótól.

Csak szükség szerint hitelesíti és kéri az engedélyeket

A növekményes hozzájárulás előnyeinek kihasznál érdekében az alkalmazásregisztrációból készítse el az alkalmazás által használt engedélyek (hatókörök) listáját, és rendezze őket két listába a következő alapján:

  • Mely hatókörökre van szükség a bejelentkezés során a felhasználónak az alkalmazással való első interakciója során?
  • Az alkalmazás egy fontos funkcióhoz társított engedélyeket is el kell magyaráznia a felhasználónak.

A hatókörök rendszerezése után rendezze az egyes listában azt az erőforrást (API-t), amelyhez jogkivonatot szeretne kérni. Valamint minden más hatókört, amelyek egyidejűleg való engedélyét is engedélyezni szeretné a felhasználó számára.

A kérés MSAL-hez való igényléshez használt parameters objektum a következőt támogatja:

  • Scope: Azon hatókörök listája, amelyekhez engedélyt szeretne kérni, és amelyekhez hozzáférési jogkivonatot szeretne kapni.
  • ExtraScopesToConsent: Azon hatókörök további listája, amelyekhez engedélyt szeretne kérni egy másik erőforrás hozzáférési jogkivonatának lekérése közben. A hatókörök ezen listája lehetővé teszi, hogy minimálisra csökkentse a felhasználói engedélyezés igénylésének szükséges számát. Ez azt jelenti, hogy kevesebb felhasználói engedélyre vagy hozzájárulásra vonatkozó kérésre van szükség.

Miigrate from AuthenticationContext to PublicClientApplications (Mirate from AuthenticationContext to PublicClientApplications)

A PublicClientApplication megépítése

Az MSAL használata után példányosul egy PublicClientApplication példánya. Ez az objektum modelle az alkalmazásidentitást, és egy vagy több hatóságnak való kérések igénylésére használható. Ezzel az objektummal konfigurálhatja az ügyfélidentitást, az átirányítási URI-t, az alapértelmezett hitelesítésszolgáltatót, az eszközböngészőt és a beágyazott webes nézetet, a naplószintet stb.

Ezt az objektumot deklaratív módon konfigurálhatja JSON-fájllal, amelyet fájlként vagy erőforrásként tárolhat az APK-ban.

Bár ez az objektum nem egyedülálló, belsőleg az interaktív és a csendes kérések számára is Executors megosztott objektumot használ.

Vállalat és vállalkozás

Az ADAL-ban minden olyan szervezetnek, amelytől hozzáférési jogkivonatokat kér, a külön példányára van AuthenticationContext szükség. Az MSAL-ban ez már nem követelmény. A csendes vagy interaktív kérés részeként megadhatja azt a hitelesítésszolgáltatót, amelytől jogkivonatot szeretne kérni.

Áttelepítés hitelesítésszolgáltatói ellenőrzésről ismert hitelesítésszolgáltatóra

Az MSAL nem rendelkezik jelzővel a hitelesítés érvényesítésének engedélyezéséhez vagy letiltásához. A hitelesítés ellenőrzése az ADAL egyik funkciója, és az MSAL korai kiadásában megakadályozza, hogy a kód jogkivonatokat kér egy potenciálisan rosszindulatú hitelesítésszolgáltatótól. Az MSAL lekéri a Microsoft által ismert hatóságlistát, és egyesíti a listát a konfigurációban megadott hatóságokkal.

Tipp

Ha Ön Azure-beli végfelhasználói (B2C-) felhasználó, akkor nem kell letiltania a hitelesítésszolgáltatói ellenőrzést. Ehelyett foglalja bele a támogatott szabályzatok Azure AD B2C MSAL-konfigurációba.

Ha olyan hitelesítést kísérel meg használni, amely nem ismert a Microsoft számára, és nem szerepel a konfigurációjában, a következőt fogja kapni: UnknownAuthorityException .

Naplózás

Most már konfigurálhatja a naplózást deklaratív módon a konfiguráció részeként, a következő módon:

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

Mirate from UserInfo to Account

Az ADAL-ban a egy objektumot biztosít a hitelesített fiókkal kapcsolatos AuthenticationResult UserInfo információk lekéréséhez. A "felhasználó" kifejezés, amely emberi vagy szoftverügynökként jelent meg, olyan módon lett alkalmazva, amely megnehezítte annak kommunikáltát, hogy egyes alkalmazások egyetlen felhasználót (akár emberi, akár szoftverügynök) támogatnak, amely több fiókkal rendelkezik.

Vegyük például a bankszámlaszámát. Több fiókkal is lehet egynél több pénzügyi intézetnél. Amikor megnyit egy fiókot, Ön (a felhasználó) olyan hitelesítő adatokat ( például ATM-kártya & PIN-kódot) ad ki, amelyek az egyes fiókok egyenlegének, számlás fizetésének és egyéb adatainak eléréséhez használhatók. Ezek a hitelesítő adatok csak az azokat kibocsátó pénzügyi intézetben használhatók.

Hasonlatból, a pénzügyi intézetek számláihoz hasonlóan a Microsoft Identitásplatform is hitelesítő adatokkal érhetők el. Ezek a hitelesítő adatok regisztrálva vannak a Microsoftnál, vagy a Microsoftnál vannak kibocsátva. Vagy a Microsoft egy szervezet nevében.

Ha a Microsoft Identitásplatform eltér a pénzügyi intézettől, ebben a hasonlatban az, hogy az Microsoft Identitásplatform olyan keretrendszert biztosít, amely lehetővé teszi, hogy a felhasználó egy fiókot és a hozzá tartozó hitelesítő adatokat használva hozzáférjen a több személyhez és szervezethez tartozó erőforrásokhoz. Ez olyan, mintha egy bank, egy másik pénzügyi intézet által kibocsátott kártyát használnál. Ez azért működik, mert az összes szóban forgó szervezet a Microsoft Identitásplatform, amely lehetővé teszi egy fiók több szervezetben való használatát. Bemutatunk egy példát:

Sam a Contoso.com működik, de a virtuális gépekhez tartozó Azure-beli Fabrikam.com. Ahhoz, hogy Sándor felügyelni tudja a Fabrikam virtuális gépeit, jogosultnak kell lennie a hozzáférésre. Ez a hozzáférés Úgy adható meg, hogy Hozzáadja Sam fiókját a Fabrikam.com, és olyan szerepkört ad a fiókjának, amely lehetővé teszi számára a virtuális gépekkel való munkát. Ez a következővel történik: Azure Portal.

Ha Sam Contoso.com fiókját a Fabrikam.com tagjaként adja hozzá, az új rekordot hozna létre a Fabrikam.com Azure Active Directory Sam számára. Sam rekordját a Azure Active Directory felhasználói objektumnak nevezik. Ebben az esetben ez a felhasználói objektum Sam felhasználói objektumra mutatna a Contoso.com. Sam Fabrikam felhasználói objektuma a Sam helyi reprezentációja, amely a Sam-hez társított fiókkal kapcsolatos információk tárolására használható a Fabrikam.com. Ebben Contoso.com Sam címe Vezető DevOps Consultant. A Fabrikamban Sam címe a Machines Contractor-Virtual van. Ebben Contoso.com Sam nem felelős a virtuális gépek kezeléséért, és nem is jogosult rá. Ebben Fabrikam.com ez az egyetlen feladat-függvénye. Sam azonban továbbra is csak egy hitelesítőadat-készletet követ, amelyek a felhasználó által kiadott Contoso.com.

A sikeres hívás után egy hivatkozás fog látni egy objektumra, amely a későbbi acquireToken IAccount kérésekben acquireTokenSilent használható.

IMultiTenantAccount

Ha rendelkezik olyan alkalmazással, amely hozzáfér egy fiók jogcíméhez minden olyan bérlőről, amelyben a fiók található, objektumokat a következőre lehet IAccount átvetni: IMultiTenantAccount . Ez az interfész a térképét biztosítja, amely bérlőazonosító alapján van kulcsokkal, így hozzáférhet a fiókhoz tartozó jogcímekhez minden olyan bérlőben, amelytől jogkivonatot kért, az aktuális fiókhoz ITenantProfiles viszonyítva.

A és a gyökérkönyvtárában található jogcímek mindig tartalmazzák a saját IAccount IMultiTenantAccount bérlőtől származó jogcímeket. Ha még nem kért jogkivonatot a saját bérlőn belül, ez a gyűjtemény üres lesz.

További változások

Az új AuthenticationCallback használata

// 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);
}

Áttelepítés az új kivételekre

Az ADAL-ban van egy kivételtípus, a, amely tartalmaz egy metódust az enum érték AuthenticationException ADALError leolvasására. Az MSAL-ban a kivételek hierarchiája van, és mindegyikhez saját specifikus hibakódok vannak társítva.

Kivétel Description
MsalArgumentException Akkor ad vissza, ha egy vagy több bemeneti argumentum érvénytelen.
MsalClientException A rendszer akkor ad vissza hibát, ha a hiba ügyféloldali.
MsalDeclinedScopeException Akkor ad vissza, ha a kiszolgáló elutasít egy vagy több kért hatókört.
MsalException Az MSAL által okozott alapértelmezett ellenőrzött kivétel.
MsalIntuneAppProtectionPolicyRequiredException A rendszer akkor ad vissza, ha az erőforráson engedélyezve van a MAMCA védelmi szabályzat.
MsalServiceException A rendszer a kiszolgálóoldali hiba esetén ad vissza hibát.
MsalUiRequiredException Akkor ad vissza, ha a jogkivonat nem frissítható csendesen.
MsalUserCancelException A rendszer eldobja, ha a felhasználó megszakította a hitelesítési folyamatot.

ADALErrorból MsalException fordításba

Ha ezeket a hibákat az ADAL-ban... ... az alábbi MSAL-kivételeket kapjuk:
Nincs egyenértékű ADALError 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
Nincs egyenértékű ADALError MsalDeclinedScopeException
  • ADALError.APP_PACKAGE_NAME_NOT_FOUND
  • ADALError.BROKER_APP_VERIFICATION_FAILED
  • ADALError.PACKAGE_NAME_NOT_FOUND
MsalException
Nincs egyenértékű ADALError MsalIntuneAppProtectionPolicyRequiredException
  • ADALError.SERVER_ERROR
  • ADALError.SERVER_INVALID_REQUEST
MsalServiceException
  • ADALError.AUTH_REFRESH_FAILED_PROMPT_NOT_ALLOWED
MsalUiRequiredException
Nincs egyenértékű ADALError MsalUserCancelException

ADAL-naplózás MSAL-naplózásba

// 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
}