快速入門:從iOS或macOS應用程式登入使用者並呼叫 Microsoft Graph
在本快速入門中,您會下載並執行程式碼範例,示範原生 iOS 或 macOS 應用程式如何登入使用者,並取得存取令牌來呼叫 Microsoft Graph API。
本快速入門同時適用於 iOS 和 macOS 應用程式。 某些步驟僅適用於 iOS 應用程式,因此會以此類方式指出。
先決條件
- 具有作用中訂閱的 Azure 帳戶。 免費建立帳戶。
- XCode 10+
- iOS 10+
- macOS 10.12+
範例的運作方式
註冊快速入門應用程式
若要註冊您的應用程式,並手動將應用程式的註冊資訊新增至您的解決方案,請遵循下列步驟:
- 以至少 應用程式開發人員身分登入 Microsoft Entra 系統管理中心。
- 如果您有多個租使用者的存取權,請使用頂端功能表中的 [設定] 圖示
,切換至您想要從 [目錄 + 訂用帳戶] 功能表註冊應用程式的租使用者。
- 瀏覽至 身分識別>應用程式>應用程式註冊。
- 選取 新增註冊。
- 輸入應用程式的 名稱。 您的應用程式使用者可能會看到此名稱,稍後您可以加以變更。
- 選取 [[註冊]。
- 在 [管理] 下,選取 [驗證],>[新增平臺>iOS]。
- 輸入應用程式的 套件組合標識碼。 套件組合識別碼是唯一識別應用程式的唯一字串,例如
com.<yourname>.identitysample.MSALMacOS
。 記下您使用的值。 請注意,iOS 設定也適用於macOS應用程式。 - 選取 [設定,然後儲存 MSAL 組態 詳細數據,以供本快速入門稍後使用。
- 選擇 [完成]。
步驟 2:下載範例專案
步驟 3:安裝依賴項
- 擷取 zip 檔案。
- 在終端機視窗中,流覽至具有下載程式碼範例的資料夾,然後執行
pod install
以安裝最新的 MSAL 連結庫。
步驟 4:設定專案
如果您選取上述選項 1,您可以略過這些步驟。
在 XCode 中開啟專案。
編輯 ViewController.swift,並以下列代碼段取代開頭為 'let kClientID' 的行。 請記得使用您稍早在本快速入門中註冊應用程式時所儲存的 clientID 來更新
kClientID
的值:let kClientID = "Enter_the_Application_Id_Here"
如果您要為 Microsoft Entra 國家雲端開發應用程式,請將以 'let kGraphEndpoint' 和 'let kAuthority' 開頭的行替換為正確的端點。 針對全域存取,請使用預設值:
let kGraphEndpoint = "https://graph.microsoft.com/" let kAuthority = "https://login.microsoftonline.com/common"
其他端點已被記錄在這裡。 例如,若要使用 Microsoft Entra Germany 執行快速入門,請使用下列指令:
let kGraphEndpoint = "https://graph.microsoft.de/" let kAuthority = "https://login.microsoftonline.de/common"
開啟項目設定。 在 [身分識別] 區段中,輸入 套件組合標識碼。
右鍵點擊 Info.plist,然後選取 開啟為>原始程式碼。
在 dict 根節點底下,將
Enter_the_bundle_Id_Here
替換為您在入口網站中使用的 套件識別碼。 請注意字串中的msauth.
前置詞。<key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>msauth.Enter_the_Bundle_Id_Here</string> </array> </dict> </array>
建置並執行應用程式!
詳細資訊
請閱讀這些章節,以深入瞭解本快速入門。
取得 MSAL
MSAL(MSAL.framework)是程式庫,用於登入使用者並請求用來存取受 Microsoft 身分識別平台保護的 API 的令牌。 您可以使用下列程式將 MSAL 新增至應用程式:
$ vi Podfile
將下列內容新增至此 Podfile(與您的專案目標相關):
use_frameworks!
target 'MSALiOS' do
pod 'MSAL'
end
執行 CocoaPods 安裝命令:
pod install
初始化 MSAL
您可以藉由新增下列程式碼來新增 MSAL 的參考:
import MSAL
然後,使用下列程式代碼初始化 MSAL:
let authority = try MSALAADAuthority(url: URL(string: kAuthority)!)
let msalConfiguration = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: nil, authority: authority)
self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
哪裡: | 描述 |
---|---|
clientId |
portal.azure.com 中註冊之應用程式的應用程式標識碼 |
authority |
Microsoft身分識別平臺。 在大部分情況下,這會 https://login.microsoftonline.com/common |
redirectUri |
應用程式的重新導向 URI。 您可以傳遞 『nil』 以使用預設值,或自定義重新導向 URI。 |
僅限 iOS,額外的應用程式需求
您的應用程式也必須在 AppDelegate
中具有下列專案。 這可讓 MSAL SDK 在您進行驗證時處理來自 Auth Broker 應用程式的令牌回應。
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}
注意
在 iOS 13+ 上,如果您採用 UISceneDelegate
而不是 UIApplicationDelegate
,請將此代碼改放在 scene:openURLContexts:
回呼中(請參閱 Apple 的文件)。
如果您支援 UISceneDelegate 和 UIApplicationDelegate,以便與舊版 iOS 相容,那麼 MSAL 回呼必須放在這兩個地方。
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)
}
最後,您的應用程式在 Info.plist 中必須有 LSApplicationQueriesSchemes
專案,CFBundleURLTypes
。 這個範例包含在內。
<key>LSApplicationQueriesSchemes</key>
<array>
<string>msauthv2</string>
<string>msauthv3</string>
</array>
登入使用者 & 要求令牌
MSAL 有兩種方法可用來取得令牌:acquireToken
和 acquireTokenSilent
。
acquireToken:以互動方式取得令牌
在某些情況下,用戶必須與Microsoft身分識別平台互動。 在這些情況下,使用者可能需要選取其帳戶、輸入其認證或同意您應用程式的許可權。 例如
- 使用者第一次登入應用程式時
- 如果使用者重設其密碼,則必須輸入其認證
- 當您的應用程式第一次要求存取資源時
- 需要 MFA 或其他條件式存取原則時
let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
self.applicationContext!.acquireToken(with: parameters) { (result, error) in /* Add your handling logic */}
哪裡: | 描述 |
---|---|
scopes |
包含所要求的範圍,(也就是 Microsoft Graph 的 [ "user.read" ] 或自訂 Web API 的 [ "<Application ID URL>/scope" ] (api://<Application ID>/access_as_user )) |
acquireTokenSilent:以無訊息方式取得存取令牌
每次要求令牌時,應用程式不應該要求其使用者登入。 如果用戶已經登入,這個方法可讓應用程式以無訊息方式要求令牌。
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 */}
}
哪裡: | 描述 |
---|---|
scopes |
包含所要求的範圍(也就是 Microsoft Graph 的 [ "user.read" ] 或自定義 Web API 的 [ "<Application ID URL>/scope" ] (api://<Application ID>/access_as_user )) |
account |
要求令牌的帳戶。 本快速入門指南是關於單一帳戶應用程式。 如果您想要建置多帳戶應用程式,您必須定義邏輯,以識別要使用哪一個帳戶來使用 accountsFromDeviceForParameters:completionBlock: 並傳遞正確的 accountIdentifier |
協助與支援
如果您需要協助、想要回報問題,或想要瞭解支援選項,請參閱 開發人員的說明和支援。
後續步驟
接下來,移至逐步教學指南,您將建置一個 iOS 或 macOS 應用程式,從 Microsoft 身分識別平台取得存取令牌,並使用它來呼叫 Microsoft Graph API。