分享方式：

在範例 Android (Kotlin) 應用程式中登入使用者並呼叫受保護的 Web API

  • 文章

本指南示範如何設定範例 Android 行動應用程式來登入使用者，以及呼叫 ASP.NET Core Web API。

在本文中，您將執行下列工作：

  • 在 Microsoft Entra 系統管理中心註冊應用程式。
  • 新增平台重新導向 URL。
  • 啟用公用用戶端流程。
  • 更新 Android 設定程式碼範例檔案，即可對客戶租用戶詳細資料使用您自己的 Microsoft Entra External ID。
  • 執行和測試範例 Android 行動應用程式。
  • 呼叫受保護的 Web API。

必要條件

  • Android Studio.

  • 一個外部租用戶。 如果您還沒有租用戶，請註冊取得免費試用。

  • 公開至少一個範圍 (委派的權限) 和一個應用程式角色 (應用程式權限) 的 API 註冊，例如 ToDoList.Read。 若尚未這麼做，請遵循在範例 Android 行動應用程式中呼叫 API 的指示，以擁有受功能保護的 ASP.NET Core web API。 請務必完成下列步驟：

    • 註冊 Web API 應用程式
    • 設定 API 範圍
    • 設定應用程式角色
    • 設定選擇性宣告
    • 複製或下載範例 Web API
    • 設定和執行範例 Web API

註冊應用程式

若要讓應用程式能夠使用 Microsoft Entra 登入使用者，Microsoft Entra 外部 ID 必須知道您建立的應用程式。 應用程式註冊會在應用程式與 Microsoft Entra 之間建立信任關係。 註冊應用程式時，外部 ID 會產生稱為「應用程式 (用戶端) 識別碼」的唯一識別碼，這個值可在建立驗證要求時用來識別您的應用程式。

下列步驟顯示如何在 Microsoft Entra 系統管理中心內註冊您的應用程式：

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

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

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

  4. 選取 + 新增註冊。

  5. 在出現的 [註冊應用程式] 頁面中；

    1. 輸入要向應用程式使用者顯示的有意義應用程式「名稱」，例如 ciam-client-app。
    2. 在 [支援的帳戶類型] 底下，選取 [僅在此組織目錄中的帳戶]。

  6. 選取註冊。

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

新增平台重新導向 URL

若要在應用程式註冊中指定您的應用程式類型，請遵循下列步驟：

  1. 在 [管理] 底下，選取 [驗證]。
  2. 在 [平台設定] 頁面中，選取 [新增平台]，然後選取 [Android] 選項。
  3. 輸入您專案的套件名稱。 若已下載範例程式碼，則此值為 com.azuresamples.msaldelegatedandroidkotlinsampleapp。
  4. 在 [設定 Android 應用程式] 窗格的 [簽章雜湊] 區段中，選取 [產生開發簽章雜湊。這將隨著每個開發環境而變更]。在終端機中複製並執行適用於作業系統的 KeyTool 命令。
  5. 輸入 KeyTool 所產生的簽章雜湊。
  6. 選取設定。
  7. 從 [Android 設定] 窗格複製 [MSAL 設定] 並儲存，以供稍後的應用程式組態使用。
  8. 選取完成。

啟用公用用戶端流程

若要將您的應用程式識別為公用用戶端，請遵循下列步驟：

  1. 在 [管理] 底下，選取 [驗證]。

  2. 在 [進階設定] 下方的 [允許公用用戶端流程]，選取 [是]。

  3. 選取儲存以儲存變更。

註冊應用程式之後，就會獲 指派User.Read 許可權。 不過，由於租使用者是外部租使用者，因此客戶使用者本身無法同意此許可權。 身為管理員的您必須代表租用戶中的所有使用者同意此權限：

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

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

    1. 選取 [代表 <您的租用戶名稱> 授與管理員同意]，然後選取 [是]。
    2. 選取 [重新整理]，然後確認 [為租用戶名稱>授與] <出現在許可權的 [狀態] 底下。

將 Web 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} 類似。

複製範例 Android 行動應用程式

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

  • 若要複製範例，請開啟命令提示字元，並瀏覽至您想要建立專案的位置，然後輸入下列命令：

    git clone https://github.com/Azure-Samples/ms-identity-ciam-browser-delegated-android-sample

設定範例 Android 行動應用程式

若要啟用 Web API 資源的驗證和存取，請遵循下列步驟來設定範例：

  1. 在 Android Studio 中，開啟您複製的專案。

  2. 開啟 /app/src/main/res/raw/auth_config_ciam.json 檔案。

  3. 尋找預留位置：

    • Enter_the_Application_Id_Here，並將其取代為您稍早註冊的應用程式所使用的應用程式 (用戶端) 識別碼。
    • Enter_the_Redirect_Uri_Here，並將其取代為您稍早新增平台重新導向 URL 時所下載的 Microsoft 驗證程式庫 (MSAL) 組態檔中的 redirect_uri 值。
    • Enter_the_Tenant_Subdomain_Here，並將其取代為目錄 (租用戶) 子網域。 例如，若租用戶主要網域是 contoso.onmicrosoft.com，請使用 contoso。 若不知道租用戶子網域，請了解如何讀取租用戶詳細資料。

  4. 開啟 /app/src/main/AndroidManifest.xml 檔案。

  5. 尋找預留位置：

    • ENTER_YOUR_SIGNATURE_HASH_HERE，並將其取代為您稍早新增平台重新導向 URL 時所產生的簽章雜湊。

  6. 開啟 /app/src/main/java/com/azuresamples/msaldelegatedandroidkotlinsampleapp/MainActivity.kt 檔案。

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

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

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

您已設定應用程式，且準備好執行。

執行和測試範例 Android 行動應用程式

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

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

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

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

  3. 選取 [執行] 按鈕。

  4. 選取 [以互動方式取得權杖] 以要求存取權杖。

  5. 選取 [API - 執行 GET] 以呼叫先前設定的 ASP.NET Core Web API。 成功呼叫 Web API 會傳回 HTTP 200，而 HTTP 403 表示未經授權的存取。

相關內容