Migrera program till MSAL för iOS och macOS

Azure Active Directory-autentiseringsbiblioteket (ADAL Objective-C) skapades för att fungera med Microsoft Entra konton via v1.0-slutpunkten.

Microsoft Authentication Library för iOS och macOS (MSAL) har utformats för att fungera med alla Microsoft-identitetstyper, till exempel Microsoft Entra-konton, personliga Microsoft-konton och Azure AD B2C-konton, via Microsofts identitetsplattform (tidigare Azure AD v2.0-slutpunkten).

Microsofts identitetsplattform har några viktiga skillnader med Azure AD v1.0. Den här artikeln belyser dessa skillnader och ger vägledning för att migrera en app från ADAL till MSAL.

Skillnader mellan ADAL- och MSAL-appfunktioner

Vem kan logga in

  • ADAL stöder endast arbets- och skolkonton – även kallat Microsoft Entra konton.
  • MSAL stöder personliga Microsoft-konton (MSA-konton) som Hotmail.com, Outlook.com och Live.com.
  • MSAL stöder arbets- och skolkonton och Azure AD B2C-konton.

Standardefterlevnad

  • Microsofts identitetsplattform följer OAuth 2.0- och OpenId Connect-standarder.
  • Med Microsofts identitetsplattform kan du begära behörigheter dynamiskt. Appar kan bara be om behörigheter efter behov och begära mer när appen behöver dem. Mer information finns i behörigheter och medgivande.

Skillnader mellan ADAL- och MSAL-bibliotek

DET offentliga MSAL-API:et återspeglar några viktiga skillnader mellan Azure AD v1.0 och Microsofts identitetsplattform.

MSALPublicClientApplication i stället för ADAuthenticationContext

ADAuthenticationContext är det första objektet som en ADAL-app skapar. Den representerar en instansiering av ADAL. Appar skapar en ny instans av ADAuthenticationContext för varje kombination av Microsoft Entra-moln och klientorganisation (auktoritet). ADAuthenticationContext Samma sak kan användas för att hämta token för flera offentliga klientprogram.

I MSAL sker den huvudsakliga interaktionen via ett MSALPublicClientApplication objekt som modelleras efter OAuth 2.0 Public Client. En instans av MSALPublicClientApplication kan användas för att interagera med flera Microsoft Entra-moln och klientorganisationer utan att behöva skapa en ny instans för varje auktoritet. För de flesta appar räcker det med en MSALPublicClientApplication instans.

Omfång i stället för resurser

I ADAL var en app tvungen att ange en resurs-identifierare som https://graph.microsoft.com för att hämta token från Azure AD v1.0-slutpunkten. En resurs kan definiera ett antal omfång, eller oAuth2Permissions i appmanifestet, som den förstår. Detta tillät klientappar att begära token från den resursen för en viss uppsättning omfång som fördefinierades under appregistreringen.

I MSAL tillhandahåller appar i stället för en enda resursidentifierare en uppsättning omfång per begäran. Ett omfång är en resursidentifierare följt av ett behörighetsnamn i formuläret resurs/behörighet. Till exempel: https://graph.microsoft.com/user.read

Det finns två sätt att tillhandahålla omfång i MSAL:

  • Ange en lista över alla behörigheter som dina appar behöver. Ett exempel:

    @[@"https://graph.microsoft.com/directory.read", @"https://graph.microsoft.com/directory.write"]

    I det här fallet begär appen behörigheterna directory.read och directory.write . Användaren uppmanas att godkänna dessa behörigheter om de inte har samtyckt till dem tidigare för den här appen. Programmet kan också få ytterligare behörigheter som användaren redan har samtyckt till för programmet. Användaren uppmanas endast att godkänna nya behörigheter eller behörigheter som inte har beviljats.

  • Omfånget /.default .

Det här är det inbyggda omfånget för varje program. Den refererar till den statiska listan över behörigheter som konfigurerades när programmet registrerades. Dess beteende liknar det för resource. Detta kan vara användbart vid migrering för att säkerställa att en liknande uppsättning behörigheter och användarupplevelse bibehålls.

Om du vill använda omfånget /.default lägger du till resursidentifieraren /.default . Till exempel: https://graph.microsoft.com/.default. Om din resurs slutar med ett snedstreck (/) bör du ändå lägga till /.default, inklusive det inledande snedstrecket, vilket resulterar i ett scope som innehåller ett dubbelt snedstreck (//).

Du kan läsa mer information om hur du använder omfånget "/.default" i behörigheter och omfång.

Stöd för olika WebView-typer och webbläsare

