Migrowanie aplikacji do biblioteki MSAL dla systemów iOS i macOS

Biblioteka Azure Active Directory Authentication Library (ADAL Objective-C) została utworzona do współpracy z kontami Microsoft Entra za pośrednictwem punktu końcowego v1.0.

Biblioteka Microsoft Authentication Library dla systemów iOS i macOS (MSAL) została zaprojektowana do współpracy ze wszystkimi tożsamościami firmy Microsoft, takimi jak konta Microsoft Entra, osobiste konta Microsoft oraz konta Azure AD B2C, za pośrednictwem platformy tożsamości firmy Microsoft (dawniej punkt końcowy Azure AD v2.0).

Platforma tożsamości firmy Microsoft różni się pod kilkoma kluczowymi względami od Azure AD w wersji 1.0. Ten artykuł wyróżnia te różnice i zawiera wskazówki dotyczące migrowania aplikacji z biblioteki ADAL do biblioteki MSAL.

Różnice w możliwościach aplikacji ADAL i MSAL

ADAL obsługuje tylko konta służbowe i szkolne — nazywane też kontami Microsoft Entra.
Biblioteka MSAL obsługuje osobiste konta Microsoft (konta MSA), takie jak Hotmail.com, Outlook.com i Live.com.
Biblioteka MSAL obsługuje konta służbowe i szkolne oraz konta Azure AD B2C.

Zgodność ze standardami

Platforma tożsamości Microsoft jest zgodna ze standardami OAuth 2.0 i OpenId Connect.

Platforma tożsamości Microsoft umożliwia dynamiczne żądanie uprawnień. Aplikacje mogą żądać uprawnień tylko w razie potrzeby i żądać więcej, ponieważ aplikacja ich potrzebuje. Aby uzyskać więcej informacji, zobacz uprawnienia i zgoda.

Różnice między bibliotekami ADAL i MSAL

Publiczny interfejs API biblioteki MSAL odzwierciedla kilka kluczowych różnic między usługą Azure AD w wersji 1.0 a Platforma tożsamości Microsoft.

MSALPublicClientApplication zamiast ADAuthenticationContext

ADAuthenticationContext jest pierwszym obiektem, który tworzy aplikacja ADAL. Reprezentuje instancję ADAL. Aplikacje tworzą nowe wystąpienie ADAuthenticationContext dla każdej kombinacji Microsoft Entra chmury i dzierżawy (urzędu). To samo ADAuthenticationContext może służyć do pobierania tokenów dla wielu publicznych aplikacji klienckich.

W bibliotece MSAL główna interakcja odbywa się za pomocą obiektu MSALPublicClientApplication, który jest wzorowany na kliencie publicznym OAuth 2.0. Jedno wystąpienie MSALPublicClientApplication może służyć do komunikacji z wieloma chmurami Microsoft Entra oraz dzierżawcami, bez konieczności tworzenia nowego wystąpienia dla każdego urzędu uwierzytelniającego. W przypadku większości aplikacji wystarczy jedno MSALPublicClientApplication wystąpienie.

Zakresy zamiast zasobów

W ADAL aplikacja musiała podać identyfikator zasobu, taki jak https://graph.microsoft.com, aby uzyskać tokeny z punktu końcowego Azure AD v1.0. Zasób może definiować pewną liczbę zakresów lub oAuth2Permissions w manifeście aplikacji, które obsługuje. Dzięki temu aplikacje klienckie mogą żądać tokenów z tego zasobu dla określonego zestawu zakresów wstępnie zdefiniowanych podczas rejestracji aplikacji.

W usłudze MSAL zamiast pojedynczego identyfikatora zasobu aplikacje udostępniają zestaw zakresów na żądanie. Zakres to identyfikator zasobu, po którym następuje nazwa uprawnień w formularzu zasób/uprawnienie. Na przykład https://graph.microsoft.com/user.read

Istnieją dwa sposoby określania zakresów w bibliotece MSAL:

Podaj listę wszystkich uprawnień wymaganych przez aplikacje. Przykład:

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

