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

  • Cikk

Ez a cikk a Microsoft Authentication Library (MSAL) használatához az Azure Active Directory Authentication Libraryt (ADAL) használó alkalmazások migrálásához szükséges módosításokat ismerteti.

Különbségi kiemelések

Az ADAL az Azure AD 1.0-s verziójú végpontjával működik. A Microsoft Authentication Library (MSAL) a Microsoft Identitásplatform, korábbi nevén az Azure AD v2.0 végponttal működik. A Microsoft Identitásplatform abban különbözik az Azure AD 1.0-s verziótól, hogy:

A következőket támogatja:

  • Szervezeti identitás (Microsoft Entra-azonosító)

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

  • (csak Azure AD B2C) Összevont bejelentkezés a Google, a Facebook, a Twitter és az Amazon használatával

  • Kompatibilis-e a szabványok a következőkkel:

    • OAuth 2.0-s verzió
    • OpenID Csatlakozás (OIDC)

Az MSAL nyilvános 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 hozzáférést biztosít a jogkivonatokhoz a AuthenticationContextkiszolgálót jelképező kiszolgálón keresztül. Az MSAL hozzáférést biztosít a jogkivonatokhoz az PublicClientApplicationügyfelet jelképező felületen keresztül. Az ügyfélfejlesztőknek nem kell új PublicClientApplication példányt létrehozniuk minden olyan szolgáltató számára, akivel kapcsolatba kell lépniük. Csak egy PublicClientApplication konfigurációra van szükség.
    • A hozzáférési jogkivonatok kérésének támogatása hatókörökkel az erőforrás-azonosítók mellett.
    • Növekményes hozzájárulás támogatása. A fejlesztők hatóköröket kérhetnek, mivel a felhasználó egyre több funkciót ér el az alkalmazásban, beleértve azokat is, amelyek nem szerepelnek az alkalmazásregisztráció során.
    • A hatóságokat a rendszer már nem ellenőrzi futásidőben. Ehelyett a fejlesztő az "ismert hatóságok" listáját deklarálja a fejlesztés során.
  • Token API-módosítások:
    • Az ADAL-ban AcquireToken() először csendes kérelmet kell intézni. Ennek hiányában interaktív kérést küld. Ez a viselkedés azt eredményezte, hogy egyes fejlesztők csak a felhasználóra AcquireTokentámaszkodtak, ezért a felhasználó időnként váratlanul hitelesítő adatokat kér. Az MSAL megköveteli, hogy a fejlesztők szándékosan értesülnek arról, amikor a felhasználó felhasználói felületi kérést kap.
      • AcquireTokenSilent mindig olyan csendes kérést eredményez, amely sikeres vagy sikertelen.
      • AcquireToken mindig olyan kérést eredményez, 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 az eszköz alapértelmezett böngészője van használatban. Ez lehetővé teszi, hogy az MSAL olyan hitelesítési állapotot (cookie-kat) használjon, amelyek egy vagy több bejelentkezett fiók esetében már jelen lehetnek. Ha nincs hitelesítési állapot, az MSAL-en keresztüli hitelesítés során a hitelesítési állapot (cookie-k) létrejönnek más, ugyanabban a böngészőben használt webalkalmazások javára.
  • Új kivételmodell:
    • A kivételek pontosabban meghatározzák a hiba típusát és azt, hogy a fejlesztőnek mit kell tennie a megoldásához.
  • Az MSAL támogatja a paraméterobjektumokat és AcquireTokenSilent a AcquireToken hívásokat.
  • Az MSAL támogatja a deklaratív konfigurációt a következő célokra:
    • Ügyfélazonosí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 kapcsolat időtúllépése

Alkalmazásregisztráció és migrálás MSAL-be

Az MSAL használatához 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 tekintenie a regisztrációt, hogy azonosítsa azokat a hatóköröket, amelyeket növekményesen szeretne kérni. További információ a hatókörökről és a növekményes hozzájárulásról.

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

Az ADAL és az Azure AD 1.0-s verziójú végpontja esetén a felhasználó először engedélyezte a saját erőforrásait. Az MSAL és a Microsoft Identitásplatform esetén a hozzájárulást növekményesen lehet kérni. A növekményes hozzájárulás olyan engedélyek esetében hasznos, amelyeket a felhasználó magas jogosultságnak tekinthet, vagy ha nem adja meg egyértelmű magyarázattal, hogy miért van szükség az engedélyre. Az ADAL-ban előfordulhat, hogy ezek az engedélyek azt eredményezték, hogy a felhasználó abbahagyta az alkalmazásba való bejelentkezést.

Tipp.

Növekményes hozzájárulással további kontextust biztosíthat a felhasználóknak arról, hogy az alkalmazásnak miért van szüksége engedélyre.

