Migratiehandleiding voor ADAL naar MSAL voor Android

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 Active Directory v1.0-eindpunt. De Microsoft Authentication Library (MSAL) werkt met het Microsoft identity platform-voorheen bekend als het Azure Active Directory v2.0-eindpunt. De Microsoft identity platform verschilt van Azure Active Directory v1.0 in dat geval:

Ondersteunt:

  • Organisatie-id (Azure Active Directory)

  • 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 AuthenticationContextserver. 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 wanneer de gebruiker toegang heeft tot meer en meer functionaliteit in de app, inclusief de bereiken 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() maakt 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, wat ertoe heeft geleid dat 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 die de gebruiker vraagt 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 verificatiestatus (cookies) 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-eindpunt heeft de gebruiker toestemming gegeven voor resources die ze bezitten bij eerste gebruik. Met MSAL en de Microsoft identity platform kunt u incrementeel toestemming aanvragen. Incrementele toestemming is handig voor machtigingen die een gebruiker kan overwegen om hoge bevoegdheden te krijgen, of kan anders vragen stellen als deze niet is opgegeven met een duidelijke uitleg over 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 nodig heeft 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 uw app-registratie.

Tip

Hoewel u een bereik kunt aanvragen met 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

Autorisatie verifiëren en aanvragen voor alle machtigingen voor het eerste gebruik

Als u momenteel ADAL gebruikt 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 resource-id-waarde in te stellen.

Waarschuwing

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 de eerste interactie van 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 ordent 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 aan de gebruiker moet uitleggen.

Zodra u de bereiken hebt georganiseerd, moet u elke lijst organiseren met de resource (API) waarvoor u een token wilt aanvragen. Evenals andere bereiken die u de gebruiker tegelijkertijd wilt autoriseren.

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 dat er minder gebruikersautorisatie- of toestemmingsprompts zijn.

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 aan een of meer autoriteiten. Met dit object configureert u uw clientidentiteit, omleidings-URI, standaardinstantie, of u de apparaatbrowser versus ingesloten webweergave, het logboekniveau en meer wilt gebruiken.

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 instantievalidatie naar bekende autoriteiten

MSAL heeft geen vlag voor het in- of uitschakelen van autorisatievalidatie. Instantievalidatie is een functie in ADAL en in de vroege releases van MSAL, waarmee wordt voorkomen dat uw code tokens aanvraagt van een mogelijk schadelijke instantie. MSAL haalt nu een lijst op met autoriteiten 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, hoeft u de validatie van de instantie niet meer uit te schakelen. Neem in plaats daarvan elk van de ondersteunde Azure AD B2C-beleid op als autoriteiten in uw MSAL-configuratie.

Als u een instantie probeert 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.

Overweeg 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 pincode voor een ATM-kaart & , die worden gebruikt om toegang te krijgen tot uw saldo, factuurbetalingen, enzovoort, voor elk account. 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 rekeningen in de Microsoft identity platform geopend met behulp van referenties. Deze referenties worden geregistreerd bij of uitgegeven door Microsoft. Of door Microsoft namens een organisatie.

Wanneer de Microsoft identity platform verschilt van een financiële instelling, is dat de Microsoft identity platform een kader biedt waarmee een gebruiker één account en de bijbehorende referenties kan gebruiken voor toegang tot resources die deel uitmaken van meerdere personen en organisaties. Dit is als het kunnen gebruiken van een kaart die door de ene bank is uitgegeven, bij nog een andere financiële instelling. Dit werkt omdat alle betrokken organisaties de Microsoft identity platform gebruiken, waardoor één account in meerdere organisaties kan worden gebruikt. 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 zou gebeuren met de Azure Portal.

Als u sam's Contoso.com-account toevoegt als lid van Fabrikam.com, wordt er een nieuwe record gemaakt in De Azure Active Directory voor Sam van Fabrikam.com. De record van Sam in Azure Active Directory wordt een gebruikersobject genoemd. In dit geval verwijst 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 Contractor-Virtual Machines. In Contoso.com is Sam niet verantwoordelijk, noch gemachtigd om virtuele machines te beheren. In Fabrikam.com is dat zijn enige functie. Maar Sam heeft nog steeds slechts één set referenties om bij te houden. Dit zijn de referenties die zijn uitgegeven door Contoso.com.

Zodra een geslaagde acquireToken aanroep is uitgevoerd, 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 tot het account behoren 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 voor een token binnen de tenant voor thuis hebt ingediend, 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 opsommingswaarde. In MSAL is er een hiërarchie van uitzonderingen en elk heeft een eigen set gekoppelde specifieke foutcodes.

Uitzondering Description
MsalArgumentException Gegenereerd als een of meer invoerargumenten ongeldig zijn.
MsalClientException Gegenereerd als de fout aan de 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 het MAMCA-beveiligingsbeleid is ingeschakeld voor de resource.
MsalServiceException Gegenereerd als de fout zich aan de serverzijde bevindt.
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 opslaat... ... deze MSAL-uitzonderingen ondervangen:
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
}