Migratiehandleiding voor ADAL naar MSAL voor Android

  • Artikel

In dit artikel worden de wijzigingen beschreven die u moet aanbrengen om een app te migreren die gebruikmaakt van de Azure Active Directory Authentication Library (ADAL) om msal (Microsoft Authentication Library) te gebruiken.

Belangrijke verschillen

ADAL werkt met het Azure AD v1.0-eindpunt. De Microsoft Authentication Library (MSAL) werkt met het Microsoft Identity Platform, voorheen bekend als het Azure AD v2.0-eindpunt. De Microsoft identity platform verschilt van Azure AD v1.0 in dat geval:

Ondersteunt:

  • Organisatie-id (Microsoft Entra-id)

  • Niet-organisatie-identiteiten, zoals Outlook.com, Xbox Live, enzovoort

  • (Alleen Azure AD B2C) Federatieve aanmelding met Google, Facebook, Twitter en Amazon

  • Is standaarden compatibel met:

    • OAuth v2.0
    • OpenID Connect (OIDC)

De openbare MSAL-API introduceert belangrijke wijzigingen, waaronder:

  • Een nieuw model voor toegang tot tokens:
    • ADAL biedt toegang tot tokens via de AuthenticationContext, die de server vertegenwoordigt. MSAL biedt toegang tot tokens via de PublicClientApplication, die de client vertegenwoordigt. Clientontwikkelaars hoeven geen nieuw PublicClientApplication exemplaar te maken voor elke instantie waarmee ze moeten communiceren. Er is slechts één PublicClientApplication configuratie vereist.
    • Ondersteuning voor het aanvragen van toegangstokens met behulp van bereiken naast resource-id's.
    • Ondersteuning voor incrementele toestemming. Ontwikkelaars kunnen bereiken aanvragen naarmate de gebruiker meer en meer functionaliteit in de app opent, met inbegrip van de functies die niet zijn opgenomen tijdens de app-registratie.
    • Autoriteiten worden niet meer gevalideerd tijdens runtime. In plaats daarvan declareert de ontwikkelaar een lijst met 'bekende autoriteiten' tijdens de ontwikkeling.
  • Wijzigingen in de token-API:
    • In ADAL AcquireToken() doet u eerst een stille aanvraag. Als dat niet lukt, wordt er een interactieve aanvraag ingediend. Dit gedrag heeft ertoe geleid dat sommige ontwikkelaars alleen AcquireTokenafhankelijk zijn van, waardoor de gebruiker onverwacht om referenties wordt gevraagd. MSAL vereist dat ontwikkelaars opzettelijk zijn wanneer de gebruiker een gebruikersinterfaceprompt ontvangt.
      • AcquireTokenSilent resulteert altijd in een stille aanvraag die slaagt of mislukt.
      • AcquireToken resulteert altijd in een aanvraag waarmee de gebruiker wordt gevraagd via de gebruikersinterface.
  • MSAL biedt ondersteuning voor aanmelden vanuit een standaardbrowser of een ingesloten webweergave:
    • Standaard wordt de standaardbrowser op het apparaat gebruikt. Hierdoor kan MSAL de verificatiestatus (cookies) gebruiken die mogelijk al aanwezig zijn voor een of meer aangemelde accounts. Als er geen verificatiestatus aanwezig is, resulteert verificatie tijdens autorisatie via MSAL in de verificatiestatus (cookies) die worden gemaakt ten behoeve van andere webtoepassingen die in dezelfde browser worden gebruikt.
  • Nieuw uitzonderingsmodel:
    • Uitzonderingen definiëren duidelijker het type fout dat is opgetreden en wat de ontwikkelaar moet doen om deze op te lossen.
  • MSAL ondersteunt parameterobjecten voor AcquireToken en AcquireTokenSilent aanroepen.
  • MSAL ondersteunt declaratieve configuratie voor:
    • Client-id, omleidings-URI.
    • Ingesloten versus standaardbrowser
    • Instanties
    • HTTP-instellingen, zoals time-out voor lezen en verbinding

Uw app-registratie en -migratie naar MSAL