ADAL stöder endast UIWebView/WKWebView för iOS och WebView för macOS. MSAL för iOS har stöd för fler alternativ för att visa webbinnehåll när du begär en auktoriseringskod och stöder inte längre UIWebView, vilket kan förbättra användarupplevelsen och säkerheten.

Som standard använder MSAL på iOS ASWebAuthenticationSession, vilket är den webbkomponent som Apple rekommenderar för autentisering på iOS 12+-enheter. Det ger fördelar med enkel inloggning (SSO) via cookiedelning mellan appar och Safari-webbläsaren.

Du kan välja att använda en annan webbkomponent beroende på appkrav och vilken slutanvändarupplevelse du vill använda. Se webbvytyper som stöds för fler alternativ.

När du migrerar från ADAL till MSAL ger WKWebView den användarupplevelse som mest liknar ADAL på iOS och macOS. Vi rekommenderar att du migrerar till ASWebAuthenticationSession på iOS, om möjligt. För macOS rekommenderar vi att du använder WKWebView.

Skillnader i API för kontohantering

När du anropar ADAL-metoderna acquireToken() eller acquireTokenSilent()får du ett ADUserInformation objekt som innehåller en lista med anspråk från id_token det som representerar kontot som autentiseras. Dessutom returnerar ADUserInformation ett userId baserat på upn-anspråket. Efter det inledande interaktiva tokenförvärvet förutsätter ADAL att utvecklaren anger userId i alla tysta anrop.

ADAL tillhandahåller inte något API för att hämta kända användaridentiteter. Den förlitar sig på appen för att spara och hantera dessa konton.

MSAL tillhandahåller en uppsättning API:er för att lista alla konton som är kända för MSAL utan att behöva hämta en token.

Precis som ADAL returnerar MSAL kontoinformation som innehåller en lista över anspråk från id_token. Det är en del av MSALAccount objektet inuti objektet MSALResult .

MSAL tillhandahåller en uppsättning API:er för att ta bort konton, vilket gör de borttagna kontona otillgängliga för appen. När kontot har tagits bort uppmanar senare tokenförvärvsanrop användaren att göra ett interaktivt tokenförvärv. Kontoborttagning gäller endast för klientprogrammet som startade det och tar inte bort kontot från de andra apparna som körs på enheten eller från systemwebbläsaren. Detta säkerställer att användaren fortsätter att ha en SSO-upplevelse på enheten även efter att ha loggat ut från en enskild app.

Dessutom returnerar MSAL även en kontoidentifierare som kan användas för att begära en token tyst senare. Kontoidentifieraren (tillgänglig via identifier egenskapen i MSALAccount objektet) kan dock inte visas och du kan inte anta vilket format den finns i och du bör inte heller försöka tolka eller parsa den.

Migrera kontocachen

Vid migrering från ADAL lagrar appar normalt ADAL:s userId, som saknar den identifier som krävs av MSAL. Som ett engångsmigreringssteg kan en app köra frågor mot ett MSAL-konto med hjälp av ADAL:s userId med följande API:

- (nullable MSALAccount *)accountForUsername:(nonnull NSString *)username error:(NSError * _Nullable __autoreleasing * _Nullable)error;

Det här API:et läser både MSAL:s och ADAL:s cacheminne för att hitta kontot med ADAL userId (UPN).

Om kontot hittas bör utvecklaren använda det kontot för att hämta en token utan användarinteraktion. Den första tysta tokenhämtningen kommer i praktiken att uppgradera kontot, och utvecklaren kommer att få en MSAL-kompatibel kontoidentifierare i MSAL-resultatet (identifier). Därefter ska endast identifier användas för kontosökningar med hjälp av följande API:

- (nullable MSALAccount *)accountForIdentifier:(nonnull NSString *)identifier error:(NSError * _Nullable __autoreleasing * _Nullable)error;

Även om det är möjligt att fortsätta använda ADAL:s userId för alla åtgärder i MSAL, omfattas userId av flera begränsningar eftersom det baseras på UPN, vilket leder till en dålig användarupplevelse. Om UPN till exempel ändras måste användaren logga in igen. Vi rekommenderar att alla appar använder det icke-visningsbara kontot identifier för alla åtgärder.

Läs mer om migrering av cachetillstånd.

Ändringar i tokenförvärv

