共用方式為

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

  • 發行項

適用於：具有灰色 X 符號的白色圓圈。 工作群體租戶 具有白色複選標記的綠色圓圈。 外部租戶（深入瞭解）

在本快速入門中，您將瞭解如何設定範例 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 的存取令牌時，它會新增 URI 作為您為 API 定義之每個範圍的前置詞。

  5. 在這裡 API 定義的範圍下，選取 [[新增範圍]。

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

    財產 價值
    範圍名稱 ToDoList.Read
    誰可以同意 僅 系統管理員
    管理員同意顯示名稱 使用 'TodoListApi' 讀取使用者的 'ToDo' 清單
    管理員同意描述 允許應用程式使用 『TodoListApi』讀取使用者的 ToDo 清單。
    州 已啟用

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

    財產 價值
    範圍名稱 待辦清單.讀寫
    誰可以同意 只有 系統管理員
    管理員同意顯示名稱 使用 『ToDoListApi』 讀取和寫入使用者 ToDo 清單
    管理員同意描述 允許應用程式使用 『ToDoListApi』 來讀取和寫入使用者的 ToDo 清單
    州 已啟用

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

  9. 將 accessTokenAcceptedVersion 屬性設定為 2。

  10. 選取 儲存。

了解有關最低許可權原則的更多資訊，以便在發布 Web API 的許可權時應用。

設定應用程式角色

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

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

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

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

    財產 價值
    顯示名稱 ToDoList.Read.All
    允許的成員類型 應用程式
    價值 待辦事項清單.讀取.全部
    描述 允許應用程式使用 『TodoListApi』 讀取每個使用者的 ToDo 清單

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

    財產 價值
    顯示名稱 ToDoList.ReadWrite.All
    允許的成員類型 應用程式
    價值 ToDoList.ReadWrite.All
    描述 允許應用程式使用 『ToDoListApi』 讀取和寫入每個使用者的 ToDo 清單

設定選擇性宣告

您可以新增 idtyp 選擇性宣告，以協助 Web API 判斷令牌是應用程式令牌還是應用程式 + 使用者令牌。 雖然您可以將 scp 和 角色的組合 用於相同的目的，但使用 idtyp 宣告是區分應用程式令牌和應用程式 + 使用者令牌最簡單的方法。 例如，當令牌是僅應用程式專用令牌時，此宣告的值為 應用程式。

將 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，並將它取代為 Directory （tenant） 子域。 例如，如果您的租用者主要網域是 contoso.onmicrosoft.com，請使用 contoso。 如果您沒有租戶名稱，請瞭解如何 查看您的租戶詳細資料。

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

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

此範例可讓您設定多個 Web API URL 端點和範圍集合。 在此情況下，您只會設定一個 Web API URL 端點及其相關聯的範圍。

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

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

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

  3. 尋找名為 scopesForAPI1 的屬性，並將在 中記錄的範圍設定為 Android 範例應用程式的 API 許可權。

    private val scopesForAPI1 = 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 模擬器或連線實體裝置。

  3. 選取 執行 按鈕。 應用程式會在電子郵件和單次密碼畫面上開啟。

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

後續步驟

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