U hoeft uw bestaande app-registratie niet te wijzigen om MSAL te gebruiken. Als u wilt profiteren van incrementele/progressieve toestemming, moet u mogelijk de registratie controleren om de specifieke bereiken te identificeren die u incrementeel wilt aanvragen. Meer informatie over bereiken en incrementele toestemming volgt.

In de app-registratie in de portal ziet u een tabblad API-machtigingen . Dit biedt een lijst met de API's en machtigingen (bereiken) waartoe uw app momenteel is geconfigureerd om toegang aan te vragen. Er wordt ook een lijst weergegeven met de bereiknamen die zijn gekoppeld aan elke API-machtiging.

Met ADAL en het Azure AD v1.0-eindpunt hebben gebruikers toestemming gegeven voor resources die ze bezitten bij eerste gebruik. Met MSAL en het Microsoft Identity Platform kunt u incrementeel toestemming aanvragen. Incrementele toestemming is handig voor machtigingen die een gebruiker kan beschouwen als een hoge bevoegdheid, of kan anderszins vragen stellen als deze niet is opgegeven met een duidelijke uitleg van waarom de machtiging is vereist. In ADAL kunnen deze machtigingen ertoe leiden dat de gebruiker zich niet meer aanmeldt bij uw app.

Tip

Gebruik incrementele toestemming om uw gebruikers aanvullende context te bieden over waarom uw app een machtiging nodig heeft.

Organisatiebeheerders kunnen toestemming geven voor machtigingen die uw toepassing vereist namens alle leden van hun organisatie. Sommige organisaties staan alleen beheerders toe om toestemming te geven voor toepassingen. Beheer toestemming vereist dat u alle API-machtigingen en bereiken opneemt die worden gebruikt door uw toepassing in de app-registratie.

Tip

Hoewel u een bereik kunt aanvragen met BEHULP van MSAL voor iets dat niet is opgenomen in uw app-registratie, raden we u aan uw app-registratie bij te werken met alle resources en bereiken waarvoor een gebruiker ooit toestemming kan verlenen.

Migreren van resource-id's naar bereiken

Verificatie en autorisatie aanvragen voor alle machtigingen voor het eerste gebruik

Als u momenteel gebruikmaakt van ADAL en u geen incrementele toestemming hoeft te gebruiken, is de eenvoudigste manier om MSAL te gaan gebruiken om een acquireToken aanvraag te doen met behulp van het nieuwe AcquireTokenParameter object en de waarde van de resource-id in te stellen.

Let op

Het is niet mogelijk om zowel bereiken als een resource-id in te stellen. Als u beide probeert in te stellen, resulteert dit in een IllegalArgumentException.

Dit resulteert in hetzelfde v1-gedrag dat u gebruikt. Alle machtigingen die zijn aangevraagd in uw app-registratie, worden tijdens hun eerste interactie door de gebruiker aangevraagd.

Machtigingen alleen verifiëren en aanvragen als dat nodig is

Als u wilt profiteren van incrementele toestemming, maakt u een lijst met machtigingen (bereiken) die uw app gebruikt vanuit uw app-registratie en organiseert u deze in twee lijsten op basis van:

  • Welke bereiken u wilt aanvragen tijdens de eerste interactie van de gebruiker met uw app tijdens het aanmelden.
  • De machtigingen die zijn gekoppeld aan een belangrijke functie van uw app die u ook moet uitleggen aan de gebruiker.

Zodra u de bereiken hebt georganiseerd, ordent u elke lijst met de resource (API) waarvoor u een token wilt aanvragen. Evenals andere bereiken die u wilt dat de gebruiker tegelijkertijd toestemming geeft.

Het parameterobject dat wordt gebruikt om uw aanvraag naar MSAL te verzenden, ondersteunt:

  • Scope: De lijst met bereiken waarvoor u autorisatie wilt aanvragen en een toegangstoken wilt ontvangen.
  • ExtraScopesToConsent: Een extra lijst met bereiken waarvoor u autorisatie wilt aanvragen terwijl u een toegangstoken aanvraagt voor een andere resource. Met deze lijst met bereiken kunt u het aantal keren beperken dat u gebruikersautorisatie moet aanvragen. Dit betekent minder gebruikersautorisatie- of toestemmingsprompts.

