Migreringsguide för ADAL till MSAL för Android

Den här artikeln beskriver de ändringar 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).

Skillnadspunkter

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

Stöder:

  • Organisationsidentitet (Azure Active Directory)

  • Icke-organisationsidentiteter 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 Connect (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 som 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.
  • Token-API:et ändras:
    • I ADAL AcquireToken() gör du först en tyst begäran. Annars gör den 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ågas om autentiseringsuppgifter ibland. MSAL kräver att utvecklare är avsiktliga när användaren får en UI-fråga.
      • 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) till förmån för andra webbprogram som ska användas i samma webbläsare om det inte finns något autentiseringstillstånd under auktoriseringen via MSAL.
  • 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 jämfört med 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 DE API:er och behörigheter (omfång) som appen för närvarande är konfigurerad 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-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.

Tips

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 godkänna 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.

Tips

Även om du kan begära ett omfång med 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ändningen

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 med behörigheter (omfång) som appen använder från appregistreringen och ordnar 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 ordnat 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 på samma gång.

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

Skapa 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 inbäddad webbvy, 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 den utfärdare som du vill begära en token från 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. Verifiering av utfärdare är en funktion i ADAL, och i de tidiga versionerna av MSAL förhindrar det att koden begär token från en potentiellt skadlig utfärdare. MSAL hämtar nu en lista över myndigheter som microsoft känner till och sammanfogar listan med de myndigheter som du har angett i konfigurationen.

Tips

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 auktoritet som inte är känd av 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 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 hos fler än ett finansinstitut. När du öppnar ett konto får du (användaren) autentiseringsuppgifter, till exempel en PIN-kod för ATM-kort & , 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 autentiseringsuppgifter. Dessa autentiseringsuppgifter registreras med eller utfärdas av Microsoft. Eller av Microsoft för en organisations räkning.

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 att en användare kan använda ett konto och dess associerade autentiseringsuppgifter för att få åtkomst till resurser som tillhör flera individer och organisationer. Det här är som att kunna använda ett kort utfärdat av en bank, hos ä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 görs med Azure-portalen.

Om sams Contoso.com-konto läggs till som medlem i Fabrikam.com skapas en ny post i Fabrikam.coms Azure Active Directory for Sam. Sams post i Azure Active Directory 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 ansvarar inte Sam, eller har behörighet, 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 de autentiseringsuppgifter som utfärdats av Contoso.com.

När ett lyckat acquireToken anrop har utförts 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 är nyckeln efter klientorganisations-ID, som gör att du kan komma åt de anspråk 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 IAccount av 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 ä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 Description
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 nekades 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
}