Udostępnij za pośrednictwem


Szybki start: logowanie użytkowników i wywoływanie programu Microsoft Graph z poziomu aplikacji dla systemu iOS lub macOS

W tym przewodniku pobierzesz i uruchomisz przykładowy kod, który pokazuje, jak natywna aplikacja na iOS lub macOS może logować użytkowników i uzyskiwać token dostępu do wywołania interfejsu API Microsoft Graph.

Szybki start dotyczy zarówno aplikacji iOS, jak i macOS. Niektóre kroki są wymagane tylko w przypadku aplikacji systemu iOS i będą wskazywane jako takie.

Warunki wstępne

Jak działa przykład

Diagram przedstawiający sposób działania przykładowej aplikacji wygenerowanej przez ten przewodnik Szybki start.

Rejestrowanie aplikacji Szybki start

Aby zarejestrować aplikację i ręcznie dodać informacje dotyczące rejestracji aplikacji do rozwiązania, wykonaj następujące kroki:

  1. Zaloguj się do centrum administracyjnego Microsoft Entra jako co najmniej Developer Aplikacji.
  2. Jeśli masz dostęp do wielu dzierżaw, użyj ikony ustawień w górnym menu, aby przełączyć się na dzierżawę, w której chcesz zarejestrować aplikację, wybierając z menu Katalogi i subskrypcje.
  3. Przejdź do Tożsamość>Aplikacje>Rejestracja aplikacji.
  4. Wybierz pozycję Nowa rejestracja.
  5. Wprowadź Nazwa dla aplikacji. Użytkownicy aplikacji mogą zobaczyć tę nazwę i możesz ją zmienić później.
  6. Wybierz pozycję Zarejestruj.
  7. W obszarze Zarządzajwybierz pozycję Uwierzytelnianie>Dodaj platformę>iOS.
  8. Wprowadź identyfikator pakietu dla aplikacji. Identyfikator pakietu to unikatowy ciąg, który jednoznacznie identyfikuje aplikację, na przykład com.<yourname>.identitysample.MSALMacOS. Zanotuj używaną wartość. Należy pamiętać, że konfiguracja systemu iOS ma również zastosowanie do aplikacji systemu macOS.
  9. Wybierz pozycję Skonfiguruj i zapisz szczegóły konfiguracji biblioteki MSAL w dalszej części tego przewodnika Szybki start.
  10. Wybierz pozycję Gotowe.

Krok 2. Pobieranie przykładowego projektu

Krok 3. Instalowanie zależności

  1. Wyodrębnij plik zip.
  2. W oknie terminalu przejdź do folderu z pobranym przykładem kodu i uruchom pod install, aby zainstalować najnowszą bibliotekę MSAL.

Krok 4. Konfigurowanie projektu

Jeśli wybrano opcję 1 powyżej, możesz pominąć te kroki.

  1. Otwórz projekt w programie XCode.

  2. Edytuj ViewController.swift i zastąp wiersz rozpoczynający się od ciągu "let kClientID" następującym fragmentem kodu. Pamiętaj, aby zaktualizować wartość dla kClientID za pomocą identyfikatora klienta (clientID), który zapisałeś podczas wcześniejszej rejestracji aplikacji w tym szybkim przewodniku.

    let kClientID = "Enter_the_Application_Id_Here"
    
  3. Jeśli tworzysz aplikację dla chmur krajowych Microsoft Entra, zastąp linie rozpoczynające się od 'let kGraphEndpoint' oraz 'let kAuthority' odpowiednimi punktami końcowymi. W przypadku dostępu globalnego użyj wartości domyślnych:

    let kGraphEndpoint = "https://graph.microsoft.com/"
    let kAuthority = "https://login.microsoftonline.com/common"
    
  4. Inne punkty końcowe są udokumentowane tutaj. Na przykład, aby uruchomić Quickstart z Microsoft Entra Germany, użyj następującego polecenia:

    let kGraphEndpoint = "https://graph.microsoft.de/"
    let kAuthority = "https://login.microsoftonline.de/common"
    
  5. Otwórz ustawienia projektu. W sekcji Identity wprowadź identyfikator pakietu .

  6. Kliknij prawym przyciskiem myszy plik Info.plist i wybierz pozycję Otwórz jako kod źródłowy>.

  7. W węźle głównym dict zastąp Enter_the_bundle_Id_Here identyfikatorem pakietu użytym w portalu. Zwróć uwagę na prefiks msauth. w ciągu.

    <key>CFBundleURLTypes</key>
    <array>
       <dict>
          <key>CFBundleURLSchemes</key>
          <array>
             <string>msauth.Enter_the_Bundle_Id_Here</string>
          </array>
       </dict>
    </array>
    
  8. Skompiluj i uruchom aplikację!

Więcej informacji

Przeczytaj te sekcje, aby dowiedzieć się więcej na temat tego przewodnika wprowadzającego.

Pobierz MSAL

Biblioteka MSAL (MSAL.framework) jest używana do logowania użytkowników i żądania tokenów, które są wykorzystywane do uzyskiwania dostępu do interfejsu API chronionego przez platformę tożsamości Microsoft. Bibliotekę MSAL można dodać do aplikacji przy użyciu następującego procesu:

