Průvodce migrací ADAL na MSAL pro Android

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 spolupracuje s koncovým bodem Azure Active Directory verze 1.0. Microsoft Authentication Library (MSAL) spolupracuje s platformou Microsoft Identity Platform – dříve označovanou jako koncový bod Azure Active Directory verze 2.0. Platforma Microsoft Identity Platform se liší od Azure Active Directory verze 1.0 v této platformě:

Podporuje:

  • Organizační identita (Azure Active Directory)

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

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

  • Je standardy kompatibilní s:

    • OAuth verze 2.0
    • OpenID Connect (OIDC)

Veřejné rozhraní API MSAL zavádí důležité změny, včetně následujících:

  • Nový model pro přístup k tokenům:
    • ADAL poskytuje přístup k tokenům prostřednictvím objektu 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í vytvořit novou PublicClientApplication instanci pro každou autoritu, se kterou potřebují pracovat. Vyžaduje se pouze jedna PublicClientApplication konfigurace.
    • Podpora pro 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 rozsahy, 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 nejprve AcquireToken() 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 uživatel občas neočekávaně vyzve k zadání přihlašovacích údajů. MSAL vyžaduje, aby vývojáři měli úmysl, když uživatel obdrží výzvu k uživatelskému rozhraní.
      • AcquireTokenSilent vždy vede k tichému požadavku, který buď proběhne úspěšně, nebo selže.
      • AcquireToken vždy způsobí požadavek, který uživatele vyzve prostřednictvím uživatelského rozhraní.
  • 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 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 přítomné 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 msAL způsobí vytvoření stavu ověřování (cookies) pro výhody jiných webových aplikací, které budou použity ve stejném prohlížeči.
  • Nový model výjimky:
    • Výjimky jasně definují typ chyby, ke které došlo, a to, co vývojář potřebuje k 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 aplikace do MSAL

Abyste mohli používat 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 se řídí.

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

U ADAL a koncového bodu Azure AD v1 byl uživateli udělen souhlas s prostředky, které vlastní, při prvním použití. U MSAL a platformy 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á může uživatel zvážit vysoké oprávnění, nebo může jinak dotazovat, pokud není k dispozici jasné vysvětlení, proč je oprávnění vyžadováno. V ADAL tato oprávnění můžou vést k tomu, že uživatel opustil 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í správcům jenom souhlas s aplikacemi. Souhlas správce 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ž si můžete vyžádat obor pomocí nástroje MSAL pro něco, co není součástí registrace aplikace, doporučujeme aktualizovat registraci aplikace tak, aby zahrnovala všechny prostředky a obory, ke kterým by mohl uživatel někdy 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 ADAL a nepotřebujete používat přírůstkový souhlas, nejjednodušší způsob, jak začít používat MSAL, 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í obou výsledků dojde k .IllegalArgumentException

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

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

Pokud chcete využít 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ě:

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

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

Objekt parametrů použitý k zadání požadavku na 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 při vyžádání přístupového tokenu pro jiný prostředek. Tento seznam oborů umožňuje minimalizovat počet potřebných k vyžádání autorizace 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 provádění žádostí na jednu nebo více autorit. S tímto objektem nakonfigurujete identitu klienta, identifikátor URI přesměrování, výchozí autoritu, jestli se má prohlížeč zařízení používat vs. vložené webové zobrazení, úroveň protokolu a další.

Tento objekt můžete deklarativním způsobem 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, ze 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

MSAL nemá příznak pro povolení nebo zakázání ověření autority. Ověření autority je funkce V ADAL a v počátečních verzích MSAL, která brání vašemu kódu v vyžádání tokenů z potenciálně škodlivé autority. MsAL teď načte seznam autorit známých microsoftem a sloučí tento seznam 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á microsoftu není známa 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 poskytuje AuthenticationResultUserInfo 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. Když otevřete účet, vy (uživatel) jste vydali přihlašovací údaje, jako je PIN kód platební karty & , který se používá 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 účty ve 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é Microsoftem. Nebo microsoftem jménem organizace.

Pokud se platforma Microsoft Identity Platform liší od finanční instituce, je v tomto analogii to, že platforma Microsoft Identity Platform poskytuje 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žití jednoho účtu 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 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 přidáním účtu Sama do Fabrikam.com a udělením jeho účtu roli, která mu umožňuje pracovat s virtuálními počítači. To by se provádělo na webu Azure Portal.

Přidání účtu Sam Contoso.com jako člena Fabrikam.com by vedlo k vytvoření nového záznamu ve službě Azure Active Directory for Sam na webu Fabrikam.com. Záznam Samu v Azure Active Directory 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 slouží 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. V 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. Sam ale stále má jen jednu sadu přihlašovacích údajů, která je tř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í identity účtu z každého tenanta, ve kterém je účet reprezentovaný, můžete přetypovat IAccount objekty na IMultiTenantAccount. Toto rozhraní poskytuje mapu ITenantProfiles, která je klíčována podle ID tenanta, která umožňuje přístup k deklaracím identity, 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ě neprodáli žádost o token v rámci domácí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 MSAL je hierarchie výjimek a každá má svou vlastní sadu přidružených konkrétních kódů chyb.

Výjimka Description
MsalArgumentException Vyvolá se, pokud je neplatný jeden nebo více argumentů vstupů.
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í zaškrtnutá výjimka vyvolána 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íte v ADAL... ... zachyťte tyto výjimky MSAL:
Žádná ekvivalentní chyba 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
Žádná ekvivalentní chyba ADALError MsalDeclinedScopeException
  • ADALError.APP_PACKAGE_NAME_NOT_FOUND
  • ADALError.BROKER_APP_VERIFICATION_FAILED
  • ADALError.PACKAGE_NAME_NOT_FOUND
MsalException
Žádná ekvivalentní chyba ADALError MsalIntuneAppProtectionPolicyRequiredException
  • ADALError.SERVER_ERROR
  • ADALError.SERVER_INVALID_REQUEST
MsalServiceException
  • ADALError.AUTH_REFRESH_FAILED_PROMPT_NOT_ALLOWED
MsalUiRequiredException
Žádná ekvivalentní chyba ADALError MsalUserCancelException

Protokolování knihovny 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
}