A szervezet rendszergazdái jóváhagyhatják az alkalmazás által igényelt engedélyeket a szervezet összes tagjának nevében. Egyes szervezetek csak a rendszergazdáknak engedélyezik az alkalmazásokhoz való hozzájárulást. Rendszergazda hozzájárulás megköveteli, hogy az alkalmazás által használt összes API-engedélyt és hatókört belefoglalja az alkalmazásregisztrációba.

Tipp.

Annak ellenére, hogy MSAL használatával kérhet hatókört az alkalmazásregisztrációban nem szereplő adatokhoz, javasoljuk, hogy frissítse az alkalmazásregisztrációt úgy, hogy az tartalmazza azokat az erőforrásokat és hatóköröket, amelyekhez a felhasználó valaha engedélyt adhatna.

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

Hitelesítés és engedélyezés kérése az első használathoz szükséges összes engedélyhez

Ha jelenleg az ADAL-t használja, és nem kell növekményes hozzájárulást használnia, az MSAL használatának legegyszerűbb módja az, ha kérést acquireToken küld az új AcquireTokenParameter objektummal, és beállítja az erőforrás-azonosító értékét.

Figyelemfelhívás

A hatókörök és az erőforrás-azonosítók nem állíthatók be. Ha mindkettőt megkísérli beállítani, az egy IllegalArgumentException.

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

Csak szükség szerint hitelesítse és kérje le az engedélyeket

A növekményes hozzájárulás előnyeinek kihasználásához készítsen listát az alkalmazás által az alkalmazásregisztrációból használt engedélyekről (hatókörökről), és rendezze őket két listába az alábbiak alapján:

  • Mely hatóköröket szeretné kérelmezni a felhasználónak a bejelentkezés során az alkalmazással való első interakciója során.
  • Az alkalmazás egy fontos funkciójához társított engedélyek, amelyeket a felhasználónak is el kell magyaráznia.

Miután rendszerezte a hatóköröket, rendszerezze az egyes listákat, hogy melyik erőforrás (API) alapján szeretne jogkivonatot kérni. Csakúgy, mint minden más hatókört, amelyet a felhasználónak egyidejűleg engedélyezni szeretne.

A kérelem MSAL-hez való kéréséhez használt paraméterobjektum a következőket támogatja:

  • Scope: Azon hatókörök listája, amelyekhez hozzáférési jogkivonatot szeretne kérni és megkapni.
  • ExtraScopesToConsent: Azoknak a hatóköröknek a további listája, amelyek engedélyezését szeretné kérni, amíg hozzáférési jogkivonatot kér egy másik erőforráshoz. Ez a hatókörlista lehetővé teszi, hogy a lehető legkevesebb alkalommal kérjen felhasználói engedélyt. Ez azt jelenti, hogy kevesebb felhasználói engedélyezésre vagy hozzájárulásra vonatkozó kérés van.

Migrálás Az AuthenticationContextből a PublicClientApplications szolgáltatásba

PublicClientApplication létrehozása

Az MSAL használatakor példányosít egy PublicClientApplication. Ez az objektum modellozza az alkalmazás identitását, és egy vagy több hatósághoz irányuló kérések igénylésére szolgál. Ezzel az objektummal konfigurálhatja az ügyfélidentitást, az átirányítási URI-t, az alapértelmezett szolgá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-val, amelyet fájlként vagy erőforrásként tárolhat az APK-ban.

Bár ez az objektum nem önálló, belsőleg az interaktív és a csendes kérelmekhez is használ megosztottat Executors .

Vállalati verzió

Az ADAL-ban minden olyan szervezetnek, amelytől hozzáférési jogkivonatokat kér, külön példányt igényel a AuthenticationContext. Az MSAL-ben ez már nem követelmény. Megadhatja azt a szolgáltatót, amelytől jogkivonatot szeretne kérni a csendes vagy interaktív kérés részeként.

Migrálás a hitelesítésről az ismert hatóságokra

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

Tipp.

Ha Ön Az Azure Business to Consumer (B2C) felhasználója, ez azt jelenti, hogy többé nem kell letiltania a hatóság érvényesítését. Ehelyett vegye fel az összes támogatott Azure AD B2C-szabályzatot az MSAL-konfigurációban szereplő hatóságok közé.

Ha olyan szolgáltatót próbál használni, amely nem ismert a Microsoft számára, és nem szerepel a konfigurációban, egy UnknownAuthorityException.

Naplózás

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

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

Migrálás UserInfo-ból fiókba

Az ADAL-ban az AuthenticationResult objektum a UserInfo hitelesített fiók adatainak lekérésére szolgál. A "felhasználó" kifejezést, amely emberi vagy szoftverügynököt jelentett, olyan módon alkalmazták, amely megnehezítette annak közlését, hogy egyes alkalmazások egyetlen felhasználót támogatnak (akár emberi, akár szoftverügynök), amely több fiókkal rendelkezik.

