快速入門：在範例行動應用程式中登入使用者

適用於： 勞動力租用者 外部租用者（深入瞭解）

開始之前，請在此頁面頂端使用「選擇租用戶類型」選取器來選擇租用戶類型。 Microsoft Entra ID 提供兩種租戶組態，員工 和 外部。 員工租戶配置適用於您的員工、內部應用程式和其他組織資源。 外部租戶適用於面向客戶的應用程式。

安卓

在本快速入門中，您會下載並執行程式碼範例，該範例會示範 Android 應用程式如何登入使用者，並取得存取權杖來呼叫 Microsoft Graph API。

應用程式必須以 Microsoft Entra ID 中的應用程式物件表示，讓 Microsoft 身分識別平台能夠為您的應用程式提供權杖。

iOS/macOS

在本快速入門中，您會下載並執行程式碼範例，示範原生 iOS 或 macOS 應用程式如何登入使用者，並取得存取令牌來呼叫 Microsoft Graph API。

本快速入門同時適用於 iOS 和 macOS 應用程式。 某些步驟僅適用於 iOS 應用程式，因此會以此類方式指出。

先決條件

• 具有有效訂閱的 Azure 帳戶。 如果您還沒有帳戶，免費建立帳戶。
• 此 Azure 帳戶必須具有管理應用程式的權限。 下列任何 Microsoft Entra 角色都包含必要的權限:
  • 應用程式管理員
  • 應用程式開發人員
• 員工租戶。 您可以使用預設目錄或設定新的租戶。

安卓

• 在 Microsoft Entra 系統管理中心註冊新的應用程式，針對 任何組織目錄中的帳戶和個人Microsoft帳戶進行設定。 如需詳細資訊 ，請參閱註冊應用程式 。 從應用程式 [概 觀 ] 頁面記錄下列值，以供稍後使用：
  • 應用程式 （用戶端） 識別碼
  • 目錄（租戶）識別碼
• Android Studio
• 安卓 16+

iOS/macOS

• 在 Microsoft Entra 系統管理中心註冊新的應用程式， 僅針對此組織目錄中的帳戶進行設定。 如需詳細資訊 ，請參閱註冊應用程式 。 從應用程式 [概 觀 ] 頁面記錄下列值，以供稍後使用：
  • 應用程式 （用戶端） 識別碼
  • 目錄（租戶）識別碼
• XCode 10+
• iOS 10+
• macOS 10.12+

新增重新導向 URI

您必須在應用程式註冊中設定特定的重新導向 URI，以確保與下載的程式碼範例相容。 在使用者成功登入之後，這些 URI 對於將使用者重新導向回應用程式至關重要。

安卓

1. 在 [管理] 底下，選取 [驗證]>[新增平台]>[Android]。

2. 根據您下載的範例類型，輸入您的專案的套件名稱。

   • JAVA 範例- com.azuresamples.msalandroidapp
   • Kotlin 範例 - com.azuresamples.msalandroidkotlinapp

3. 在 [設定您的 Android 應用程式] 頁面的 [簽章雜湊] 區段中，選取 [產生開發簽章雜湊。]，然後將 KeyTool 命令複製到命令列。

   • KeyTool.exe 會安裝為 Java 開發套件 (JDK) 的一部分。 您也必須安裝 OpenSSL 工具來執行 KeyTool 命令。 如需詳細資訊，請參閱關於產生金鑰的 Android 文件。

4. 輸入 KeyTool 所產生的簽章雜湊。

5. 選取 [設定] 並儲存出現在 [Android 組態] 窗格中的 [MSAL 組態]，以便稍後在設定應用程式時可加以輸入。

6. 選擇 完成。

iOS/macOS

