使用原生驗證在範例 iOS 行動應用程式中登入使用者並呼叫 API - Microsoft Entra External ID

文章
06/14/2024

此範例示範如何設定 iOS 範例應用程式來呼叫 ASP.NET Core Web API。

必要條件

使用原生驗證，在範例 iOS（Swift）行動裝置應用程式中登入使用者。

註冊 Web API 應用程式

以至少應用程式開發人員身分登入 Microsoft Entra 系統管理中心。
如果您有多個租使用者的存取權，請使用 頂端功能表中的 [設定 ] 圖示，從 [目錄 + 訂 用帳戶] 功能表切換至外部租使用者。
流覽至 [身分>識別應用程式> 應用程式註冊]。
選取 + 新增註冊。
在出現的 [註冊應用程式] 頁面中，輸入應用程式的註冊資訊：
1. 在 [名稱] 區段中，輸入將向用戶顯示有意義的應用程式名稱，例如 ciam-ToDoList-api。
2. 在 [支援的帳戶類型] 底下，選取 [僅在此組織目錄中的帳戶]。
選取 [暫存器] 以建立應用程式。
註冊完成時，會顯示應用程式的 [ 概觀] 窗格 。 記錄要用於應用程式原始碼的目錄（租使用者）標識碼和應用程式（用戶端）標識碼。

設定 API 範圍

API 必須發佈至少一個範圍，也稱為「委派許可權」，用戶端應用程式才能成功取得使用者的存取令牌。若要發佈範圍，請遵循下列步驟：

從 [應用程式註冊] 頁面中，選取您建立的 API 應用程式（ciam-ToDoList-api），以開啟其 [概觀] 頁面。
在 [管理] 底下，選取 [公開 API]。
在頁面頂端的 [應用程式識別碼 URI] 旁，選取 [新增] 鏈接以產生此應用程式唯一的 URI。
接受建議的應用程式識別碼 URI，例如 api://{clientId}，然後選取 [ 儲存]。當您的 Web 應用程式要求 Web API 的存取令牌時，它會新增 URI 作為您為 API 定義之每個範圍的前置詞。
在 [由此 API 定義的範圍] 底下，選取 [新增範圍]。

輸入下列定義 API 讀取權限的值，然後選取 [ 新增範圍 ] 以儲存變更：

屬性	數值
範圍名稱	ToDoList.Read
有權同意者	僅限系統管理員
管理員同意顯示名稱	使用 'TodoListApi' 讀取使用者ToDo清單
管理員同意描述	允許應用程式使用『TodoListApi』讀取使用者的 ToDo 清單。
州/省	已啟用

再次選取 [新增範圍 ]，然後輸入下列值來定義 API 的讀取和寫入存取範圍。選取 [ 新增範圍 ] 以儲存變更：

屬性	數值
範圍名稱	ToDoList.ReadWrite
有權同意者	僅限系統管理員
管理員同意顯示名稱	使用 'ToDoListApi' 讀取和寫入使用者 ToDo list
管理員同意描述	允許應用程式使用『ToDoListApi』讀取和寫入使用者的 ToDo 清單
州/省	已啟用

在 [管理] 底下，選取 [指令清單] 以開啟 API 指令清單編輯器。
將屬性設定 accessTokenAcceptedVersion 為 2。
選取 [儲存]。

深入瞭解發佈 Web API 許可權時最低許可權的原則。

設定應用程式角色

API 必須針對應用程式發佈至少一個應用程式角色，也稱為「應用程式許可權」，用戶端應用程式才能自行取得存取令牌。應用程式許可權是 API 想要讓用戶端應用程式以自己身分成功驗證，而不需要登入使用者時，應該發佈的許可權類型。若要發佈應用程式許可權，請遵循下列步驟：

從 [應用程式註冊] 頁面中，選取您建立的應用程式（例如 ciam-ToDoList-api），以開啟其 [概觀] 頁面。
在 [管理] 底下，選取 [應用程式角色]。

選取 [ 建立應用程式角色]，然後輸入下列值，然後選取 [ 套用 ] 以儲存變更：

屬性	數值
Display name	ToDoList.Read.All
允許的成員類型	應用程式
值	ToDoList.Read.All
描述	允許應用程式使用『TodoListApi』讀取每個使用者的 ToDo 清單

再次選取 [建立應用程式角色]，然後輸入下列第二個應用程式角色 的值，然後選取 [ 套用 ] 以儲存變更：

屬性	數值
Display name	ToDoList.ReadWrite.All
允許的成員類型	應用程式
值	ToDoList.ReadWrite.All
描述	允許應用程式使用『ToDoListApi』讀取和寫入每個使用者的 ToDo 清單

設定選擇性宣告

