共用方式為

使用原生驗證在範例 iOS 行動應用程式中將使用者登入及呼叫 API

  • 發行項

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

必要條件

註冊 Web API 應用程式

  1. 至少以應用程式開發人員的身分登入 Microsoft Entra 系統管理中心。

  2. 如果您有權存取多個租用戶，請使用頂端功能表中的 [設定] 圖示 ，以從 [目錄 + 訂用帳戶] 功能表切換至您的外部租用戶。

  3. 瀏覽至 [身分識別] > [應用程式] > [應用程式註冊]。

  4. 選取 + 新增註冊。

  5. 在出現的 [註冊應用程式] 頁面 中，輸入應用程式的註冊資訊：

    1. 在 [名稱] 區段中，輸入將向應用程式使用者顯示的有意義應用程式名稱，例如 ciam-ToDoList-api。

    2. 在 [支援的帳戶類型] 底下，選取 [僅在此組織目錄中的帳戶]。

  6. 選取 [暫存器] 以建立應用程式。

  7. 註冊完成時，將會顯示應用程式的 [概觀] 窗格。 記錄 [目錄 (租用戶) 識別碼] 和 [應用程式 (用戶端) 識別碼]，以用於您的應用程式原始程式碼。

設定 API 範圍

API 必須發佈至少一個範圍 (也稱為委派權限 (部分機器翻譯))，用戶端應用程式才能成功取得使用者的存取權杖。 若要發佈範圍，請遵循下列步驟：

  1. 從 [應用程式註冊] 頁面，選取您建立的 API 應用程式 (ciam-ToDoList-api)，以開啟其 [概觀] 頁面。

  2. 在 [管理] 底下，選取 [公開 API]。

  3. 在頁面頂端的 [應用程式識別碼 URI] 旁邊，選取 [新增] 連結，以針對此應用程式產生唯一的 URI。

  4. 接受建議的應用程式識別碼 URI (例如 api://{clientId})，然後選取 [儲存]。 當您的 Web 應用程式要求 Web API 的存取權杖時，即會新增此 URI 作為您針對 API 所定義之每個範圍的前置詞。

  5. 在 [由此 API 定義的範圍] 底下，選取 [新增範圍]。

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

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

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

    屬性 數值
    範圍名稱 ToDoList.ReadWrite
    有權同意者 僅限管理員
    管理員同意顯示名稱 使用 'TodoListApi' 讀取和寫入使用者的待辦事項清單
    管理員同意描述 允許應用程式使用 'TodoListApi' 讀取和寫入使用者的待辦事項清單
    州/省 已啟用

  8. 在 [管理] 底下，選取 [資訊清單] 以開啟 API 資訊清單編輯器。

  9. 將 accessTokenAcceptedVersion 屬性設定為 2。

  10. 選取 [儲存]。

深入了解針對 Web API 發佈權限時的最低權限準則 (部分機器翻譯)。

設定應用程式角色

API 必須為應用程式至少發佈一個應用程式角色 (也稱為應用程式權限)，用戶端應用程式才能以自身身分取得存取權杖。 應用程式權限是 API 應該在想要讓用戶端應用程式能夠以自身身分成功驗證，且不需登入使用者時發佈的權限類型。 若要發佈應用程式權限，請遵循下列步驟：

  1. 從 [應用程式註冊] 頁面中，選取您建立的應用程式 (例如 ciam-ToDoList-api)，以開啟其 [概觀] 頁面。

  2. 在 [管理] 下方，選取 [應用程式角色]。

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

    屬性 數值
    Display name ToDoList.Read.All
    允許的成員類型 應用程式
    值 ToDoList.Read.All
    描述 允許應用程式使用 'TodoListApi' 讀取每位使用者的待辦事項清單

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

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

設定選擇性宣告

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

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

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

  1. 從 [應用程式註冊] 頁面，選取您建立的應用程式 (例如 ciam-client-app)，以開啟其 [概觀] 頁面。

  2. 在 [管理] 之下選取 [API 權限]。

  3. 在 [已設定的權限] 底下，選取 [新增權限]。

  4. 選取 [我的組織使用的 API] 索引標籤。

  5. 在 API 清單中，選取 API，例如 ciam-ToDoList-api。

  6. 選取 [委派的權限] 選項。

  7. 從權限清單，選取 [ToDoList.Read]、[ToDoList.ReadWrite] (如有必要，請使用搜尋方塊)。

  8. 選取 [新增權限] 按鈕。

  9. 此時，您已正確獲指派權限。 不過，由於租用戶是客戶的租用戶，因此取用者使用者本身無法同意這些權限。 若要解決此問題，身為系統管理員，您必須代表租用戶中的所有使用者同意此權限：

    1. 選取 [代表 <您的租用戶名稱> 授與管理員同意]，接著選取 [是]。

    2. 選取 [重新整理]，然後驗證 [已授與 <您的租用戶名稱>] 是否顯示在這兩個權限的 [狀態] 下方。

  10. 從 [已設定權限] 清單中，選取 [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

  1. 在程式碼編輯器中，開啟 2-Authorization/1-call-own-api-aspnet-core-mvc/ToDoListAPI/appsettings.json 檔案。

  2. 尋找預留位置：

    • Enter_the_Application_Id_Here，並將其取代為您稍早複製之 Web API 的 [應用程式 (用戶端) 識別碼]。
    • Enter_the_Tenant_Id_Here，並將其取代為您稍早複製的 [目錄 (租用戶) 識別碼]。
    • Enter_the_Tenant_Subdomain_Here 並將其取代為目錄 (租用戶) 子網域。 例如，若租用戶主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租用戶名稱，請了解如何讀取租用戶詳細資料。

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

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

此範例可讓您設定多個 Web API URL 端點和範圍。 在此案例，您只需設定一個 Web API URL 端點及其關聯的範圍。

  1. 在您的 Xcode 中，開啟 /NativeAuthSampleApp/ProtectedAPIViewController.swift 檔案。 如果您使用 macOS，請參閱以下樣本 ProtectedAPIViewController.swift 程式碼檔案。

  2. 尋找 protectedAPIUrl1 並輸入 Web API URL 作為其值。

    let protectedAPIUrl1: String? = nil // Developers should set the respective URL of their web API here. For example let protectedAPIUrl1: String? = "https://api.example.com/v1/resource"

  3. 尋找 protectedAPIScopes1，並設定在將 API 權限授與 iOS 範例應用程式中所記錄的範圍。

    let protectedAPIScopes1: [String] = [] // 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

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

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

下一步