Vegye figyelembe a bankszámlát. Több pénzügyi intézménynél is rendelkezhet egynél több számlával. Amikor megnyit egy fiókot, Ön (a felhasználó) hitelesítő adatokat, például egy ATM Card > PIN-kódot ad ki, amely az egyes fiókok egyenlegéhez, számláihoz stb. való hozzáférésre szolgál. Ezek a hitelesítő adatok csak az őket kibocsátó pénzügyi intézménynél használhatók.

Analógiával, például egy pénzügyi intézmény számláihoz hasonlóan a Microsoft Identitásplatform lévő fiókok hitelesítő adatokkal érhetők el. Ezeket a hitelesítő adatokat a Microsoft regisztrálja vagy kiadja. Vagy a Microsoft egy szervezet nevében.

Ha a Microsoft Identitásplatform eltér egy pénzügyi intézménytől, ebben a hasonlatban az, hogy a Microsoft Identitásplatform olyan keretrendszert biztosít, amely lehetővé teszi a felhasználó számára, hogy egy fiókot és a hozzá tartozó hitelesítő adatokat használjon a több személyhez és szervezethez tartozó erőforrások eléréséhez. Ez olyan, mint egy bank által kibocsátott kártya használata egy másik pénzintézetnél. Ez azért működik, mert az összes érintett szervezet használja a Microsoft Identitásplatform, amely lehetővé teszi, hogy egy fiókot több szervezet is használjon. Példa:

Sam Contoso.com dolgozik, de felügyeli az Fabrikam.com tartozó Azure-beli virtuális gépeket. Ahhoz, hogy Sam felügyelje Fabrikam virtuális gépeit, jogosultnak kell lennie a hozzáférésükre. Ez a hozzáférés úgy biztosítható, hogy Hozzáadja Sam fiókját Fabrikam.com, és olyan szerepkört ad a fiókjának, amely lehetővé teszi számára, hogy a virtuális gépekkel dolgozzon. Ez az Azure Portalon történik.

Sam Contoso.com-fiókjának Fabrikam.com tagjaként való hozzáadása új rekord létrehozását eredményezné Fabrikam.com Sam Microsoft Entra-azonosítójában. Sam rekordja a Microsoft Entra-azonosítóban felhasználói objektumként ismert. Ebben az esetben az adott felhasználói objektum vissza fog mutatni Sam felhasználói objektumára a Contoso.com. Sam Fabrikam felhasználói objektuma Sam helyi ábrázolása, amely a Samhez társított fiók adatainak tárolására szolgál a Fabrikam.com kontextusában. A Contoso.com Sam neve vezető DevOps-tanácsadó. A Fabrikamban Sam címe Contractor-Virtual Machines. A Contoso.com sam nem felelős és nem jogosult sem a virtuális gépek felügyeletére. A Fabrikam.com ez az egyetlen feladatfüggvénye. Sam azonban továbbra is csak egy hitelesítőadat-készlettel rendelkezik, amelyeket nyomon kell követnie, amelyek a Contoso.com által kiadott hitelesítő adatok.

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

IMultiTenantAccount

Ha olyan alkalmazással rendelkezik, amely a fiókhoz tartozó összes bérlőtől hozzáfér egy-egy fiókra vonatkozó jogcímekhez, objektumokat IMultiTenantAccounthelyezhet el IAccount a fiókban. Ez az interfész a bérlőazonosító alapján kulcsolt térképet ITenantProfilesbiztosít, amely lehetővé teszi a fiókhoz tartozó jogcímek elérését az összes olyan bérlőben, amelytől jogkivonatot kért, az aktuális fiókhoz képest.

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

Egyéb 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);
}

Migrálás az új kivételekre

Az ADAL-ban van egy kivételtípus, AuthenticationExceptionamely az enumerálási érték beolvasására ADALError szolgáló metódust is tartalmaz. Az MSAL-ben a kivételek hierarchiája létezik, és mindegyik saját társított konkrét hibakódokkal rendelkezik.

Kivétel Leírás
MsalArgumentException Akkor lesz eldobva, ha egy vagy több bemeneti argumentum érvénytelen.
MsalClientException Akkor jelenik meg, ha a hiba ügyféloldali.
MsalDeclinedScopeException Akkor jelenik meg, ha a kiszolgáló elutasított egy vagy több kért hatókört.
MsalException Alapértelmezett ellenőrzött kivétel, amelyet az MSAL adott ki.
MsalIntuneAppProtectionPolicyRequiredException Akkor jelenik meg, ha az erőforrás mamCA védelmi szabályzata engedélyezve van.
MsalServiceException Akkor jelenik meg, ha a hiba kiszolgálóoldali.
MsalUiRequiredException Eldobva, ha a jogkivonat nem frissíthető csendben.
MsalUserCancelException Akkor lesz eldobva, ha a felhasználó megszakította a hitelesítési folyamatot.

ADALError to MsalException translation

Ha ezeket a hibákat az ADAL-ban észleli... ... észleli az alábbi MSAL-kivételeket:
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
}