Průvodce migrací ADAL na MSAL pro Android

  • Článek

Tento článek popisuje změny, které je potřeba provést při migraci aplikace, která používá knihovnu ADAL (Azure Active Directory Authentication Library) k používání knihovny Microsoft Authentication Library (MSAL).

Zvýraznění rozdílů

ADAL funguje s koncovým bodem Azure AD v1.0. Knihovna Microsoft Authentication Library (MSAL) funguje s platformou Microsoft Identity Platform, která se dříve označuje jako koncový bod Azure AD v2.0. Platforma Microsoft Identity Platform se liší od Azure AD verze 1.0 v tom, že:

Podpora:

  • Organizační identita (Microsoft Entra ID)

  • Identity mimo organizaci, jako jsou Outlook.com, Xbox Live atd.

  • (Jenom Azure AD B2C) Federované přihlášení s Googlem, Facebookem, Twitterem a Amazonem

  • Jsou standardy kompatibilní s:

    • OAuth v2.0
    • OpenID Připojení (OIDC)

Veřejné rozhraní API MSAL zavádí důležité změny, mezi které patří:

  • Nový model pro přístup k tokenům:
    • ADAL poskytuje přístup k tokenům prostřednictvím AuthenticationContext, který představuje server. MSAL poskytuje přístup k tokenům prostřednictvím objektu PublicClientApplication, který představuje klienta. Vývojáři klientů nemusí vytvářet novou PublicClientApplication instanci pro každou autoritu, se kterou potřebují pracovat. Vyžaduje se pouze jedna PublicClientApplication konfigurace.
    • Podpora vyžádání přístupových tokenů pomocí oborů kromě identifikátorů prostředků
    • Podpora přírůstkového souhlasu Vývojáři můžou požádat o obory, protože uživatel přistupuje k více a více funkcím v aplikaci, včetně těch, které nejsou zahrnuté během registrace aplikace.
    • Autority se už neověřují za běhu. Vývojář místo toho deklaruje seznam "známých autorit" během vývoje.
  • Změny rozhraní API tokenu:
    • V ADAL AcquireToken() nejprve vytvoří tichý požadavek. Pokud se to nepodaří, vytvoří interaktivní požadavek. Toto chování vedlo k tomu, že někteří vývojáři spoléhají jenom na AcquireTokento, že se uživatel neočekávaně vyzve k zadání přihlašovacích údajů. MSAL vyžaduje, aby vývojáři měli úmyslně, když uživatel obdrží výzvu k uživatelskému rozhraní.
      • AcquireTokenSilent Výsledkem vždy je bezobslužný požadavek, který buď proběhne úspěšně, nebo selže.
      • AcquireToken výsledkem vždy je požadavek, který uživatele vyzve prostřednictvím uživatelského rozhraní.
  • KNIHOVNA MSAL podporuje přihlášení z výchozího prohlížeče nebo integrovaného webového zobrazení:
    • Ve výchozím nastavení se používá výchozí prohlížeč na zařízení. To umožňuje službě MSAL používat stav ověřování (soubory cookie), které již mohou být k dispozici pro jeden nebo více přihlášených účtů. Pokud není k dispozici žádný stav ověřování, ověření během autorizace prostřednictvím knihovny MSAL způsobí vytvoření stavu ověřování (souborů cookie) pro výhodu jiných webových aplikací, které budou použity ve stejném prohlížeči.
  • Nový model výjimek:
    • Výjimky jasněji definují typ chyby, ke které došlo, a to, co vývojář potřebuje k jeho vyřešení.
  • MSAL podporuje objekty parametrů pro AcquireToken a AcquireTokenSilent volání.
  • MSAL podporuje deklarativní konfiguraci pro:
    • ID klienta, identifikátor URI přesměrování.
    • Vložený a výchozí prohlížeč
    • Orgány
    • Nastavení HTTP, jako je vypršení časového limitu čtení a připojení

Registrace a migrace vaší aplikace do MSAL