您可以 idtyp 選擇性宣告來協助 Web API 判斷令牌是否為應用程式權杖或應用程式 + 使用者令牌。雖然您可以將scp和 roles 宣告的組合用於相同用途，但使用idtyp宣告是區分應用程式令牌和應用程式 + 使用者令牌的最簡單方式。 例如，當令牌是僅限應用程式令牌時，此宣告的值是 應用程式 。

將 API 許可權授與 iOS 範例應用程式

註冊用戶端應用程式和 Web API，並藉由建立範圍來公開 API 之後，您可以遵循下列步驟來設定用戶端對 API 的許可權：

從 [應用程式註冊] 頁面中，選取您建立的應用程式（例如 ciam-client-app），以開啟其 [概觀] 頁面。
在 [管理] 之下選取 [API 權限]。
在 [已設定的權限] 底下，選取 [新增權限]。
選取 [我的組織使用的 API] 索引標籤。
在 API 清單中，選取 api，例如 ciam-ToDoList-api。
選取 [委派的許可權] 選項。
從許可權清單中，選取 [ToDoList.Read]、[ToDoList.ReadWrite ] （如有必要，請使用搜尋方塊）。
選取 [ 新增許可權] 按鈕。
此時，您已正確指派許可權。不過，由於租用戶是客戶的租使用者，因此取用者使用者本身無法同意這些許可權。若要解決此問題，身為系統管理員必須代表租使用者中的所有使用者同意這些許可權：
1. 選取 [授與租用戶名稱>的<管理員同意]，然後選取 [是]。
2. 選取 [重新整理]，然後確認 [為租用戶名稱>授與] <出現在這兩個許可權的 [狀態] 底下。
從 [設定的許可權] 清單中，選取 ToDoList.Read 和 ToDoList.ReadWrite 許可權，一次一個許可權，然後複製許可權的完整 URI 以供稍後使用。完整權限 URI 看起來類似 api://{clientId}/{ToDoList.Read} 或 api://{clientId}/{ToDoList.ReadWrite}。

複製或下載範例 Web API

若要取得範例應用程式，您可以從 GitHub 複製它，或將它下載為.zip檔案。

若要複製範例，請開啟命令提示字元並流覽至您想要建立專案的位置，然後輸入下列命令：
```
git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git
```
下載.zip檔案。將它解壓縮到名稱長度少於 260 個字元的檔案路徑。

設定和執行範例 Web API

在您的程式代碼編輯器中，開啟 2-Authorization/1-call-own-api-aspnet-core-mvc/ToDoListAPI/appsettings.json 檔案。
尋找佔位元：
- Enter_the_Application_Id_Here 並將它取代為您 稍早複製之 Web API 的應用程式（用戶端）識別碼 。
- Enter_the_Tenant_Id_Here 並將它取代為您稍早複製的 目錄（租用戶）標識符 。
- Enter_the_Tenant_Subdomain_Here 並將它取代為 Directory （tenant）子域。例如，如果您的租使用者主要網域是 contoso.onmicrosoft.com，請使用 contoso。如果您沒有租用戶名稱，請瞭解如何閱讀您的租使用者詳細數據。

您必須裝載 Web API，讓 iOS 範例應用程式呼叫它。請遵循快速入門：部署 ASP.NET Web 應用程式以部署您的 Web API。

設定範例 iOS 行動應用程式以呼叫 Web API

在您的 Xcode 中，開啟 /NativeAuthSampleApp/ProtectedAPIViewController.swift 檔案。

使用您的 Web API URL 尋找 Enter_the_Protected_API_Full_URL_Here 並取代此值。

let protectedAPIUrl = "Enter_the_Protected_API_Full_URL_Here" // Developers should set the respective URL of their web API here

尋找 Enter_the_Protected_API_Scopes_Here 並設定授與 API 許可權中記錄的範圍給 iOS 範例應用程式。

let protectedAPIScopes = ["Enter_the_Protected_API_Scopes_Here"] // Developers should set the respective scopes of their web API here.For example, let protectedAPIScopes = ["api://{clientId}/{ToDoList.Read}","api://{clientId}/{ToDoList.ReadWrite}"]

執行 iOS 範例應用程式並呼叫 Web API

若要建置並執行您的應用程式，請遵循下列步驟：

若要建置並執行您的程式碼，請從 Xcode 中的 [產品] 選單選取 [執行]。成功建置之後，Xcode 會在模擬器中啟動範例應用程式。
選取 [API] 索引標籤以測試 API 呼叫。成功呼叫 Web API 會傳回 HTTP ，而 HTTP 200403 表示未經授權的存取。

下一步

教學課程：準備 iOS 應用程式以進行原生驗證。

分享方式：