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

Artykuł
10/24/2023

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

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

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
XCode 10+
iOS 10+
macOS 10.12+

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

Napiwek

Kroki opisane w tym artykule mogą się nieznacznie różnić w zależności od portalu, od którego zaczynasz.

Aby ręcznie zarejestrować aplikację i dodać informacje na temat rejestracji aplikacji do rozwiązania, wykonaj następujące czynności:

Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako deweloper aplikacji.
Jeśli masz dostęp do wielu dzierżaw, użyj ikonyUstawienia w górnym menu, aby przełączyć się do dzierżawy, w której chcesz zarejestrować aplikację z menu Katalogi i subskrypcje.
Przejdź do aplikacji tożsamości>> Rejestracje aplikacji.
Wybierz opcjęNowa rejestracja.
Wprowadź nazwę aplikacji. Użytkownicy aplikacji mogą zobaczyć tę nazwę i możesz ją zmienić później.
Wybierz pozycję Zarejestruj.
W obszarze Zarządzanie wybierz pozycję Uwierzytelnianie>Dodaj platformę>iOS.
Wprowadź identyfikator pakietu dla aplikacji. Identyfikator pakietu jest unikatowym ciągiem, 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.
Wybierz pozycję Konfiguruj i zapisz szczegóły konfiguracji biblioteki MSAL w dalszej części tego przewodnika Szybki start.
Wybierz pozycję Gotowe.

Krok 2. Pobieranie przykładowego projektu

Krok 3. Instalowanie zależności

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

Krok 4. Konfigurowanie projektu

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

Otwórz projekt w programie XCode.
Edytuj plik ViewController.swift i zastąp wiersz rozpoczynający się ciągiem "let kClientID" następującym fragmentem kodu. Pamiętaj, aby zaktualizować wartość parametru za kClientID pomocą identyfikatora clientID zapisanego podczas rejestrowania aplikacji wcześniej w tym przewodniku Szybki start:
```
let kClientID = "Enter_the_Application_Id_Here"
```
Jeśli tworzysz aplikację dla chmur krajowych firmy Microsoft Entra, zastąp wiersz rozpoczynający się od "let kGraphEndpoint" i "let kAuthority" poprawnymi 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"
```
Inne punkty końcowe są udokumentowane tutaj. Aby na przykład uruchomić przewodnik Szybki start z firmą Microsoft Entra Germany, użyj następującego polecenia:
```
let kGraphEndpoint = "https://graph.microsoft.de/"
let kAuthority = "https://login.microsoftonline.de/common"
```
Otwórz ustawienia projektu. W sekcji Tożsamość wprowadź identyfikator pakietu.
Kliknij prawym przyciskiem myszy plik Info.plist i wybierz pozycję Otwórz jako>kod źródłowy.

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

<key>CFBundleURLTypes</key>
<array>
   <dict>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>msauth.Enter_the_Bundle_Id_Here</string>
      </array>
   </dict>
</array>

Skompiluj i uruchom aplikację!

Więcej informacji

Zapoznaj się z następującymi sekcjami, aby dowiedzieć się więcej na temat tego przewodnika Szybki start.

Uzyskiwanie biblioteki MSAL

BIBLIOTEKA MSAL (MSAL.framework) to biblioteka używana do logowania użytkowników i żądania tokenów używanych do uzyskiwania dostępu do interfejsu API chronionego przez Platforma tożsamości Microsoft. Możesz dodać bibliotekę MSAL do aplikacji w następujący sposób:

$ vi Podfile

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

use_frameworks!

target 'MSALiOS' do
   pod 'MSAL'
end

Uruchom polecenie instalacji cocoaPods:

pod install

Inicjowanie biblioteki MSAL

Aby dodać odwołanie do biblioteki MSAL, dodaj następujący kod:

import MSAL

Następnie zainicjuj bibliotekę MSAL, używając 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 z aplikacji zarejestrowanej w witrynie portal.azure.com
`authority`	Platforma tożsamości Microsoft. W większości przypadków będzie to `https://login.microsoftonline.com/common`
`redirectUri`	Identyfikator URI przekierowania aplikacji. Możesz przekazać wartość "nil", aby użyć wartości domyślnej lub niestandardowego identyfikatora URI przekierowania.

Tylko w przypadku systemu iOS dodatkowe wymagania dotyczące aplikacji

Aplikacja musi również mieć następujące elementy w pliku 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)
}

Uwaga

W systemie iOS 13 lub nowszym, jeśli przyjmujesz UISceneDelegate zamiast UIApplicationDelegate, umieść ten kod w scene:openURLContexts: wywołaniu zwrotnym (zobacz dokumentację firmy Apple). Jeśli obsługujesz zarówno interfejs użytkownikaSceneDelegate, jak i UIApplicationDelegate w celu zapewnienia zgodności ze starszym systemem iOS, wywołanie zwrotne biblioteki 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 musi mieć LSApplicationQueriesSchemes wpis w pliku Info.plist obok pliku CFBundleURLTypes. Przykład jest dostarczany z tym dołączonym elementem.

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

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

acquireToken: interaktywne uzyskiwanie tokenu

Niektóre sytuacje wymagają od użytkowników interakcji z Platforma tożsamości 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. Przykład:

Gdy nowi użytkownicy logują się do aplikacji po raz pierwszy.
Jeśli użytkownik resetuje swoje hasło, musi wprowadzić swoje poświadczenia
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" ]` 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" ]` niestandardowych internetowych interfejsów API (`api://<Application ID>/access_as_user`))
`account`	Konto, dla którego jest wymagany token. Ten przewodnik Szybki start dotyczy pojedynczej aplikacji konta. 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, i `accountsFromDeviceForParameters:completionBlock:` przekazywać 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 Platforma tożsamości Microsoft i używa go do wywoływania interfejsu API programu Microsoft Graph.

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

Udostępnij za pośrednictwem

Wymagania wstępne

Jak działa przykład

Rejestrowanie aplikacji Szybki start

Krok 2. Pobieranie przykładowego projektu

Krok 3. Instalowanie zależności

Krok 4. Konfigurowanie projektu

Więcej informacji

Uzyskiwanie biblioteki MSAL

Inicjowanie biblioteki MSAL

Tylko w przypadku systemu iOS dodatkowe wymagania dotyczące aplikacji

acquireToken: interaktywne uzyskiwanie tokenu

acquireTokenSilent: dyskretne uzyskiwanie tokenu dostępu

Pomoc i obsługa techniczna

Następne kroki

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Wymagania wstępne

Jak działa przykład

Rejestrowanie aplikacji Szybki start

Krok 2. Pobieranie przykładowego projektu

Krok 3. Instalowanie zależności

Krok 4. Konfigurowanie projektu

Więcej informacji

Uzyskiwanie biblioteki MSAL

Inicjowanie biblioteki MSAL

Tylko w przypadku systemu iOS dodatkowe wymagania dotyczące aplikacji

Logowanie użytkowników i tokenów żądań

acquireToken: interaktywne uzyskiwanie tokenu

acquireTokenSilent: dyskretne uzyskiwanie tokenu dostępu

Pomoc i obsługa techniczna

Następne kroki

Opinia

Dodatkowe zasoby