Abyste mohli používat KNIHOVNU MSAL, nemusíte měnit stávající registraci aplikace. Pokud chcete využít výhod přírůstkového nebo progresivního souhlasu, možná budete muset zkontrolovat registraci a zjistit konkrétní rozsahy, které chcete vyžádat přírůstkově. Další informace o oborech a přírůstkových souhlasech následuje.

V registraci aplikace na portálu se zobrazí karta oprávnění rozhraní API. Zobrazí se seznam rozhraní API a oprávnění (oborů), ke kterým je vaše aplikace aktuálně nakonfigurovaná tak, aby požadovala přístup. Zobrazuje také seznam názvů oborů přidružených k jednotlivým oprávněním rozhraní API.

S ADAL a koncovým bodem Azure AD v1.0 uživatel souhlasil s prostředky, které vlastní, byl udělen při prvním použití. S MSAL a platformou Microsoft Identity Platform je možné vyžádat souhlas přírůstkově. Přírůstkový souhlas je užitečný pro oprávnění, která uživatel může zvážit vysoké oprávnění, nebo se může jinak dotazovat, pokud není k dispozici jasné vysvětlení, proč je oprávnění požadováno. V ADAL mohla tato oprávnění vést k tomu, že uživatel opustil přihlašování k vaší aplikaci.

Tip

Použití přírůstkového souhlasu k poskytnutí dalšího kontextu uživatelům o tom, proč vaše aplikace potřebuje oprávnění.

Správci organizace můžou udělit souhlas s oprávněními, která vaše aplikace vyžaduje jménem všech členů organizace. Některé organizace umožňují jenom správcům udělit souhlas s aplikacemi. Správa souhlas vyžaduje, abyste do registrace aplikace zahrnuli všechna oprávnění a obory rozhraní API, které vaše aplikace používá.

Tip

I když můžete požádat o rozsah pomocí knihovny MSAL pro něco, co není součástí registrace vaší aplikace, doporučujeme aktualizovat registraci aplikace tak, aby zahrnovala všechny prostředky a obory, kterým by mohl uživatel kdykoli udělit oprávnění.

Migrace z ID prostředků na obory

Ověření a vyžádání autorizace pro všechna oprávnění při prvním použití

Pokud aktuálně používáte knihovnu ADAL a nepotřebujete používat přírůstkový souhlas, nejjednodušší způsob, jak začít používat knihovnu MSAL, je vytvořit acquireToken požadavek pomocí nového AcquireTokenParameter objektu a nastavit hodnotu ID prostředku.

Upozornění

Obory i ID prostředku není možné nastavit. Výsledkem pokusu o nastavení obou bude hodnota IllegalArgumentException.

Výsledkem bude stejné chování v1, které jste použili. Během první interakce se od uživatele požadují všechna oprávnění požadovaná v registraci aplikace.

Ověřování a vyžádání oprávnění pouze podle potřeby

Pokud chcete využít výhod přírůstkového souhlasu, vytvořte seznam oprávnění (rozsahů), které vaše aplikace používá z registrace aplikace, a uspořádejte je do dvou seznamů na základě:

  • Jaké obory chcete během první interakce uživatele s vaší aplikací během přihlašování požadovat.
  • Oprávnění přidružená k důležité funkci aplikace, která budete také muset uživateli vysvětlit.

Jakmile uspořádáte obory, uspořádejte každý seznam podle prostředku (API), pro který chcete požádat o token. Stejně jako všechny ostatní obory, které chcete uživateli autorizovat současně.

Objekt parametrů použitý k provedení požadavku na knihovnu MSAL podporuje:

  • Scope: Seznam oborů, pro které chcete požádat o autorizaci a přijetí přístupového tokenu.
  • ExtraScopesToConsent: Další seznam oborů, pro které chcete požádat o autorizaci, zatímco žádáte o přístupový token pro jiný prostředek. Tento seznam oborů vám umožní minimalizovat počet, kolikrát potřebujete požádat o autorizaci uživatele. To znamená menší počet výzev k autorizaci nebo vyjádření souhlasu uživatele.

Migrace z AuthenticationContext na PublicClientApplications