W takim przypadku aplikacja żąda uprawnień directory.read i directory.write. Użytkownik zostanie poproszony o wyrażenie zgody na te uprawnienia, jeśli wcześniej nie wyraził na nie zgody dla tej aplikacji. Aplikacja może również otrzymać dodatkowe uprawnienia, na które użytkownik wyraził już zgodę na aplikację. Użytkownik będzie monitowany tylko o zgodę na nowe uprawnienia lub uprawnienia, które nie zostały przyznane.
Zakres /.default.

Jest to wbudowany zakres dla każdej aplikacji. Odwołuje się ona do statycznej listy uprawnień skonfigurowanych podczas rejestrowania aplikacji. Jego zachowanie jest podobne do zachowania resource. Może to być przydatne podczas migracji, aby upewnić się, że zachowany jest podobny zestaw zakresów i środowiska użytkownika.

Aby użyć zakresu /.default, dołącz /.default do identyfikatora zasobu. Na przykład: https://graph.microsoft.com/.default. Jeśli zasób kończy się ukośnikiem (/), nadal należy dodać /.default, łącznie z poprzedzającym go ukośnikiem, w wyniku czego powstaje zakres zawierający podwójny ukośnik (//).

Więcej informacji na temat korzystania z zakresu "/.default" można znaleźć w sekcji Uprawnienia i zakresy.

Obsługa różnych typów i przeglądarek WebView

ADAL obsługuje tylko UIWebView/WKWebView w systemie iOS oraz WebView w systemie macOS. Biblioteka MSAL dla systemu iOS oferuje więcej opcji wyświetlania treści internetowych podczas żądania kodu autoryzacji i nie obsługuje już UIWebView; co może poprawić komfort użytkowania i bezpieczeństwo.

Domyślnie biblioteka MSAL w systemie iOS używa ASWebAuthenticationSession, czyli komponentu internetowego zalecanego przez Apple do uwierzytelniania na urządzeniach z systemem iOS 12 i nowszym. Zapewnia ona korzyści z logowania jednokrotnego (SSO) za pośrednictwem udostępniania plików cookie między aplikacjami a przeglądarką Safari.

Możesz użyć innego składnika internetowego w zależności od wymagań aplikacji i środowiska użytkownika końcowego. Aby uzyskać więcej opcji, zobacz obsługiwane typy widoków internetowych .

Podczas migracji z biblioteki ADAL do biblioteki MSAL WKWebView zapewnia środowisko użytkownika najbardziej zbliżone do tego oferowanego przez ADAL na platformach iOS i macOS. Zachęcamy do migracji do ASWebAuthenticationSession systemu iOS, jeśli to możliwe. W przypadku systemu macOS zachęcamy do korzystania z usługi WKWebView.

Różnice interfejsu API zarządzania kontami

Podczas wywoływania metod biblioteki ADAL acquireToken() lub acquireTokenSilent() otrzymujesz obiekt ADUserInformation, który zawiera listę oświadczeń z obiektu id_token reprezentującego konto, które jest uwierzytelniane. Ponadto ADUserInformation zwraca wartość userId na podstawie oświadczenia upn. Po początkowym interaktywnym uzyskaniu tokenu biblioteka ADAL oczekuje, że deweloper przekaże userId we wszystkich wywołaniach nieinteraktywnych.

ADAL nie udostępnia interfejsu API do pobrania znanych tożsamości użytkowników. Korzysta ona z aplikacji do zapisywania tych kont i zarządzania nimi.

Biblioteka MSAL udostępnia zestaw interfejsów API umożliwiających wyświetlenie wszystkich kont znanych bibliotece MSAL bez konieczności uzyskiwania tokena.

Podobnie jak ADAL, MSAL zwraca informacje o koncie, które zawierają listę oświadczeń tożsamości z id_token. Jest częścią MSALAccount obiektu wewnątrz MSALResult obiektu.

Biblioteka MSAL udostępnia zestaw interfejsów API do usuwania kont, dzięki czemu usunięte konta są niedostępne dla aplikacji. Po usunięciu konta późniejsze wywołania uzyskiwania tokenu spowodują wyświetlenie użytkownikowi monitu o interaktywne uzyskanie tokenu. Usunięcie konta dotyczy tylko aplikacji klienckiej, która ją uruchomiła, i nie usuwa konta z innych aplikacji uruchomionych na urządzeniu ani z przeglądarki systemowej. Dzięki temu użytkownik będzie nadal korzystać z logowania jednokrotnego na urządzeniu nawet po wylogowaniu się z pojedynczej aplikacji.

