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
- Konto platformy Azure z aktywną subskrypcją. Utwórz bezpłatne konto.
- XCode 10+
- iOS 10+
- macOS 10.12+
Jak działa przykład
Rejestrowanie aplikacji Szybki start
Aby zarejestrować aplikację i ręcznie dodać informacje dotyczące rejestracji aplikacji do rozwiązania, wykonaj następujące kroki:
- Zaloguj się do centrum administracyjnego Microsoft Entra jako co najmniej Developer Aplikacji.
- 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.
- Przejdź do Tożsamość>Aplikacje>Rejestracja aplikacji.
- Wybierz pozycję Nowa rejestracja.
- Wprowadź Nazwa dla aplikacji. Użytkownicy aplikacji mogą zobaczyć tę nazwę i możesz ją zmienić później.
- Wybierz pozycję Zarejestruj.
- W obszarze Zarządzajwybierz pozycję Uwierzytelnianie>Dodaj platformę>iOS.
- 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. - Wybierz pozycję Skonfiguruj 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 plik zip.
- 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.
Otwórz projekt w programie XCode.
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"
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"
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"
Otwórz ustawienia projektu. W sekcji Identity 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
Enter_the_bundle_Id_Here
identyfikatorem pakietu użytym w portalu. Zwróć uwagę na prefiksmsauth.
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
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.