Vytváření PublicClientApplication

Při použití MSAL vytvoříte instanci PublicClientApplication. Tento objekt modeluje identitu aplikace a používá se k odesílání požadavků na jednu nebo více autorit. Pomocí tohoto objektu nakonfigurujete identitu klienta, identifikátor URI přesměrování, výchozí autoritu, jestli se má používat prohlížeč zařízení a vložené webové zobrazení, úroveň protokolu a další.

Tento objekt můžete deklarativním způsobem nakonfigurovat pomocí formátu JSON, který buď zadáte jako soubor, nebo ho uložíte jako prostředek v souboru APK.

I když tento objekt není singleton, interně používá sdílené Executors pro interaktivní i tiché požadavky.

Business to Business

V ADAL vyžaduje každá organizace, od které požadujete přístupové tokeny, samostatnou instanci AuthenticationContext. V MSAL už to není požadavek. Jako součást tichého nebo interaktivního požadavku můžete zadat autoritu, ze které chcete požádat o token.

Migrace z ověření autority na známé autority

Knihovna MSAL nemá příznak pro povolení nebo zakázání ověření autority. Ověření autority je funkce knihovny ADAL a v dřívějších verzích knihovny MSAL, která brání kódu v vyžádání tokenů z potenciálně škodlivé autority. Služba MSAL teď načte seznam autorit známých microsoftem a tento seznam sloučí s autoritami, které jste zadali ve své konfiguraci.

Tip

Pokud jste uživatel Azure Business to Consumer (B2C), znamená to, že už nemusíte ověřování autority zakázat. Místo toho do konfigurace MSAL zahrňte všechny podporované zásady Azure AD B2C jako autority.

Pokud se pokusíte použít autoritu, která není microsoftu známá a není součástí vaší konfigurace, získáte .UnknownAuthorityException

Protokolování

Protokolování teď můžete deklarativní konfigurovat jako součást konfigurace, například takto:

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

Migrace z UserInfo na účet

V ADAL AuthenticationResult poskytuje UserInfo objekt použitý k načtení informací o ověřeném účtu. Pojem "uživatel", který znamenal člověka nebo softwarového agenta, byl použit způsobem, který ztěžoval komunikaci s tím, že některé aplikace podporují jednoho uživatele (bez ohledu na to, jestli je to člověk nebo softwarový agent), který má více účtů.

Zvažte bankovní účet. Možná máte více účtů ve více než jedné finanční instituci. Při otevření účtu se vám (uživateli) vystaví přihlašovací údaje, jako je platební karta a PIN kód, které se použijí pro přístup k vašemu zůstatku, platbám na faktuře atd. pro každý účet. Tyto přihlašovací údaje lze použít pouze u finanční instituce, která je vydala.

Podobně jako účty v finanční instituci se k účtům na platformě Microsoft Identity Platform přistupuje pomocí přihlašovacích údajů. Tyto přihlašovací údaje jsou buď zaregistrované, nebo vydané společností Microsoft. Nebo microsoft jménem organizace.

Pokud se platforma Microsoft Identity Platform liší od finanční instituce, v této analogii představuje platforma Microsoft Identity Platform architekturu, která uživateli umožňuje používat jeden účet a jeho přidružené přihlašovací údaje pro přístup k prostředkům, které patří více jednotlivcům a organizacím. Je to jako schopnost používat kartu vystavenou jednou bankou, a to ještě v jiné finanční instituci. To funguje, protože všechny dotčené organizace používají platformu Microsoft Identity Platform, která umožňuje používat jeden účet napříč více organizacemi. Tady je příklad:

Sam pracuje pro Contoso.com, ale spravuje virtuální počítače Azure, které patří do Fabrikam.com. Aby Sam mohl spravovat virtuální počítače společnosti Fabrikam, musí mít oprávnění k přístupu k nim. Tento přístup můžete udělit přidáním účtu Sama do Fabrikam.com a udělením jeho účtu roli, která mu umožní pracovat s virtuálními počítači. To by se provedlo pomocí webu Azure Portal.

