Průvodce migrací Z 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 Azure Active Directory Authentication Library (ADAL) 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 Microsoft identity platform, dříve označovaným jako koncový bod Azure AD v2.0. Microsoft identity platform se od Azure AD verze 1.0 liší v tom, že:

Podporuje:

  • Organizační identita (ID Microsoft Entra)

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

  • (jenom Azure AD B2C) Federované přihlášení pomocí Googlu, Facebooku, Twitteru a Amazonu

  • Jsou standardy kompatibilní s:

    • OAuth v2.0
    • OpenID Connect (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 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ů s využitím 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 dalším funkcím aplikace, včetně těch, které nejsou součástí registrace aplikace.
    • Autority se už za běhu neověřují. Vývojář místo toho během vývoje deklaruje seznam "známých autorit".
  • Změny rozhraní API tokenu:
    • V ADAL AcquireToken() nejprve vytvoří tichou žádost. V opačném případě odešle interaktivní požadavek. Toto chování vedlo k tomu, že někteří vývojáři spoléhali pouze na AcquireToken, což vedlo k tomu, že se uživateli občas neočekávaně zobrazila výzva k zadání přihlašovacích údajů. MSAL vyžaduje, aby vývojáři záměrně hleděli, kdy se uživateli zobrazí výzva k uživatelskému rozhraní.
      • AcquireTokenSilent vždy vede k tichému požadavku, který je úspěšný nebo neúspěšný.
      • AcquireToken výsledkem vždy bude 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 z vloženého webového zobrazení:
    • Ve výchozím nastavení se na zařízení používá výchozí prohlížeč. To umožňuje knihovně MSAL používat stav ověřování (soubory cookie), které už můžou existovat pro jeden nebo více přihlášených účtů. Pokud není k dispozici žádný stav ověřování, při ověřování prostřednictvím knihovny MSAL se vytvoří stav ověřování (soubory cookie) ve prospěch jiných webových aplikací, které se budou používat ve stejném prohlížeči.
  • Nový model výjimky:
    • Výjimky jasněji definují typ chyby, ke které došlo, a co musí vývojář udělat, aby ji vyřešil.
  • Knihovna MSAL podporuje objekty parametrů pro AcquireToken a AcquireTokenSilent volání.
  • Knihovna MSAL podporuje deklarativní konfiguraci pro:
    • ID klienta, identifikátor URI přesměrování.
    • Vložený vs. výchozí prohlížeč
    • Orgány
    • Nastavení HTTP, jako je vypršení časového limitu čtení a připojení

Registrace vaší aplikace a migrace do MSAL

Abyste mohli používat MSAL, nemusíte měnit stávající registraci aplikace. Pokud chcete využít přírůstkový nebo progresivní souhlas, možná budete muset zkontrolovat registraci a identifikovat konkrétní obory, o které chcete inkrementálně požádat. Další informace o oborech a přírůstkové vyjádření souhlasu najdete níže.

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 ke každému oprávnění rozhraní API.

U knihovny ADAL a koncového bodu Azure AD v1.0 byl udělen souhlas uživatele s prostředky, které vlastní, při prvním použití. V knihovně MSAL a Microsoft identity platform je možné požádat o souhlas přírůstkově. Přírůstkový souhlas je užitečný pro oprávnění, která uživatel může považovat za vysoká oprávnění, nebo se může jinak dotazovat, pokud není poskytnuta, s jasným vysvětlením, proč je oprávnění požadováno. V ADAL tato oprávnění můžou vést k tomu, že uživatel opustí přihlášení k vaší aplikaci.

Tip

Pomocí přírůstkového souhlasu můžete uživatelům poskytnout další kontext 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í vyjádření souhlasu s aplikacemi jenom správcům. Správa souhlas vyžaduje, abyste do registrace aplikace zahrnuli všechna oprávnění a obory rozhraní API používané vaší aplikací.

Tip

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

Migrace z ID prostředků na rozsahy

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 knihovnu MSAL používat, je vytvořit acquireToken požadavek pomocí nového AcquireTokenParameter objektu a nastavit hodnotu ID prostředku.

Upozornění

Není možné nastavit obory i ID prostředku. Při pokusu o nastavení obojího dojde k chybě IllegalArgumentException.

Výsledkem bude stejné chování v1, které používáte. Všechna oprávnění požadovaná při registraci aplikace se od uživatele požadují při jeho první interakci.

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

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

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

Jakmile uspořádáte obory, uspořádejte každý seznam podle toho, pro který prostředek (rozhraní API) chcete požádat o token. Stejně jako všechny další obory, které chcete, aby uživatel autorizoval současně.

Objekt parameters použitý k vytvoření požadavku na knihovnu MSAL podporuje:

  • Scope: Seznam oborů, pro které chcete požádat o autorizaci a získat přístupový token.
  • 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ů umožňuje minimalizovat počet potřebných žádostí 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í aplikace PublicClientApplication

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

Tento objekt můžete deklarativně nakonfigurovat pomocí formátu JSON, který zadáte jako soubor nebo 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 knihovně MSAL už to není povinné. Autoritu, od které chcete požádat o token, můžete zadat jako součást tichého nebo interaktivního požadavku.

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 v knihovně ADAL a v počátečních verzích knihovny MSAL, která brání vašemu kódu v vyžádání tokenů od potenciálně škodlivé autority. Knihovna MSAL teď načte seznam autorit známých Microsoftu a sloučí tento seznam s autoritami, které jste zadali v konfiguraci.

Tip

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

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

protokolování

Teď můžete deklarativně nakonfigurovat protokolování jako součást konfigurace, například takto:

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

Migrace z UserInfo na účet

V ADAL poskytuje UserInfo objekt použitý AuthenticationResult k načtení informací o ověřeném účtu. Termín "uživatel", který znamenal lidského nebo softwarového agenta, se použil způsobem, který ztěžoval sdělení, že některé aplikace podporují jednoho uživatele (ať už lidského nebo softwarového agenta), který má více účtů.

Zvažte bankovní účet. U více než jedné finanční instituce můžete mít více účtů. Když otevřete účet, zobrazí se vám (uživateli) přihlašovací údaje, například PIN platební karty & , které se používají pro přístup k 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 u účtů ve finanční instituci se k účtům v Microsoft identity platform přistupuje pomocí přihlašovacích údajů. Tyto přihlašovací údaje jsou buď zaregistrované u Microsoftu, nebo vydané společností Microsoft. Nebo microsoftem jménem organizace.

Microsoft identity platform se v této analogii liší od finanční instituce v tom, že Microsoft identity platform poskytuje architekturu, která umožňuje uživateli 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. To je jako mít možnost používat kartu vystavenou jednou bankou, u jiné finanční instituce. To funguje, protože všechny příslušné organizace používají Microsoft identity platform, což umožňuje použití jednoho účtu ve více organizacích. Tady je příklad:

Sam pracuje pro Contoso.com, ale spravuje virtuální počítače Azure, které patří do Fabrikam.com. Aby Mohl Sam spravovat virtuální počítače společnosti Fabrikam, musí mít oprávnění k přístupu k nim. Tento přístup je možné udělit tak, že do Fabrikam.com přidáte Samův účet a udělíte mu roli, která mu umožní pracovat s virtuálními počítači. To se provede pomocí Azure Portal.

Přidání Samova Contoso.com účtu jako člena Fabrikam.com by vedlo k vytvoření nového záznamu v ID Microsoft Entra Fabrikam.com pro Sam. Samův záznam v ID Microsoft Entra se označuje jako objekt uživatele. V tomto případě by objekt uživatele odkazoval zpět na objekt uživatele Sam v Contoso.com. Objekt uživatele Sam Fabrikam je místní reprezentace Samu a slouží k ukládání informací o účtu přidruženém k Samu v kontextu Fabrikam.com. V Contoso.com má Sam titul 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á pracovní funkce. Sam ale stále má jenom jednu sadu přihlašovacích údajů, které je potřeba 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ím identity účtu z každého tenanta, ve kterém je účet zastoupený, můžete přetypovat IAccount objekty do IMultiTenantAccount. Toto rozhraní poskytuje mapu ITenantProfiless klíčem podle ID tenanta, který umožňuje přístup k deklaracím, které patří k účtu v každém tenantovi, ze 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ě nepožadovali token v rámci domovského tenanta, bude tato kolekce prázdná.

Další změny

Použití nové funkce AuthenticationCallback

// 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á z nich má vlastní sadu přidružených specifických kódů chyb.

Výjimka Description
MsalArgumentException Vyvolá se, pokud je jeden nebo více argumentů vstupů neplatných.
MsalClientException Vyvolá se, pokud je chyba na straně klienta.
MsalDeclinedScopeException Vyvolána, pokud server odmítl jeden nebo více požadovaných oborů.
MsalException Výchozí kontrolovaná výjimka vyvolaná knihovnou MSAL.
MsalIntuneAppProtectionPolicyRequiredException Vyvolána, pokud má prostředek povolené zásady ochrany MAMCA.
MsalServiceException Vyvolá se, pokud je chyba na straně serveru.
MsalUiRequiredException Vyvolána, pokud token nejde bezobslužně aktualizovat.
MsalUserCancelException Vyvolána, 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
}