MSAL introducerar vissa ändringar i tokeninsamlingsanropet:

  • Precis som ADAL acquireTokenSilent resulterar det alltid i en tyst begäran.
  • Till skillnad från ADAL acquireToken resulterar det alltid i användaråtgärdsbart användargränssnitt antingen via webbvyn eller Microsoft Authenticator appen. Beroende på tillståndet för enkel inloggning i webview/Microsoft Authenticator kan användaren uppmanas att ange sina autentiseringsuppgifter.
  • I ADAL försöker acquireToken med AD_PROMPT_AUTO först hämta token i bakgrunden och visar bara ett användargränssnitt om den tysta hämtningen misslyckas. I MSAL kan den här logiken uppnås genom att först anropa acquireTokenSilent och endast anropa acquireToken om tyst förvärv misslyckas. På så sätt kan utvecklare anpassa användarupplevelsen innan de påbörjar anskaffning av interaktiva token.

Fel vid hantering av skillnader

MSAL ger mer klarhet mellan fel som kan hanteras av din app och de som kräver åtgärder av användaren. Det finns ett begränsat antal fel som utvecklaren måste hantera:

  • MSALErrorInteractionRequired: Användaren måste göra en interaktiv begäran. Detta kan orsakas av olika orsaker, till exempel en autentiseringssession som har upphört att gälla, principen för villkorsstyrd åtkomst har ändrats, en uppdateringstoken har upphört att gälla eller har återkallats, det finns inga giltiga token i cacheminnet och så vidare.
  • MSALErrorServerDeclinedScopes: Begäran slutfördes inte helt och vissa omfång har inte beviljats åtkomst. Detta kan orsakas av att en användare avböjer medgivande till ett eller flera omfång.

Det är valfritt att MSALError hantera alla andra fel i listan. Du kan använda informationen i dessa fel för att förbättra användarupplevelsen.

Mer information om MSAL-felhantering finns i Hantera undantag och fel med MSAL .

Stöd för mäklare

MSAL, som börjar med version 0.3.0, ger stöd för asynkron autentisering med hjälp av Microsoft Authenticator-appen. Microsoft Authenticator möjliggör även stöd för scenarier med villkorsstyrd åtkomst. Exempel på scenarier med villkorsstyrd åtkomst är enhetsefterlevnadsprinciper som kräver att användaren registrerar enheten via Intune eller registrerar sig med Microsoft Entra ID för att hämta en token. Och principer för villkorsstyrd åtkomst för hantering av mobila applikationer (MAM), som kräver bevis på efterlevnad innan appen kan få en token.

Så här aktiverar du broker för ditt program:

  1. Registrera ett broker-kompatibelt omdirigerings-URI-format för programmet. Det broker-kompatibla omdirigerings-URI-formatet är msauth.<app.bundle.id>://auth. Ersätt <app.bundle.id> med programmets paket-ID. Om du migrerar från ADAL och ditt program redan var koordinatorkompatibelt finns det inget extra du behöver göra. Din tidigare omdirigerings-URI är helt kompatibel med MSAL, så du kan gå vidare till steg 3.

  2. Lägg till programmets omdirigerings-URI-schema i filen info.plist. För standard-MSAL-omdirigerings-URI:n är formatet msauth.<app.bundle.id>. Ett exempel:

    <key>CFBundleURLSchemes</key>
<array>
    <string>msauth.<app.bundle.id></string>
</array>

  3. Lägg till följande scheman i appens Info.plist under LSApplicationQueriesSchemes:

    <key>LSApplicationQueriesSchemes</key>
<array>
     <string>msauthv2</string>
     <string>msauthv3</string>
