快速入門：從 iOS 或 macOS 應用程式登入使用者並呼叫 Microsoft Graph

發行項
07/03/2024

在本快速入門中，您會下載並執行程式碼範例，該範例會示範原生 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：安裝相依項目

解壓縮檔案。
在終端視窗中，瀏覽至包含所下載程式碼範例的資料夾，然後執行 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 能夠在您執行驗證時，處理來自驗證訊息代理程式應用程式的權杖回應。

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 中的 CFBundleURLTypes 旁邊必須有 LSApplicationQueriesSchemes 項目。此範例會包含此項目。

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

教學課程：從 iOS 或 macOS 應用程式登入使用者並呼叫 Microsoft Graph

共用方式為

必要條件

此範例的運作方式

註冊快速入門應用程式

步驟 2：下載範例專案

步驟 3：安裝相依項目

步驟 4：設定您的專案

相關資訊

取得 MSAL

將 MSAL 初始化

其他應用程式需求 (僅限於 iOS)

acquireToken：以互動方式取得權杖

acquireTokenSilent：以無訊息方式取得存取權杖

說明與支援

下一步

意見反應

其他資源

共用方式為

必要條件

此範例的運作方式

註冊快速入門應用程式

步驟 2：下載範例專案

步驟 3：安裝相依項目

步驟 4：設定您的專案

相關資訊

取得 MSAL

將 MSAL 初始化

其他應用程式需求 (僅限於 iOS)

登入使用者與要求權杖

acquireToken：以互動方式取得權杖

acquireTokenSilent：以無訊息方式取得存取權杖

說明與支援

下一步

意見反應

其他資源