Migreringsguide för ADAL till MSAL för Android

  • Artikel

Den här artikeln belyser ändringar som du behöver göra för att migrera en app som använder Azure Active Directory Authentication Library (ADAL) för att använda Microsoft Authentication Library (MSAL).

Skillnadshöjdpunkter

ADAL fungerar med Azure AD v1.0-slutpunkten. Microsoft Authentication Library (MSAL) fungerar med Microsofts identitetsplattform, som tidigare kallades Azure AD v2.0-slutpunkten. Den Microsofts identitetsplattform skiljer sig från Azure AD v1.0 på så sätt:

Stöder:

  • Organisationsidentitet (Microsoft Entra-ID)

  • Icke-organisatoriska identiteter som Outlook.com, Xbox Live och så vidare

  • (Endast Azure AD B2C) Federerad inloggning med Google, Facebook, Twitter och Amazon

  • Är standarder kompatibla med:

    • OAuth v2.0
    • OpenID Anslut (OIDC)

Det offentliga MSAL-API:et introducerar viktiga ändringar, inklusive:

  • En ny modell för åtkomst till token:
    • ADAL ger åtkomst till token via , AuthenticationContextsom representerar servern. MSAL ger åtkomst till token via , PublicClientApplicationsom representerar klienten. Klientutvecklare behöver inte skapa en ny PublicClientApplication instans för varje utfärdare de behöver interagera med. Endast en PublicClientApplication konfiguration krävs.
    • Stöd för att begära åtkomsttoken med hjälp av omfång utöver resursidentifierare.
    • Stöd för inkrementellt medgivande. Utvecklare kan begära omfång när användaren får åtkomst till fler och fler funktioner i appen, inklusive de som inte ingår under appregistreringen.
    • Myndigheterna verifieras inte längre vid körning. I stället deklarerar utvecklaren en lista över "kända myndigheter" under utvecklingen.
  • Api-ändringar för token:
    • I ADAL AcquireToken() gör du först en tyst begäran. Annars görs en interaktiv begäran. Det här beteendet resulterade i att vissa utvecklare bara förlitade sig på AcquireToken, vilket resulterade i att användaren oväntat tillfrågades om autentiseringsuppgifter ibland. MSAL kräver att utvecklare är avsiktliga när användaren tar emot en användargränssnittsprompt.
      • AcquireTokenSilent resulterar alltid i en tyst begäran som antingen lyckas eller misslyckas.
      • AcquireToken resulterar alltid i en begäran som uppmanar användaren via användargränssnittet.
  • MSAL stöder inloggning från antingen en standardwebbläsare eller en inbäddad webbvy:
    • Som standard används standardwebbläsaren på enheten. Detta gör att MSAL kan använda autentiseringstillstånd (cookies) som kanske redan finns för ett eller flera inloggade konton. Om det inte finns något autentiseringstillstånd skapas autentiseringstillståndet (cookies) under auktoriseringen via MSAL till förmån för andra webbprogram som ska användas i samma webbläsare.
  • Ny undantagsmodell:
    • Undantag definierar tydligare vilken typ av fel som inträffade och vad utvecklaren behöver göra för att lösa det.
  • MSAL stöder parameterobjekt för AcquireToken och AcquireTokenSilent anrop.
  • MSAL stöder deklarativ konfiguration för:
    • Klient-ID, omdirigerings-URI.
    • Inbäddad kontra standardwebbläsare
    • Myndigheterna
    • HTTP-inställningar som läs- och anslutningstimeout

Din appregistrering och migrering till MSAL

Du behöver inte ändra din befintliga appregistrering för att använda MSAL. Om du vill dra nytta av inkrementellt/progressivt medgivande kan du behöva granska registreringen för att identifiera de specifika omfång som du vill begära stegvis. Mer information om omfång och inkrementellt medgivande finns här.

I din appregistrering i portalen visas fliken API-behörigheter . Detta ger en lista över API:er och behörigheter (omfång) som appen för närvarande är konfigurerad för att begära åtkomst till. Den visar också en lista över de omfångsnamn som är associerade med varje API-behörighet.

Med ADAL och Azure AD v1.0-slutpunkten beviljades användarens medgivande till resurser som de äger vid första användningen. Med MSAL och Microsofts identitetsplattform kan medgivande begäras stegvis. Inkrementellt medgivande är användbart för behörigheter som en användare kan överväga med hög behörighet, eller kan på annat sätt ifrågasätta om det inte ges en tydlig förklaring av varför behörigheten krävs. I ADAL kan dessa behörigheter ha resulterat i att användaren övergav inloggningen till din app.

Dricks

Använd inkrementellt medgivande för att ge användarna ytterligare kontext om varför din app behöver en behörighet.

Organisationsadministratörer kan samtycka till behörigheter som ditt program kräver för alla medlemmar i organisationen. Vissa organisationer tillåter endast administratörer att godkänna program. Administratörsmedgivande kräver att du inkluderar alla API-behörigheter och omfång som används av ditt program i din appregistrering.