Ponadto biblioteka MSAL zwraca również identyfikator konta, który może służyć do żądania tokenu w trybie dyskretnym później. Jednak identyfikatora konta (dostępnego za pomocą właściwości identifier w obiekcie MSALAccount) nie można wyświetlić i nie można zakładać, jaki ma format, ani nie należy próbować go interpretować ani parsować.

Migracja pamięci podręcznej konta

Podczas migracji z ADAL aplikacje zwykle przechowują element ADAL userId, który nie zawiera elementu identifier wymaganego przez MSAL. W ramach jednorazowego kroku migracji aplikacja może wysłać zapytanie o konto MSAL przy użyciu identyfikatora userId z ADAL za pomocą następującego interfejsu API:

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

Ten interfejs API odczytuje pamięć podręczną bibliotek MSAL i ADAL, aby wyszukać konto na podstawie identyfikatora userId biblioteki ADAL (UPN).

Jeśli konto zostanie znalezione, deweloper powinien użyć tego konta do niejawnego pozyskania tokenu. Pierwsze pozyskanie tokenu w trybie cichym skutecznie uaktualni konto, a deweloper uzyska identyfikator konta zgodny z biblioteką MSAL w wyniku zwracanym przez MSAL (identifier). Następnie należy używać tylko identifier do wyszukiwania kont przy użyciu następującego interfejsu API:

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

Chociaż możliwe jest dalsze używanie elementu userId biblioteki ADAL do wszystkich operacji w bibliotece MSAL, ponieważ userId jest oparta na nazwie UPN, wiąże się z wieloma ograniczeniami, które skutkują negatywnymi doświadczeniami użytkownika. Jeśli na przykład zmieni się nazwa UPN, użytkownik musi zalogować się ponownie. Zalecamy, aby wszystkie aplikacje używały niewyświetlanego konta identifier do wszystkich operacji.

Przeczytaj więcej na temat migracji stanu pamięci podręcznej.

Zmiany pozyskiwania tokenów

MSAL wprowadza kilka zmian w wywołaniach służących do uzyskiwania tokenów:

Podobnie jak ADAL, acquireTokenSilent zawsze skutkuje żądaniem bez interakcji.
W przeciwieństwie do ADAL acquireToken zawsze powoduje wyświetlenie interfejsu użytkownika wymagającego działania ze strony użytkownika — w widoku sieci Web lub w aplikacji Microsoft Authenticator. W zależności od stanu logowania jednokrotnego (SSO) w komponencie WebView lub aplikacji Microsoft Authenticator użytkownik może zostać poproszony o wprowadzenie swoich danych logowania.
W ADAL acquireToken z AD_PROMPT_AUTO najpierw próbuje dyskretnie uzyskać token i wyświetla interfejs użytkownika tylko wtedy, gdy żądanie dyskretne zakończy się niepowodzeniem. W bibliotece MSAL tę logikę można zrealizować, najpierw wywołując acquireTokenSilent, a następnie wywołując acquireToken tylko wtedy, gdy ciche uzyskiwanie tokenu zakończy się niepowodzeniem. Dzięki temu deweloperzy mogą dostosowywać środowisko użytkownika przed rozpoczęciem pozyskiwania tokenów interakcyjnych.

Różnice w obsłudze błędów

Biblioteka MSAL pozwala wyraźniej rozróżnić błędy, które mogą być obsługiwane przez aplikację, od tych, które wymagają interwencji użytkownika. Istnieje ograniczona liczba błędów, które deweloper musi obsłużyć:

MSALErrorInteractionRequired: Użytkownik musi wykonać żądanie interakcyjne. Może to być spowodowane różnymi przyczynami, takimi jak wygasła sesja uwierzytelniania, zmieniono zasady dostępu warunkowego, wygasł lub odwołano token odświeżania, nie ma prawidłowych tokenów w pamięci podręcznej itd.
MSALErrorServerDeclinedScopes: Żądanie nie zostało w pełni zrealizowane i nie przyznano dostępu do niektórych zakresów uprawnień. Może to być spowodowane tym, że użytkownik odmawia zgody na co najmniej jeden zakres.