Přidání Contoso.com účtu Sam jako člena Fabrikam.com by vedlo k vytvoření nového záznamu v Fabrikam.com Microsoft Entra ID pro Sam. Záznam Samu v Microsoft Entra ID se označuje jako objekt uživatele. V tomto případě by tento objekt uživatele odkazoval zpět na objekt uživatele Sam v Contoso.com. Uživatelský objekt Sam Fabrikam je místní reprezentace Samu a použil by se k ukládání informací o účtu přidruženém k Samu v kontextu Fabrikam.com. V Contoso.com se Sam jmenuje Senior DevOps Consultant. Ve společnosti Fabrikam má Sam název Contractor-Virtual Machines. V Contoso.com sam není zodpovědný ani autorizovaný ke správě virtuálních počítačů. V Fabrikam.com je to jeho jediná funkce práce. Sam ale stále má jenom jednu sadu přihlašovacích údajů, které umožňují sledovat, což jsou přihlašovací údaje vydané Contoso.com.

Po úspěšném acquireToken volání se zobrazí odkaz na IAccount objekt, který lze použít v pozdějších acquireTokenSilent požadavcích.

IMultiTenantAccount

Pokud máte aplikaci, která přistupuje k deklarací identity účtu z každého tenanta, ve kterém je účet reprezentován, můžete přetypovat IAccount objekty na IMultiTenantAccount. Toto rozhraní poskytuje mapu ITenantProfiles, klíč klíč podle ID tenanta, která umožňuje přístup k deklaracím, které patří k účtu v každém tenantovi, od kterého jste požadovali token vzhledem k aktuálnímu účtu.

Deklarace identity v kořenovém adresáři IAccount a IMultiTenantAccount vždy obsahují deklarace identity z domovského tenanta. Pokud jste ještě neprošli žádost o token v rámci domovského tenanta, bude tato kolekce prázdná.

Další změny

Použití nového AuthenticationCallbacku

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

Migrace na nové výjimky

V ADAL existuje jeden typ výjimky, AuthenticationExceptionkterá zahrnuje metodu pro načtení hodnoty výčtu ADALError . V knihovně MSAL existuje hierarchie výjimek a každá má vlastní sadu přidružených konkrétních kódů chyb.

Výjimka Popis
MsalArgumentException Vyvolá se, pokud jeden nebo více argumentů vstupů není platný.
MsalClientException Vyvolá se, pokud je chyba na straně klienta.
MsalDeclinedScopeException Vyvolá se, pokud server odmítl jeden nebo více požadovaných oborů.
MsalException Výchozí zaškrtnutá výjimka vyvolaná knihovnou MSAL
MsalIntuneAppProtectionPolicyRequiredException Vyvolá se, pokud má prostředek povolenou zásadu ochrany MAMCA.
MsalServiceException Vyvolá se, pokud je chyba na straně serveru.
MsalUiRequiredException Vyvolá se, pokud se token nedá bezobslužně aktualizovat.
MsalUserCancelException Vyvolá se, pokud uživatel zrušil tok ověřování.

ADALError to MsalException translation

Pokud tyto chyby zachytáváte v ADAL... ... zachyťte tyto výjimky MSAL:
Žádná ekvivalentní chyba ADAL 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
Žádná ekvivalentní chyba ADAL MsalDeclinedScopeException
  • ADALError.APP_PACKAGE_NAME_NOT_FOUND
  • ADALError.BROKER_APP_VERIFICATION_FAILED
  • ADALError.PACKAGE_NAME_NOT_FOUND
 MsalException
Žádná ekvivalentní chyba ADAL MsalIntuneAppProtectionPolicyRequiredException
  • ADALError.SERVER_ERROR
  • ADALError.SERVER_INVALID_REQUEST
 MsalServiceException
  • ADALError.AUTH_REFRESH_FAILED_PROMPT_NOT_ALLOWED
 MsalUiRequiredException
Žádná ekvivalentní chyba ADAL MsalUserCancelException

Protokolování ADAL do protokolování MSAL

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