1. 在 [管理] 下，選取 [驗證]，>[新增平臺>iOS]。
2. 輸入應用程式的 套件組合標識碼。 套件組合識別碼是唯一識別應用程式的唯一字串，例如 com.<yourname>.identitysample.MSALMacOS。 記下您使用的值。 請注意，iOS 設定也適用於macOS應用程式。
3. 選取 [設定，然後儲存 MSAL 組態 詳細數據，以供本快速入門稍後使用。
4. 選擇 完成。

下載範例應用程式

安卓

• JAVA：下載程式碼。
• Kotlin：下載程式碼。

iOS/macOS

下載範例專案

• 下載 iOS 的程式代碼範例
• 下載macOS 的程式代碼範例

安裝依賴項

1. 擷取 zip 檔案。
2. 在終端機視窗中，流覽至具有下載程式碼範例的資料夾，然後執行 pod install 以安裝最新的 MSAL 連結庫。

設定範例應用程式

安卓

1. 在 Android Studio 的專案窗格中，瀏覽至 app\src\main\res。

2. 以滑鼠右鍵按下 res，然後選擇 [新增>目錄]。 輸入 raw 作為新的目錄名稱，然後選取 [確定]。

3. 在 [app]>[src]>[main]>[res]>[raw] 中，移至名為 auth_config_single_account.json 的新 JSON 檔案，並貼上您先前儲存的 [MSAL 設定]。

   在重新導向 URI 下方貼上：

     "account_mode" : "SINGLE",
   

   您的組態檔應該類似下列範例：

   {
     "client_id": "00001111-aaaa-bbbb-3333-cccc4444",
     "authorization_user_agent": "WEBVIEW",
     "redirect_uri": "msauth://com.azuresamples.msalandroidapp/00001111%cccc4444%3D",
     "broker_redirect_uri_registered": false,
     "account_mode": "SINGLE",
     "authorities": [
       {
         "type": "AAD",
         "audience": {
           "type": "AzureADandPersonalMicrosoftAccount",
           "tenant_id": "common"
         }
       }
     ]
   }
   

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

5. 尋找占位符：

   • enter_the_signature_hash 並將它取代為在您先前新增平臺重定向 URL 時所產生的 簽章哈希。

   本教學課程僅示範如何在單一帳戶模式中設定應用程式，請參閱單一與多個帳戶模式和設定應用程式以取得詳細資訊

執行範例應用程式

從 Android Studio 的可用裝置下拉式清單中選取您的模擬器或實體裝置，然後執行應用程式。

範例應用程式會在 [單一帳戶模式] 畫面上啟動。 依預設會提供預設範圍 user.read，這是在 Microsoft Graph API 呼叫期間讀取您自己的設定檔資料時所使用的範圍。 依預設會提供 Microsoft Graph API 呼叫的 URL。 您可以視需要變更這兩項設定。

使用應用程式功能表，在單一和多重帳戶模式之間進行變更。

在單一帳戶模式中，使用工作或主帳戶登入：

1. 選取 [以互動方式取得圖形資料]，以提示使用者輸入其認證。 您會在畫面底部看到 Microsoft Graph API 呼叫的輸出。
2. 登入之後，選取 [以無訊息方式取得圖形資料] 以呼叫 Microsoft Graph API，而不再次提示使用者提供認證。 您會在畫面底部看到 Microsoft Graph API 呼叫的輸出。

在多重帳戶模式中，您可以重複相同的步驟。 此外，您也可以移除已登入的帳戶，這也會同時清除該帳戶的快取憑證。

iOS/macOS

如果您選取上述選項 1，您可以略過這些步驟。

1. 在 XCode 中開啟專案。

2. 編輯 ViewController.swift，並以下列代碼段取代開頭為 'let kClientID' 的行。 請記得使用您稍早在本快速入門中註冊應用程式時所儲存的 clientID 來更新 kClientID 的值：

   let kClientID = "Enter_the_Application_Id_Here"
   

3. 如果您要為 Microsoft Entra 國家雲端開發應用程式，請將以 'let kGraphEndpoint' 和 'let kAuthority' 開頭的行替換為正確的端點。 針對全域存取，請使用預設值：

   let kGraphEndpoint = "https://graph.microsoft.com/"
   let kAuthority = "https://login.microsoftonline.com/common"
   

4. 其他端點已被記錄在這裡。 例如，若要使用 Microsoft Entra Germany 執行快速入門，請使用下列指令：

   let kGraphEndpoint = "https://graph.microsoft.de/"
   let kAuthority = "https://login.microsoftonline.de/common"
   

5. 開啟項目設定。 在 [身分識別] 區段中，輸入 套件組合標識碼。

6. 右鍵點擊 Info.plist，然後選取 開啟為>原始程式碼。

7. 在 dict 根節點底下，將 Enter_the_bundle_Id_Here 替換為您在入口網站中使用的 套件識別碼。 請注意字串中的 msauth. 前置詞。

   <key>CFBundleURLTypes</key>
   <array>
      <dict>
         <key>CFBundleURLSchemes</key>
         <array>
            <string>msauth.Enter_the_Bundle_Id_Here</string>
         </array>
      </dict>
   </array>
   

8. 建置並執行應用程式！

此範例的運作方式

安卓

程式碼會組織成片段，說明如何撰寫單一和多重帳戶 MSAL 應用程式。 程式碼檔案的組織方式如下：

檔案	演示
主要活動	管理 UI
MSGraphRequestWrapper	使用 MSAL 提供的授權憑證來呼叫 Microsoft Graph API
多帳號模式片段	初始化多重帳戶應用程式、載入使用者帳戶，並取得權杖以呼叫 Microsoft Graph API
單帳戶模式片段	初始化單一帳戶應用程式、載入使用者帳戶，並取得權杖以呼叫 Microsoft Graph API
res/auth_config_multiple_account.json	多重帳戶組態檔
res/auth_config_single_account.json	單一帳戶組態檔
Gradle Scripts/build.grade（模組：app）	在此新增 MSAL 程式庫依賴項

現在我們將更詳細地探討這些檔案，並指出每個檔案中 MSAL 特有的程式碼。

iOS/macOS

後續步驟

安卓

繼續進行 Android 教學課程，您可以在其中建置 Android 應用程式，從 Microsoft 身分識別平台取得存取權杖，並將其用來呼叫 Microsoft Graph API。

教學指南：使用 Android 應用程式登入使用者並呼叫 Microsoft Graph

iOS/macOS

接下來，移至逐步教學指南，您將建置一個 iOS 或 macOS 應用程式，從 Microsoft 身分識別平台取得存取令牌，並使用它來呼叫 Microsoft Graph API。

教學課程：從iOS或macOS應用程式登入使用者並呼叫 Microsoft Graph

快速入門會引導您設定範例 Android、.NET MAUI Android 和 iOS/macOS 應用程式，藉由註冊應用程式、設定重新導向 URL、更新設定及測試應用程式來登入使用者。

先決條件

• 具有有效訂閱的 Azure 帳戶。 如果您還沒有帳戶，免費建立帳戶。
• 此 Azure 帳戶必須具有管理應用程式的權限。 下列任何 Microsoft Entra 角色都包含必要的權限:
  • 應用程式管理員
  • 應用程式開發人員
• 外部租戶。 若要建立一個，請從下列方法中選擇：
  • 使用 Microsoft Entra External ID 擴充功能 直接在 Visual Studio Code 中設定外部租戶。 (建議使用)
  • 在 Microsoft Entra 管理中心中建立新的外部租戶。
• 在 Microsoft Entra 系統管理中心註冊新的應用程式， 僅針對此組織目錄中的帳戶進行設定。 如需詳細資訊 ，請參閱註冊應用程式 。 從應用程式 [概 觀 ] 頁面記錄下列值，以供稍後使用：
  • 應用程式 （用戶端） 識別碼
  • 目錄（租戶）識別碼

安卓

• Android Studio。

Android（.NET MAUI）

• 使用者流程。 如需詳細資訊，請參閱 為外部租使用者中的應用程式建立自助式註冊使用者流程。 此使用者流程可用於多個應用程式。
• 將應用程式新增至使用者流程。
• .NET 7.0 開發工具包
• 已安裝 MAUI 工作負載的 Visual Studio 2022：
  • Windows 使用說明
  • macOS 使用指南

iOS/macOS

• Xcode。

新增平臺重定向 URL

您必須在應用程式註冊中設定特定的重新導向 URI，以確保與下載的程式碼範例相容。 在使用者成功登入之後，這些 URI 對於將使用者重新導向回應用程式至關重要。

安卓

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

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

啟用公開客戶端流程

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

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

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

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

Android（.NET MAUI）

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

1. 在 [管理] 底下，選取 [驗證]。
2. 在 [平台設定] 頁面上，選取 [新增平台]，然後選取 [行動應用程式和傳統型應用程式] 選項。
3. 針對 重新導向 URI，將 msal{client_id}://auth 輸入。 請確定 {client_id} 符合應用程式註冊的值。 選取[]，然後設定[]。
4. 選取儲存以儲存變更。

iOS/macOS

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

1. 在 [管理] 底下，選取 [驗證]。
2. 在 [平臺組態] 頁面上，選取 [新增平臺]，然後選取 [iOS / macOS] 選項。
3. 輸入專案的套件組合識別碼。 若已下載範例程式碼，則此值為 com.microsoft.identitysample.ciam.MSALiOS。
4. 選取 [設定]，然後儲存 MSAL 組態，這會出現在 [iOS / macOS 組態] 窗格中，以便稍後設定應用程式時輸入。
5. 選擇 完成。

啟用公開客戶端流程

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

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

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

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

複製應用程式範例

安卓

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

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

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

Android（.NET MAUI）

若要取得 .NET MAUI Android 應用程式樣本程式碼，請下載此 .zip 檔案，或執行下列命令，從 GitHub 複製 .NET MAUI Android 應用程式樣本：

git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git

iOS/macOS

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

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

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

設定範例應用程式

安卓

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

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

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

3. 尋找占位符：

   • Enter_the_Application_Id_Here，然後用您稍早註冊的應用程式的 應用程式（用戶端）ID 取代它。
   • Enter_the_Redirect_Uri_Here，並使用您稍早加入平台重定向 URL 時所下載的 Microsoft 驗證庫 (MSAL) 組態檔中的 redirect_uri 值來取代它。
   • Enter_the_Tenant_Subdomain_Here，並將它取代為 Directory （tenant） 子域。 例如，如果您的租戶主要網域為 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. 尋找名為 scopes 的屬性，並設定 授與管理員同意中所記錄的範圍。 如果您尚未記錄任何範圍，您可以將此範圍清單保留空白。

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

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

Android（.NET MAUI）

1. 在 Visual Studio 中，開啟 ms-identity-ciam-dotnet-tutorial-main/1-Authentication/2-sign-in-maui/appsettings.json 檔案。
2. 尋找佔位符
   1. Enter_the_Tenant_Subdomain_Here，並將它取代為 Directory （tenant） 子域。 例如，如果您的租戶主要網域為 contoso.onmicrosoft.com，則請使用 contoso。 如果您沒有租用戶名稱，請了解如何讀取租用戶詳細資料。
   2. Enter_the_Application_Id_Here，然後用您稍早註冊的應用程式的 應用程式（用戶端）ID 取代它。
3. 在 Visual Studio 中，開啟 ms-identity-ciam-dotnet-tutorial-main/1-Authentication/2-sign-in-maui/Platforms/Android/AndroidManifest.xml 檔案。
4. 尋找佔位符
   1. Enter_the_Application_Id_Here，然後用您稍早註冊的應用程式的 應用程式（用戶端）ID 取代它。

iOS/macOS

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

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

2. 開啟 /MSALiOS/Configuration.swift 檔案。

3. 尋找占位符：

   • Enter_the_Application_Id_Here，然後用您稍早註冊的應用程式的 應用程式（用戶端）ID 取代它。
   • Enter_the_Redirect_URI_Here 並將它取代為您稍早新增平臺重新導向 URL 時所下載Microsoft驗證連結庫 （MSAL） 組態檔中的 kRedirectUri 值。
   • Enter_the_Protected_API_Scopes_Here 並將它取代為 授與管理員同意中所記錄的範圍。 如果您尚未記錄任何範圍，您可以將此範圍清單保留空白。
   • Enter_the_Tenant_Subdomain_Here，並將它取代為 Directory （tenant） 子域。 例如，如果您的租戶主要網域為 contoso.onmicrosoft.com，則請使用 contoso。 如果您不知道租戶子網域，請瞭解如何 查看租戶的詳細資訊。

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

執行及測試範例應用程式

安卓

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

1. 在工具列中，從 [執行組態] 功能選取您的應用程式。

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

   如果您沒有設定任何裝置，您必須建立 Android 虛擬設備以使用 Android 模擬器或連線實體 Android 裝置。

3. 選取 執行 按鈕。

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

5. 如果您選取 [API - 執行 GET ] 來呼叫受保護的 ASP.NET Core Web API，您將會收到錯誤。

如需呼叫受保護 Web API 的詳細資訊，請參閱 後續步驟

Android（.NET MAUI）

.NET MAUI 應用程式已設計為可在多個作業系統和裝置上執行。 您必須選取您要用來測試和偵錯應用程式的目標。

將 Visual Studio 工具列中的 [偵錯目標] 設定為您想要進行偵錯和測試的裝置。 下列步驟示範如何將 偵錯目標 設定為 Android：

1. 選取 [偵錯目標] 下拉式清單。
2. 選擇 Android 模擬器。
3. 選取模擬器裝置。

按 F5 或選取 Visual Studio 頂端的「播放按鈕」，以執行應用程式。

1. 您現在可以測試範例 .NET MAUI Android 應用程式。 執行應用程式之後，Android 應用程式視窗會出現在模擬器中：

   

2. 在出現的 Android 視窗中，選取 登入 按鈕。 瀏覽器視窗隨即開啟，系統會提示您登入。

   

   在登入過程中，系統會提示您授與各種許可權（允許應用程式存取您的數據）。 成功登入並同意後，應用程式畫面會顯示主頁面。

   

iOS/macOS

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

1. 若要建置並執行程式碼，請從 Xcode 的 產品 選單中選取 執行。 成功建置之後，Xcode 會在模擬器中啟動範例應用程式。
2. 選取 [以互動方式取得令牌 ] 以要求存取令牌。
3. 如果您選取 [API - 執行 GET ] 來呼叫受保護的 ASP.NET Core Web API，您將會收到錯誤。

如需呼叫受保護 Web API 的詳細資訊，請參閱 後續步驟

後續步驟

安卓

• 在 Android 範例 （Kotlin） 應用程式中登入使用者並呼叫受保護的 Web API。

Android（.NET MAUI）

• 自訂預設商標。
• 使用Google設定登入。

iOS/macOS

• 在範例 iOS （Swift） 應用程式中登入使用者並呼叫受保護的 Web API。