Migreren van AuthenticationContext naar PublicClientApplications

PublicClientApplication maken

Wanneer u MSAL gebruikt, instantieert u een PublicClientApplication. Dit object modelleert uw app-identiteit en wordt gebruikt om aanvragen te doen bij een of meer autoriteiten. Met dit object configureert u uw clientidentiteit, omleidings-URI, standaardinstantie, of u de apparaatbrowser wilt gebruiken versus ingesloten webweergave, het logboekniveau en meer.

U kunt dit object declaratief configureren met JSON, die u als een bestand opgeeft of als een resource in uw APK opslaat.

Hoewel dit object geen singleton is, wordt intern gebruikgemaakt van gedeelde Executors aanvragen voor interactieve en stille aanvragen.

Business to Business

In ADAL vereist elke organisatie van wie u toegangstokens aanvraagt een afzonderlijk exemplaar van de AuthenticationContext. In MSAL is dit geen vereiste meer. U kunt de instantie opgeven waaruit u een token wilt aanvragen als onderdeel van uw stille of interactieve aanvraag.

Migreren van autorisatievalidatie naar bekende autoriteiten

MSAL heeft geen vlag om autorisatievalidatie in of uit te schakelen. Autorisatievalidatie is een functie in ADAL en in de vroege releases van MSAL voorkomt u dat uw code tokens aanvraagt bij een mogelijk schadelijke instantie. MSAL haalt nu een lijst met autoriteiten op die bekend zijn bij Microsoft en voegt die lijst samen met de autoriteiten die u in uw configuratie hebt opgegeven.

Tip

Als u een B2C-gebruiker (Azure Business to Consumer) bent, betekent dit dat u de autorisatievalidatie niet meer hoeft uit te schakelen. Neem in plaats daarvan elk van de ondersteunde Azure AD B2C-beleidsregels op als bron in uw MSAL-configuratie.

Als u probeert een instantie te gebruiken die niet bekend is bij Microsoft en niet is opgenomen in uw configuratie, krijgt u een UnknownAuthorityException.

Logboekregistratie

U kunt nu declaratief logboekregistratie configureren als onderdeel van uw configuratie, zoals hieronder:

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

Migreren van UserInfo naar Account

In ADAL biedt het AuthenticationResult een UserInfo object dat wordt gebruikt om informatie over het geverifieerde account op te halen. De term 'gebruiker', wat een menselijke of softwareagent betekende, werd toegepast op een manier die het moeilijk maakte om te communiceren dat sommige apps één gebruiker ondersteunen (of een menselijke of softwareagent) meerdere accounts heeft.

Denk aan een bankrekening. Mogelijk hebt u meer dan één rekening bij meer dan één financiële instelling. Wanneer u een account opent, krijgt u (de gebruiker) referenties, zoals een ATM Card &pin, die worden gebruikt voor toegang tot uw saldo, factuurbetalingen, enzovoort, voor elke rekening. Deze referenties kunnen alleen worden gebruikt bij de financiële instelling die ze heeft uitgegeven.

Naar analogie, zoals accounts bij een financiële instelling, worden accounts in het Microsoft Identity Platform geopend met behulp van referenties. Deze referenties zijn geregistreerd bij of uitgegeven door Microsoft. Of door Microsoft namens een organisatie.

Waar het Microsoft Identity Platform verschilt van een financiële instelling, is dat het Microsoft Identity Platform een framework biedt waarmee een gebruiker één account en de bijbehorende referenties kan gebruiken om toegang te krijgen tot resources die deel uitmaken van meerdere personen en organisaties. Dit is vergelijkbaar met het gebruik van een kaart die door de ene bank is uitgegeven, bij een andere financiële instelling. Dit werkt omdat alle betrokken organisaties gebruikmaken van het Microsoft Identity Platform, waarmee één account kan worden gebruikt in meerdere organisaties. Hier volgt een voorbeeld:

Sam werkt voor Contoso.com, maar beheert virtuele Azure-machines die deel uitmaken van Fabrikam.com. Sam moet gemachtigd zijn om toegang te krijgen tot de virtuele machines van Fabrikam. Deze toegang kan worden verleend door Sam's account toe te voegen aan Fabrikam.com en zijn account een rol te geven waarmee hij met de virtuele machines kan werken. Dit wordt gedaan met Azure Portal.