Obsługa wszystkich innych błędów na MSALError liście jest opcjonalna. Możesz wykorzystać informacje zawarte w tych błędach, aby poprawić komfort użytkowania.

Aby uzyskać więcej informacji na temat obsługi błędów biblioteki MSAL, zobacz Obsługa wyjątków i błędów przy użyciu biblioteki MSAL .

Obsługa brokera

Biblioteka MSAL, począwszy od wersji 0.3.0, zapewnia obsługę uwierzytelniania obsługiwanego przez brokera przy użyciu aplikacji Microsoft Authenticator. Microsoft Authenticator umożliwia również obsługę scenariuszy dostępu warunkowego. Przykłady scenariuszy dostępu warunkowego obejmują zasady zgodności urządzeń, które wymagają od użytkownika zarejestrowania urządzenia za pośrednictwem usługi Intune lub zarejestrowania się w Microsoft Entra ID w celu uzyskania tokenu. A także zasady dostępu warunkowego usługi Mobile Application Management (MAM), które wymagają wykazania zgodności, zanim aplikacja będzie mogła uzyskać token.

Aby włączyć brokera dla aplikacji:

Zarejestruj zgodny z brokerem format identyfikatora URI przekierowania dla aplikacji. Format URI przekierowania zgodnego z brokerem to msauth.<app.bundle.id>://auth. Zastąp <app.bundle.id> identyfikatorem pakietu Twojej aplikacji. Jeśli migrujesz z ADAL, a Twoja aplikacja obsługiwała już brokera, nie musisz robić nic więcej. Poprzedni identyfikator URI przekierowania jest w pełni zgodny z MSAL, więc możesz przejść do kroku 3.
Dodaj schemat URI przekierowania aplikacji do pliku Info.plist. W przypadku domyślnego identyfikatora URI przekierowania MSAL format ma postać msauth.<app.bundle.id>. Przykład:
```
<key>CFBundleURLSchemes</key>
<array>
    <string>msauth.<app.bundle.id></string>
</array>
```

Dodaj następujące schematy do pliku Info.plist aplikacji w obszarze LSApplicationQueriesSchemes:

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

Dodaj następujący kod do pliku AppDelegate.m, aby obsłużyć wywołania zwrotne: 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)
}

Business-to-business (B2B)

W bibliotece ADAL tworzysz oddzielne wystąpienia elementu ADAuthenticationContext dla każdej dzierżawy, dla której aplikacja żąda tokenów. Nie jest to już wymagane w MSAL. W usłudze MSAL można utworzyć pojedyncze wystąpienie MSALPublicClientApplication i używać go w dowolnej chmurze i organizacji Microsoft Entra, określając inne authority dla wywołań acquireToken i acquireTokenSilent.

SSO w połączeniu z innymi pakietami SDK

Biblioteka MSAL dla systemu iOS może realizować SSO dzięki ujednoliconej pamięci podręcznej współdzielonej z biblioteką ADAL Objective-C 2.7.x+.

SSO jest realizowane dzięki współdzieleniu pęku kluczy iOS i jest dostępne tylko między aplikacjami opublikowanymi z tego samego konta Apple Developer.

SSO przez udostępnianie pęku kluczy w systemie iOS jest jedynym typem cichego SSO.

W systemie macOS biblioteka MSAL może zapewniać logowanie jednokrotne (SSO) z innymi aplikacjami opartymi na bibliotece MSAL dla systemów iOS i macOS oraz z aplikacjami opartymi na bibliotece ADAL dla Objective-C.

Biblioteka MSAL w systemie iOS obsługuje również dwa inne rodzaje logowania jednokrotnego (SSO):

Logowanie jednokrotne (SSO) w przeglądarce internetowej. Biblioteka MSAL dla systemu iOS obsługuje ASWebAuthenticationSession, które zapewnia logowanie jednokrotne (SSO) za pośrednictwem plików cookie współdzielonych z innymi aplikacjami na urządzeniu, a w szczególności z przeglądarką Safari.
Logowanie jednokrotne za pośrednictwem brokera uwierzytelniania. Na urządzeniu z systemem iOS Microsoft Authenticator działa jako broker uwierzytelniania. Może ona być zgodna z zasadami dostępu warunkowego, takimi jak wymaganie zgodnego urządzenia i zapewnia logowanie jednokrotne dla zarejestrowanych urządzeń. Zestawy SDK biblioteki MSAL, począwszy od wersji 0.3.0, domyślnie obsługują brokera.

