分享方式：

使用原生驗證在範例 Android 行動裝置應用程式中登入使用者並呼叫 API

  • 文章

本文示範如何設定範例 Android 行動應用程式來呼叫 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 的存取權杖時，您為該 API 定義的每個範圍都會加上此 URI 作為前置詞。

  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 權限授與 Android 範例應用程式

一旦您註冊了用戶端應用程式和 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 以供 Android 範例應用程式進行呼叫。 若要部署您的 Web API，請遵循快速入門：部署 ASP.NET Web 應用程式 (部分機器翻譯)。

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

  1. 在您的 Android Studio 中，開啟 /app/src/main/java/com/azuresamples/msalnativeauthandroidkotlinsampleapp/AccessApiFragment.kt 檔案。

  2. 尋找名為 WEB_API_BASE_URL 的屬性，並將 URL 設定為您的 Web API。

    private const val WEB_API_BASE_URL = "" // Developers should set the respective URL of their web API here

  3. 尋找名為 scopes 的屬性，並設定將 API 權限授與 Android 範例應用程式中所記錄的範圍。

    private val scopes = listOf<String>() // Developers should set the respective scopes of their web API here. For example, private val scopes = listOf<String>("api://{clientId}/{ToDoList.Read}", "api://{clientId}/{ToDoList.ReadWrite}")

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

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

  1. 在工具列中，從執行設定功能表選取您的應用程式。

  2. 在目標裝置功能表中，選取您要執行應用程式的裝置。

    如果您未設定任何裝置，則必須建立 Android 虛擬設備以使用 Android Emulator 或連線至實體裝置。

  3. 選取 [執行] 按鈕。 應用程式開啟時會顯示電子郵件和一次性密碼畫面。

  4. 選取 [API] 索引標籤以測試 API 呼叫。 成功呼叫 Web API 會傳回 HTTP 200，而 HTTP 403 表示未經授權的存取。

下一步