Migreringsguide för ADAL till MSAL för Android

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

Skillnadshöjdpunkter

ADAL fungerar med slutpunkten Azure AD v1.0. Microsofts autentiseringsbibliotek (MSAL) fungerar med Microsofts identitetsplattform, som tidigare kallades Azure AD v2.0-slutpunkt. Microsofts identitetsplattform skiljer sig från Azure AD v1.0 genom att den:

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, X 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 PublicClientApplication, som 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. Om det misslyckas skickas 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 medvetna om när användaren får en UI-uppmaning.
    • 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.

Användarmedgivande

Med ADAL och Azure AD v1.0-slutpunkt beviljades användarens medgivande till resurser som de äger vid första användningen. Med MSAL och Microsofts identitetsplattform kan medgivande begäras stegvis. Stegvis samtycke är användbart för behörigheter som en användare kan uppfatta som särskilt känsliga, eller som användaren annars kan ifrågasätta om användaren inte får en tydlig förklaring till varför behörigheten krävs. I ADAL kan dessa behörigheter ha resulterat i att användaren övergav inloggningen till din app.

Administratörsmedgivande

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 ge medgivande till applikationer. Administratörsmedgivande kräver att du inkluderar alla API-behörigheter och omfång som används av ditt program i din appregistrering.

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.

Detta ger samma v1-beteende som du är van vid. 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

Skapar 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änder det internt delad Executors för både interaktiva och tysta förfrågningar.

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 inget alternativ för att aktivera eller inaktivera validering av auktoritet. 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 att Microsoft och sammanfogar listan med de myndigheter som du har angett i konfigurationen.

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

Logging

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 uttagsautomat kort och 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 registreras med eller utfärdas 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 Azure virtuella 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.

Att lägga till Sams konto på Contoso.com som medlem i Fabrikam.com skulle leda till att en ny post skapas för Sam i Fabrikam.coms Microsoft Entra-ID. 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 de autentiseringsuppgifter som utfärdats 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 får åtkomst till anspråksuppgifter om ett konto från var och en av de klientorganisationer där kontot representeras, kan du omvandla objekt av typen IAccount till IMultiTenantAccount. Det här gränssnittet tillhandahåller en mappning av ITenantProfiles, med klientorganisations-ID som nyckel, som gör att du kan komma åt de anspråk som tillhör kontot i var och en av de klientorganisationer som du har begärt en token från, för det aktuella kontot.

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

Andra ändringar

Använd 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 hämta uppräkningsvärdet ADALError. I MSAL finns det en hierarki med undantag och var och en har en egen uppsättning associerade specifika felkoder.

ADALError till MsalException-översättning

Från 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
}