Zestaw SDK zarządzania aplikacjami mobilnymi usługi Intune

Pakiet Intune MAM SDK obsługuje MSAL dla iOS od wersji 11.1.2

MSAL i ADAL w tej samej aplikacji

Biblioteka ADAL w wersji 2.7.0 lub nowszej nie może współistnieć z biblioteką MSAL w tej samej aplikacji. Głównym powodem jest wspólny kod współużytkowanego modułu podrzędnego. Ponieważ Objective-C nie obsługuje przestrzeni nazw, jeśli do aplikacji zostaną dodane zarówno struktury ADAL, jak i MSAL, będą istnieć dwa wystąpienia tej samej klasy. Nie ma gwarancji, która z nich zostanie wybrana w czasie wykonywania. Jeśli oba zestawy SDK używają tej samej wersji klasy powodującej konflikt, aplikacja może nadal działać. Jeśli jednak jest to inna wersja, aplikacja może napotkać nieoczekiwane awarie, które są trudne do zdiagnozowania.

Uruchamianie bibliotek ADAL i MSAL w jednej aplikacji produkcyjnej nie jest obsługiwane. Jeśli jednak przeprowadzasz tylko testowanie i migrowanie użytkowników z biblioteki ADAL Objective-C do biblioteki MSAL dla systemów iOS i macOS, możesz nadal używać biblioteki ADAL Objective-C 2.6.10. To jedyna wersja, która działa z MSAL w ramach tej samej aplikacji. Nie będzie żadnych nowych aktualizacji funkcji dla tej wersji biblioteki ADAL, dlatego powinna być używana tylko do celów migracji i testowania. Aplikacja nie powinna w dłuższej perspektywie opierać się na współistnieniu bibliotek ADAL i MSAL.

Współistnienie bibliotek ADAL i MSAL w tej samej aplikacji nie jest obsługiwane. Współistnienie bibliotek ADAL i MSAL w wielu aplikacjach jest w pełni obsługiwane.

Praktyczne kroki migracji

Migracja rejestracji aplikacji

Nie musisz zmieniać istniejącej aplikacji Microsoft Entra, aby przełączyć się na bibliotekę MSAL i włączyć konta Microsoft Entra. Jeśli jednak aplikacja oparta na biblioteki ADAL nie obsługuje uwierzytelniania obsługiwanego przez brokera, musisz zarejestrować nowy identyfikator URI przekierowania dla aplikacji, zanim będzie można przełączyć się do biblioteki MSAL.

Adres URI przekierowania powinien mieć następujący format: msauth.<app.bundle.id>://auth. Zastąp <app.bundle.id> identyfikatorem pakietu Twojej aplikacji. Określ URI przekierowania w centrum administracyjnym Microsoft Entra.

Tylko w systemie iOS, aby obsługiwać uwierzytelnianie oparte na certyfikatach, należy zarejestrować dodatkowy identyfikator URI przekierowania w aplikacji i centrum administracyjnym Microsoft Entra w następującym formacie: msauth://code/<broker-redirect-uri-in-url-encoded-form>. Na przykład msauth://code/msauth.com.microsoft.mybundleId%3A%2F%2Fauth

Zalecamy, aby wszystkie aplikacje rejestrowały oba adresy URI przekierowania.

Jeśli chcesz dodać obsługę zgody przyrostowej, wybierz interfejsy API i uprawnienia, o dostęp do których aplikacja jest skonfigurowana żądać, w ramach rejestracji aplikacji na karcie Uprawnienia interfejsu API.

Jeśli migrujesz z biblioteki ADAL i chcesz obsługiwać zarówno konta Microsoft Entra ID, jak i konta MSA, musisz zaktualizować istniejącą rejestrację aplikacji, aby obsługiwała oba typy kont. Nie zalecamy aktualizowania istniejącej aplikacji produkcyjnej w celu obsługi zarówno Microsoft Entra ID, jak i MSA od razu. Zamiast tego utwórz inny identyfikator klienta, który obsługuje zarówno Microsoft Entra ID, jak i MSA na potrzeby testowania, a po sprawdzeniu, czy wszystkie scenariusze działają, zaktualizuj istniejącą aplikację.