Dricks

Även om du kan begära ett omfång med HJÄLP av MSAL för något som inte ingår i appregistreringen rekommenderar vi att du uppdaterar appregistreringen så att den inkluderar alla resurser och omfång som en användare någonsin kan bevilja behörighet till.

Migrera från resurs-ID:t till omfång

Autentisera och begära auktorisering för alla behörigheter vid första användning

Om du för närvarande använder ADAL och inte behöver använda inkrementellt medgivande är det enklaste sättet att börja använda MSAL att göra en acquireToken begäran med det nya AcquireTokenParameter objektet och ange resurs-ID-värdet.

Varning

Det går inte att ange både omfång och ett resurs-ID. Om du försöker ange båda resulterar det i en IllegalArgumentException.

Detta resulterar i samma v1-beteende som du använder. Alla behörigheter som begärs i din appregistrering begärs från användaren under deras första interaktion.

Autentisera och begär endast behörigheter efter behov

Om du vill dra nytta av inkrementellt medgivande skapar du en lista över behörigheter (omfång) som appen använder från appregistreringen och organiserar dem i två listor baserat på:

  • Vilka omfång du vill begära under användarens första interaktion med din app under inloggningen.
  • De behörigheter som är associerade med en viktig funktion i din app som du också behöver förklara för användaren.

När du har organiserat omfången ordnar du varje lista med vilken resurs (API) du vill begära en token för. Förutom andra omfång som du vill att användaren ska auktorisera samtidigt.

Parameterobjektet som används för att göra din begäran till MSAL stöder:

  • Scope: Listan över omfång som du vill begära auktorisering för och ta emot en åtkomsttoken.
  • ExtraScopesToConsent: En ytterligare lista över omfång som du vill begära auktorisering för när du begär en åtkomsttoken för en annan resurs. Med den här listan med omfång kan du minimera antalet gånger som du behöver begära användarauktorisering. Vilket innebär färre uppmaningar om användarauktorisering eller medgivande.

Migrera från AuthenticationContext till PublicClientApplications

Konstruera PublicClientApplication

När du använder MSAL instansierar du en PublicClientApplication. Det här objektet modellerar din appidentitet och används för att göra begäranden till en eller flera myndigheter. Med det här objektet konfigurerar du din klientidentitet, omdirigerings-URI, standardutfärdare, om du vill använda enhetswebbläsaren eller den inbäddade webbvyn, loggnivån med mera.

Du kan deklarativt konfigurera det här objektet med JSON, som du antingen anger som en fil eller lagrar som en resurs i din APK.

Även om det här objektet inte är en singleton används Executors det internt för både interaktiva och tysta begäranden.

Företag till företag

I ADAL kräver varje organisation som du begär åtkomsttoken från en separat instans av AuthenticationContext. I MSAL är detta inte längre ett krav. Du kan ange från vilken utfärdare du vill begära en token som en del av din tysta eller interaktiva begäran.

Migrera från utfärdarvalidering till kända myndigheter

MSAL har ingen flagga för att aktivera eller inaktivera verifiering av utfärdare. Utfärdarvalidering är en funktion i ADAL och i de tidiga versionerna av MSAL förhindrar det att din kod begär token från en potentiellt skadlig utfärdare. MSAL hämtar nu en lista över myndigheter som är kända för Microsoft och sammanfogar listan med de myndigheter som du har angett i konfigurationen.

Dricks

Om du är en Azure Business to Consumer-användare (B2C) innebär det att du inte längre behöver inaktivera verifiering av utfärdare. Inkludera i stället var och en av de Azure AD B2C-principer som stöds som myndigheter i DIN MSAL-konfiguration.

Om du försöker använda en utfärdare som inte är känd för Microsoft och inte ingår i konfigurationen får du en UnknownAuthorityException.

Loggning

Nu kan du deklarativt konfigurera loggning som en del av konfigurationen, så här:

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

Migrera från UserInfo till konto

I ADAL AuthenticationResult tillhandahåller det ett UserInfo objekt som används för att hämta information om det autentiserade kontot. Termen "användare", som innebar en mänsklig agent eller programvaruagent, tillämpades på ett sätt som gjorde det svårt att kommunicera att vissa appar stöder en enskild användare (oavsett om det är en mänsklig agent eller programvaruagent) som har flera konton.

Överväg ett bankkonto. Du kan ha fler än ett konto på mer än ett finansinstitut. När du öppnar ett konto utfärdas du (användaren) autentiseringsuppgifter, till exempel ett ATM-kort och EN PIN-kod, som används för att komma åt ditt saldo, fakturera betalningar och så vidare för varje konto. Dessa autentiseringsuppgifter kan endast användas hos det finansinstitut som utfärdade dem.