</array>

  4. Lägg till följande i din AppDelegate.m-fil för att hantera callbackanrop: Objective-C:

    - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)options`
{
    return [MSALPublicClientApplication handleMSALResponse:url sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

    Swift

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

Företag till företag (B2B)

I ADAL skapar du separata instanser av ADAuthenticationContext för varje klientorganisation som appen begär token för. Detta är inte längre ett krav i MSAL. I MSAL kan du skapa en enda instans av MSALPublicClientApplication och använda den för alla Microsoft Entra moln och organisation genom att ange en annan utfärdare för acquireToken och acquireTokenSilent-anrop.

SSO tillsammans med andra SDK:er

MSAL för iOS kan uppnå enkel inloggning via en enhetlig cache med ADAL Objective-C 2.7.x+.

Enkel inloggning uppnås via delning av iOS-nyckelringar och är endast tillgängligt mellan appar som publicerats från samma Apple Developer-konto.

SSO via iOS-nyckelringsdelning är den enda typen av tyst SSO.

På macOS kan MSAL uppnå enkel inloggning (SSO) med andra iOS- och macOS-baserade program som använder MSAL samt Objective-C-baserade program som använder ADAL.

MSAL på iOS har också stöd för två andra typer av enkel inloggning:

  • Enkel inloggning via webbläsaren. MSAL för iOS stöder ASWebAuthenticationSession, vilket ger enkel inloggning via cookies som delas mellan andra appar på enheten och specifikt Safari-webbläsaren.
  • SSO via en autentiseringsförmedlare. På en iOS-enhet fungerar Microsoft Authenticator som autentiseringskoordinator. Den kan följa principer för villkorsstyrd åtkomst som att kräva en kompatibel enhet och tillhandahåller enkel inloggning för registrerade enheter. MSAL SDK:er från och med version 0.3.0 har stöd för en broker som standard.

Intune MAM SDK

Intune MAM SDK stöder MSAL för iOS från och med version 11.1.2

MSAL och ADAL i samma app

ADAL version 2.7.0 och senare kan inte samexistera med MSAL i samma program. Den främsta orsaken är den gemensamma undermodulens gemensamma kod. Eftersom Objective-C inte stöder namnområden finns det två instanser av samma klass om du lägger till både ADAL- och MSAL-ramverk i ditt program. Det finns ingen garanti för vilken som väljs vid körning. Om båda SDK:erna använder samma version av klassen som står i konflikt kan appen fortfarande fungera. Men om det är en annan version kan din app uppleva oväntade krascher som är svåra att diagnostisera.

Det går inte att köra ADAL och MSAL i samma produktionsprogram. Men om du bara testar och migrerar dina användare från ADAL Objective-C till MSAL för iOS och macOS kan du fortsätta använda ADAL Objective-C 2.6.10. Det är den enda versionen som fungerar med MSAL i samma program. Det kommer inte att finnas några nya funktionsuppdateringar för den här ADAL-versionen, så den bör endast användas för migrering och testning. Din app bör inte förlita sig på ADAL- och MSAL-samexistens på lång sikt.

ADAL- och MSAL-samexistens i samma program stöds inte. ADAL- och MSAL-samexistens mellan flera program stöds fullt ut.

Praktiska migreringssteg

Migrering av appregistrering

Du behöver inte ändra ditt befintliga Microsoft Entra program för att växla till MSAL och aktivera Microsoft Entra konton. Men om ditt ADAL-baserade program inte stöder asynkron autentisering måste du registrera en ny omdirigerings-URI för programmet innan du kan växla till MSAL.

Omdirigerings-URI:n ska vara i följande format: msauth.<app.bundle.id>://auth. Ersätt <app.bundle.id> med programmets paket-ID. Ange omdirigerings-URI:n i Microsoft Entra administrationscenter.

Endast för iOS måste en ytterligare omdirigerings-URI registreras i ditt program och Microsoft Entra administrationscenter i följande format för att stödja certbaserad autentisering: msauth://code/<broker-redirect-uri-in-url-encoded-form>. Till exempel: msauth://code/msauth.com.microsoft.mybundleId%3A%2F%2Fauth

Vi rekommenderar att alla appar registrerar båda omdirigerings-URI:er.

Om du vill lägga till stöd för inkrementellt medgivande väljer du DE API:er och behörigheter som appen har konfigurerats för att begära åtkomst till i din appregistrering under fliken API-behörigheter .

Om du migrerar från ADAL och vill stödja både Microsoft Entra ID- och MSA-konton måste din befintliga programregistrering uppdateras för att stödja båda. Vi rekommenderar inte att du uppdaterar din befintliga produktionsapp för att stödja både Microsoft Entra ID och MSA direkt. Skapa i stället ett annat klient-ID som stöder både Microsoft Entra ID och MSA för testning, och när du har kontrollerat att alla scenarier fungerar uppdaterar du den befintliga appen.

Lägga till MSAL i din app

Du kan lägga till MSAL SDK i din app med hjälp av det pakethanteringsverktyg som du föredrar. Se detaljerade instruktioner här.

Uppdatera appens Info.plist-fil

Endast för iOS lägger du till programmets omdirigerings-URI-schema i filen info.plist. För appar som är kompatibla med ADAL-broker borde det redan finnas där. Standardschemat för MSAL-omdirigerings-URI är i formatet: msauth.<app.bundle.id>.

<key>CFBundleURLSchemes</key>
<array>
    <string>msauth.<app.bundle.id></string>
</array>

Lägg till följande scheman i appens Info.plist under LSApplicationQueriesSchemes.

<key>LSApplicationQueriesSchemes</key>
<array>
     <string>msauthv2</string>
     <string>msauthv3</string>
</array>

Uppdatera din AppDelegate-kod

För endast iOS lägger du till följande i din AppDelegate.m-fil:

Objective-C:

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)options`
{
    return [MSALPublicClientApplication handleMSALResponse:url sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

Swift

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

Om du använder Xcode 11 bör du placera MSAL-återanrop i filen i SceneDelegate stället. Om du stöder både UISceneDelegate och UIApplicationDelegate för kompatibilitet med äldre iOS måste MSAL-callback läggas till i båda filerna.

Objective-C:

 - (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
 {
     UIOpenURLContext *context = URLContexts.anyObject;
     NSURL *url = context.URL;
     NSString *sourceApplication = context.options.sourceApplication;
     
     [MSALPublicClientApplication handleMSALResponse:url sourceApplication:sourceApplication];
 }

Swift

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        
        guard let urlContext = URLContexts.first else {
            return
        }
        
        let url = urlContext.url
        let sourceApp = urlContext.options.sourceApplication
        
        MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApp)
    }

Detta gör att MSAL kan hantera svar från broker och webbkomponent. Detta var inte nödvändigt i ADAL eftersom den automatiskt ”swizzlade” App Delegate-metoder. Att lägga till det manuellt är mindre felbenäget och ger programmet mer kontroll.

Aktivera cachelagring av token

Som standard cachelagrar MSAL appens token i iOS- eller macOS-nyckelringen.

Så här aktiverar du cachelagring av token:

  1. Se till att appen är korrekt signerad
  2. Gå till projektinställningarna för ditt Xcode-projekt >fliken Funktioner>Aktivera nyckelringsdelning
  3. Klicka + och ange följande nyckelringsgrupper : 3.a För iOS anger du com.microsoft.adalcache 3.b För macOS-retur com.microsoft.identity.universalstorage

Skapa MSALPublicClientApplication och växla till sina acquireToken- och acquireTokeSilent-anrop

Du kan skapa MSALPublicClientApplication med hjälp av följande kod:

Objective-C:

NSError *error = nil;
MSALPublicClientApplicationConfig *configuration = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"];
    
MSALPublicClientApplication *application =
[[MSALPublicClientApplication alloc] initWithConfiguration:configuration
                                                     error:&error];

Swift

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
do {
  let application = try MSALPublicClientApplication(configuration: config)
  // continue on with application
            
} catch let error as NSError {
  // handle error here
}

Anropa sedan kontohanterings-API:et för att se om det finns några konton i cacheminnet:

Objective-C:

NSString *accountIdentifier = nil /*previously saved MSAL account identifier */;
NSError *error = nil;
MSALAccount *account = [application accountForIdentifier:accountIdentifier error:&error];

Swift

// definitions that need to be initialized
let application: MSALPublicClientApplication!
let accountIdentifier: String! /*previously saved MSAL account identifier */

do {
  let account = try application.account(forIdentifier: accountIdentifier)
  // continue with account usage
} catch let error as NSError {
  // handle error here
}

eller läsa alla redogörelser:

Objective-C:

NSError *error = nil;
NSArray<MSALAccount *> *accounts = [application allAccounts:&error];

Swift

let application: MSALPublicClientApplication!
do {
  let accounts = try application.allAccounts()
  // continue with account usage
} catch let error as NSError {
  // handle error here
}

Om ett konto hittas anropar du MSAL acquireTokenSilent API:

Objective-C:

MSALSilentTokenParameters *silentParameters = [[MSALSilentTokenParameters alloc] initWithScopes:@[@"<your-resource-here>/.default"] account:account];
    
[application acquireTokenSilentWithParameters:silentParameters
                              completionBlock:^(MSALResult *result, NSError *error)
{
    if (result)
    {
        NSString *accessToken = result.accessToken;
        // Use your token
    }
    else
    {
        // Check the error
        if ([error.domain isEqual:MSALErrorDomain] && error.code == MSALErrorInteractionRequired)
        {
            // Interactive auth will be required
        }
            
        // Other errors may require trying again later, or reporting authentication problems to the user
    }
}];

Swift

let application: MSALPublicClientApplication!
let account: MSALAccount!
        
let silentParameters = MSALSilentTokenParameters(scopes: ["<your-resource-here>/.default"], 
                                                 account: account)
application.acquireTokenSilent(with: silentParameters) {
  (result: MSALResult?, error: Error?) in
  if let accessToken = result?.accessToken {
     // use accessToken
  }
  else {
    // Check the error
    guard let error = error else {
      assert(true, "callback should contain a valid result or error")
      return
    }
    
    let nsError = error as NSError
    if (nsError.domain == MSALErrorDomain
        && nsError.code == MSALError.interactionRequired.rawValue) {
      // Interactive auth will be required
    }
                
    // Other errors may require trying again later, or reporting authentication problems to the user
  }
}

Nästa steg

Läs mer om autentiseringsflöden och programscenarier

  • Last updated on