Dodawanie biblioteki MSAL do aplikacji

Zestaw SDK biblioteki MSAL można dodać do aplikacji przy użyciu preferowanego narzędzia do zarządzania pakietami. Zobacz szczegółowe instrukcje tutaj.

Aktualizowanie pliku Info.plist aplikacji

Tylko w systemie iOS dodaj schemat URI przekierowania Twojej aplikacji do pliku Info.plist. W przypadku aplikacji zgodnych z brokerem ADAL powinno już tam być. Domyślny schemat URI przekierowania MSAL będzie miał format: msauth.<app.bundle.id>.

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

Dodaj następujące schematy do pliku Info.plist aplikacji w obszarze LSApplicationQueriesSchemes.

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

Aktualizowanie kodu AppDelegate

W przypadku tylko systemu iOS dodaj następujący kod do pliku AppDelegate.m:

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

Jeśli używasz programu Xcode 11, należy zamiast tego umieścić wywołanie zwrotne biblioteki MSAL w SceneDelegate pliku. Jeśli dla zgodności ze starszymi wersjami iOS obsługiwane są zarówno UISceneDelegate, jak i UIApplicationDelegate, wywołanie zwrotne MSAL musi zostać umieszczone w obu plikach.

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

Dzięki temu MSAL może obsługiwać odpowiedzi z brokera i składnika internetowego. Nie było to konieczne w ADAL, ponieważ automatycznie podmieniał implementacje metod delegata aplikacji. Dodawanie go ręcznie jest mniej podatne na błędy i zapewnia aplikacji większą kontrolę.

Włączanie buforowania tokenów

Domyślnie biblioteka MSAL buforuje tokeny aplikacji w pęku kluczy systemu iOS lub macOS.

Aby włączyć buforowanie tokenów:

Upewnij się, że aplikacja jest prawidłowo podpisana
Przejdź do > Możliwości ustawień > Project XcodeWłącz udostępnianie łańcucha kluczy
Kliknij + i wprowadź następujący wpis w polu Grupy pęku kluczy: 3.a W przypadku systemu iOS wprowadź com.microsoft.adalcache 3.b W przypadku systemu macOS wprowadź com.microsoft.identity.universalstorage

Utwórz aplikację MSALPublicClientApplication i przejdź do wywołań acquireToken i acquireTokeSilent

Możesz utworzyć MSALPublicClientApplication przy użyciu następującego kodu:

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
}

Następnie wywołaj interfejs API zarządzania kontami, aby sprawdzić, czy istnieją jakieś konta w pamięci podręcznej:

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
}

lub przeczytaj wszystkie relacje:

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
}

Jeśli znaleziono konto, wywołaj interfejs API MSAL acquireTokenSilent:

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

Następne kroki

Dowiedz się więcej o przepływach uwierzytelniania i scenariuszach aplikacji

Opinia

Czy ta strona była pomocna?

Last updated on 2026-07-02

Migrowanie aplikacji do biblioteki MSAL dla systemów iOS i macOS

Różnice w możliwościach aplikacji ADAL i MSAL

Kto może się zalogować

Zgodność ze standardami

Przyrostowa i dynamiczna zgoda

Różnice między bibliotekami ADAL i MSAL

MSALPublicClientApplication zamiast ADAuthenticationContext

Zakresy zamiast zasobów

Obsługa różnych typów i przeglądarek WebView

Różnice interfejsu API zarządzania kontami

Migracja pamięci podręcznej konta

Zmiany pozyskiwania tokenów

Różnice w obsłudze błędów

Obsługa brokera

Business-to-business (B2B)

SSO w połączeniu z innymi pakietami SDK

Zestaw SDK zarządzania aplikacjami mobilnymi usługi Intune

MSAL i ADAL w tej samej aplikacji

Praktyczne kroki migracji

Migracja rejestracji aplikacji

Dodawanie biblioteki MSAL do aplikacji

Aktualizowanie pliku Info.plist aplikacji

Aktualizowanie kodu AppDelegate

Włączanie buforowania tokenów

Utwórz aplikację MSALPublicClientApplication i przejdź do wywołań acquireToken i acquireTokeSilent

Następne kroki

Opinia

Dodatkowe zasoby