I likhet med konton på ett finansinstitut används konton i Microsofts identitetsplattform med hjälp av autentiseringsuppgifter. Dessa autentiseringsuppgifter är antingen registrerade med eller utfärdade av Microsoft. Eller av Microsoft på uppdrag av en organisation.

Om Microsofts identitetsplattform skiljer sig från ett finansinstitut, i den här analogin, är att Microsofts identitetsplattform tillhandahåller ett ramverk som gör det möjligt för en användare att använda ett konto och dess associerade autentiseringsuppgifter för att få åtkomst till resurser som tillhör flera individer och organisationer. Detta är som att kunna använda ett kort utfärdat av en bank, på ännu ett finansinstitut. Detta fungerar eftersom alla organisationer i fråga använder Microsofts identitetsplattform, vilket gör att ett konto kan användas i flera organisationer. Här är ett exempel:

Sam arbetar för Contoso.com men hanterar virtuella Azure-datorer som tillhör Fabrikam.com. För att Sam ska kunna hantera Fabrikams virtuella datorer måste han ha behörighet att komma åt dem. Den här åtkomsten kan beviljas genom att lägga till Sams konto i Fabrikam.com och ge hans konto en roll som gör att han kan arbeta med de virtuella datorerna. Detta skulle göras med Azure-portalen.

Om sams Contoso.com-konto läggs till som medlem i Fabrikam.com skapas en ny post i Fabrikam.com Microsoft Entra-ID för Sam. Sams post i Microsoft Entra-ID kallas för ett användarobjekt. I det här fallet pekar användarobjektet tillbaka på Sams användarobjekt i Contoso.com. Sams Fabrikam-användarobjekt är den lokala representationen av Sam och används för att lagra information om kontot som är associerat med Sam i kontexten för Fabrikam.com. I Contoso.com är Sams titel Senior DevOps Consultant. I Fabrikam är Sams titel Contractor-Virtual Machines. I Contoso.com är Sam inte ansvarig eller auktoriserad för att hantera virtuella datorer. I Fabrikam.com är det hans enda jobbfunktion. Ändå har Sam fortfarande bara en uppsättning autentiseringsuppgifter att hålla reda på, vilket är autentiseringsuppgifterna som utfärdas av Contoso.com.

När ett lyckat acquireToken anrop har gjorts visas en referens till ett IAccount objekt som kan användas i senare acquireTokenSilent begäranden.

IMultiTenantAccount

Om du har en app som har åtkomst till anspråk om ett konto från var och en av de klienter där kontot representeras kan du omvandla IAccount objekt till IMultiTenantAccount. Det här gränssnittet innehåller en karta över ITenantProfiles, som styrs av klientorganisations-ID, som gör att du kan komma åt anspråken som tillhör kontot i var och en av de klienter som du har begärt en token från i förhållande till det aktuella kontot.

Anspråken i roten av IAccount och IMultiTenantAccount innehåller alltid anspråken från hemklientorganisationen. Om du ännu inte har gjort en begäran om en token i hemklientorganisationen är den här samlingen tom.

Andra förändringar

Använda den nya 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);
}

Migrera till de nya undantagen

I ADAL finns det en typ av undantag, AuthenticationException, som innehåller en metod för att ADALError hämta uppräkningsvärdet. I MSAL finns det en hierarki med undantag och var och en har en egen uppsättning associerade specifika felkoder.

Undantag beskrivning
MsalArgumentException Utlöses om ett eller flera indataargument är ogiltiga.
MsalClientException Utlöses om felet är klientsidan.
MsalDeclinedScopeException Utlöses om en eller flera begärda omfång avvisades av servern.
MsalException Standardkontrollerat undantag som genereras av MSAL.
MsalIntuneAppProtectionPolicyRequiredException Utlöses om resursen har MAMCA-skyddsprincip aktiverad.
MsalServiceException Utlöses om felet är serversidan.
MsalUiRequiredException Utlöses om token inte kan uppdateras tyst.
MsalUserCancelException Utlöses om användaren avbröt autentiseringsflödet.

ADALError till MsalException-översättning

Om du får dessa fel i ADAL... ... fånga dessa MSAL-undantag:
Ingen motsvarande 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
Ingen motsvarande ADALError MsalDeclinedScopeException
  • ADALError.APP_PACKAGE_NAME_NOT_FOUND
  • ADALError.BROKER_APP_VERIFICATION_FAILED
  • ADALError.PACKAGE_NAME_NOT_FOUND
 MsalException
Ingen motsvarande ADALError MsalIntuneAppProtectionPolicyRequiredException
  • ADALError.SERVER_ERROR
  • ADALError.SERVER_INVALID_REQUEST
 MsalServiceException
  • ADALError.AUTH_REFRESH_FAILED_PROMPT_NOT_ALLOWED
 MsalUiRequiredException
Ingen motsvarande ADALError MsalUserCancelException

ADAL-loggning till MSAL-loggning

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