$ vi Podfile

Dodaj następujący kod do tego pliku podfile (z obiektem docelowym projektu):

use_frameworks!

target 'MSALiOS' do
   pod 'MSAL'
end

Uruchom komendę instalacji CocoaPods:

pod install

Inicjowanie biblioteki MSAL

Odwołanie do biblioteki MSAL można dodać za pomocą następującego kodu:

import MSAL

Następnie zainicjuj bibliotekę MSAL przy użyciu następującego kodu:

let authority = try MSALAADAuthority(url: URL(string: kAuthority)!)

let msalConfiguration = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: nil, authority: authority)
self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
Gdzie: Opis
clientId Identyfikator aplikacji zarejestrowanej w portal.azure.com
authority Platforma tożsamości firmy Microsoft. W większości przypadków będzie to https://login.microsoftonline.com/common
redirectUri URI przekierowania aplikacji. Możesz przekazać wartość «nil», aby użyć wartości domyślnej lub podać własny, niestandardowy identyfikator URI przekierowania.

Tylko w przypadku systemu iOS dodatkowe wymagania dotyczące aplikacji

Twoja aplikacja musi również zawierać następujące elementy w AppDelegate. Dzięki temu zestaw SDK biblioteki MSAL obsługuje odpowiedź tokenu z aplikacji brokera uwierzytelniania podczas uwierzytelniania.

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

    return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

Notatka

Jeśli w systemie iOS 13 lub nowszym zdecydujesz się na UISceneDelegate zamiast UIApplicationDelegate, ten kod umieść w wywołaniu zwrotnym scene:openURLContexts: (zobacz dokumentację firmy Apple). Jeśli obsługujesz zarówno UISceneDelegate, jak i UIApplicationDelegate w celu zapewnienia zgodności ze starszym systemem iOS, wywołanie zwrotne MSAL musi zostać umieszczone w obu miejscach.

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

Na koniec aplikacja powinna mieć wpis LSApplicationQueriesSchemes w Info.plist obok CFBundleURLTypes. Przykład jest dostarczany z tym dołączonym elementem.

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

Użytkownicy logujący się & żądają tokenów

Biblioteka MSAL ma dwie metody uzyskiwania tokenów: acquireToken i acquireTokenSilent.

acquireToken: interaktywne uzyskiwanie tokenu

Niektóre sytuacje wymagają od użytkowników interakcji z platformą tożsamości firmy Microsoft. W takich przypadkach użytkownik końcowy może być zobowiązany do wybrania swojego konta, wprowadzenia poświadczeń lub zgody na uprawnienia aplikacji. Na przykład

  • Przy pierwszym logowaniu użytkowników do aplikacji
  • Jeśli użytkownik zresetuje swoje hasło, będzie musiał wprowadzić swoje poświadczenia do systemu.
  • Gdy aplikacja żąda dostępu do zasobu po raz pierwszy
  • Gdy wymagane są uwierzytelnianie wieloskładnikowe lub inne zasady dostępu warunkowego
let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
self.applicationContext!.acquireToken(with: parameters) { (result, error) in /* Add your handling logic */}
Gdzie: Opis
scopes Zawiera żądane zakresy (czyli [ "user.read" ] dla programu Microsoft Graph lub [ "<Application ID URL>/scope" ] dla niestandardowych internetowych interfejsów API (api://<Application ID>/access_as_user))

acquireTokenSilent: dyskretne uzyskiwanie tokenu dostępu

Aplikacje nie powinny wymagać od użytkowników logowania się za każdym razem, gdy żądają tokenu. Jeśli użytkownik już się zalogował, ta metoda umożliwia aplikacjom dyskretne żądanie tokenów.

self.applicationContext!.getCurrentAccount(with: nil) { (currentAccount, previousAccount, error) in

   guard let account = currentAccount else {
      return
   }

   let silentParams = MSALSilentTokenParameters(scopes: self.kScopes, account: account)
   self.applicationContext!.acquireTokenSilent(with: silentParams) { (result, error) in /* Add your handling logic */}
}
Gdzie: Opis
scopes Zawiera żądane zakresy (czyli [ "user.read" ] dla programu Microsoft Graph lub [ "<Application ID URL>/scope" ] dla niestandardowych internetowych interfejsów API (api://<Application ID>/access_as_user))
account Konto, dla którego jest wymagany token. Ten przewodnik szybkiego startu odnosi się do pojedynczej aplikacji do zarządzania kontem. Jeśli chcesz utworzyć aplikację z wieloma kontami, musisz zdefiniować logikę, aby określić, które konto ma być używane na potrzeby żądań tokenów przy użyciu accountsFromDeviceForParameters:completionBlock: i przekazując poprawne accountIdentifier.

Pomoc i obsługa techniczna

Jeśli potrzebujesz pomocy, chcesz zgłosić problem lub poznać opcje pomocy technicznej, zobacz Pomoc i obsługa techniczna dla deweloperów.

Następne kroki

Przejdź do samouczka krok po kroku, w którym tworzysz aplikację dla systemu iOS lub macOS, która pobiera token dostępu z platformy tożsamości firmy Microsoft i używa jej do wywoływania interfejsu API programu Microsoft Graph.