Als u sam's Contoso.com-account toevoegt als lid van Fabrikam.com, wordt er een nieuwe record gemaakt in de Microsoft Entra-id van Fabrikam.com voor Sam. Sam's record in Microsoft Entra ID wordt een gebruikersobject genoemd. In dit geval wijst dat gebruikersobject terug naar het gebruikersobject van Sam in Contoso.com. Het Fabrikam-gebruikersobject van Sam is de lokale weergave van Sam en wordt gebruikt voor het opslaan van informatie over het account dat is gekoppeld aan Sam in de context van Fabrikam.com. In Contoso.com is Sam's titel Senior DevOps Consultant. In Fabrikam is Sam's titel Aannemer-Virtual Machines. In Contoso.com is Sam niet verantwoordelijk of gemachtigd om virtuele machines te beheren. In Fabrikam.com is dat zijn enige functie. Maar Sam heeft nog maar één set referenties om bij te houden. Dit zijn de referenties die zijn uitgegeven door Contoso.com.

Zodra een geslaagde acquireToken aanroep is gedaan, ziet u een verwijzing naar een IAccount object dat in latere acquireTokenSilent aanvragen kan worden gebruikt.

IMultiTenantAccount

Als u een app hebt die toegang heeft tot claims over een account van elk van de tenants waarin het account wordt weergegeven, kunt u objecten casten IAccount naar IMultiTenantAccount. Deze interface biedt een kaart van ITenantProfiles, gesleuteld op tenant-id, waarmee u toegang hebt tot de claims die deel uitmaken van het account in elk van de tenants waarvan u een token hebt aangevraagd ten opzichte van het huidige account.

De claims in de hoofdmap van de IAccount en IMultiTenantAccount bevatten altijd de claims van de thuistenant. Als u nog geen aanvraag hebt ingediend voor een token binnen de tenant thuis, is deze verzameling leeg.

Andere wijzigingen

De nieuwe AuthenticationCallback gebruiken

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

Migreren naar de nieuwe uitzonderingen

In ADAL is er één type uitzondering, AuthenticationExceptiondat een methode bevat voor het ophalen van de ADALError enum-waarde. In MSAL is er een hiërarchie van uitzonderingen en elk heeft een eigen set gekoppelde specifieke foutcodes.

Uitzondering Beschrijving
MsalArgumentException Gegenereerd als een of meer invoerargumenten ongeldig zijn.
MsalClientException Gegenereerd als de fout clientzijde is.
MsalDeclinedScopeException Gegenereerd als een of meer aangevraagde bereiken zijn geweigerd door de server.
MsalException Standaard ingeschakelde uitzondering die is gegenereerd door MSAL.
MsalIntuneAppProtectionPolicyRequiredException Gegenereerd als mamCA-beveiligingsbeleid is ingeschakeld voor de resource.
MsalServiceException Er is een fout opgetreden als de fout aan de serverzijde is.
MsalUiRequiredException Gegenereerd als het token niet op de achtergrond kan worden vernieuwd.
MsalUserCancelException Gegenereerd als de gebruiker de verificatiestroom heeft geannuleerd.

ADALError naar MsalException-vertaling

Als u deze fouten in ADAL onderscheppen... ... ondervang deze MSAL-uitzonderingen:
Geen equivalente 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
Geen equivalente ADALError MsalDeclinedScopeException
  • ADALError.APP_PACKAGE_NAME_NOT_FOUND
  • ADALError.BROKER_APP_VERIFICATION_FAILED
  • ADALError.PACKAGE_NAME_NOT_FOUND
 MsalException
Geen equivalente ADALError MsalIntuneAppProtectionPolicyRequiredException
  • ADALError.SERVER_ERROR
  • ADALError.SERVER_INVALID_REQUEST
 MsalServiceException
  • ADALError.AUTH_REFRESH_FAILED_PROMPT_NOT_ALLOWED
 MsalUiRequiredException
Geen equivalente ADALError MsalUserCancelException

ADAL-logboekregistratie naar MSAL-logboekregistratie

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