教學課程：在 Android 應用程式新增共用裝置模式支援

在本教學課程中，Android 開發人員了解如何使用適用於 Android 的 Microsoft 驗證庫 (MSAL) 在 Android 應用程式新增共用裝置模式支援。

在本教學課程中：

• 建立或修改現有的 Android 應用程式專案。
• 啟用和偵測共用裝置模式
• 偵測單一或多個帳戶模式
• 偵測使用者切換
• 啟用全域登入和登出

建立或修改現有的 Android 應用程式

若要完成本教學課程的其餘部分，必須建立新的 Android 應用程式或修改現有的 Android 應用程式。 如果您還沒這樣做，請參閱 MSAL Android 教學課程，以取得如何整合 MSAL 與 Android 應用程式、登入使用者、呼叫 Microsoft Graph 及登出使用者的指導。 如果您偏好使用已完成的程式碼範例來進行學習與測試，請從 GitHub 複製應用程式範例。 此範例可在單一或多個帳戶模式中使用。

將 MSAL SDK 新增至您的本機 Maven 存放庫

如果您不是使用範例應用程式，請將 MSAL 程式庫新增為 build.gradle 檔案中的相依性，如下所示：

dependencies{
  implementation 'com.microsoft.identity.client.msal:4.9.+'
}

新增單一帳戶模式的支援

使用 Microsoft 驗證程式庫 (MSAL) SDK 所撰寫的應用程式，可以管理單一帳戶或多個帳戶。 如需詳細資料，請參閱單一帳戶模式或多帳戶模式。

您應用程式可用的 Microsoft 身分識別平台功能會有所不同，取決於應用程式是在單一帳戶模式還是多帳戶模式中執行。

共用裝置模式應用程式只能在單一帳戶模式下運作。

重要

僅支援多帳戶模式的應用程式無法在共用裝置上執行。 如果員工載入不支援單一帳戶模式的應用程式，其不會在共用裝置上執行。

在 MSAL SDK 發行之前所撰寫的應用程式，會在多帳戶模式下執行，而且必須更新為支援單一帳戶模式，然後才能在共用模式裝置上執行。 同時支援單一帳戶和多帳戶

您可以建置應用程式，以支援同時在個人裝置和共用裝置上執行。 如果您的應用程式目前支援多個帳戶，而且您想要支援共用裝置模式，請新增單一帳戶模式的支援。

您也可能想要應用程式變更其行為，取決於其執行所在的裝置類型。 使用 ISingleAccountPublicClientApplication.isSharedDevice() 來決定何時要在單一帳戶模式下執行。

有兩個不同的介面，代表您應用程式所在的裝置類型。 當您從 MSAL 的應用程式工廠要求應用程式執行個體時，系統會自動提供正確的應用程式物件。

下列物件模型說明您可能會收到的物件類型，以及其在共用裝置內容中的意義：

在取得 PublicClientApplication 物件時，必須進行類型檢查並轉換成適當的介面。 下列程式碼會檢查多帳戶模式或單一帳戶模式，並相應地轉換應用程式物件：

private IPublicClientApplication mApplication;

        // Running in personal-device mode?
        if (mApplication instanceOf IMultipleAccountPublicClientApplication) {
          IMultipleAccountPublicClientApplication multipleAccountApplication = (IMultipleAccountPublicClientApplication) mApplication;
          ...
        // Running in shared-device mode?
        } else if (mApplication instanceOf ISingleAccountPublicClientApplication) {
           ISingleAccountPublicClientApplication singleAccountApplication = (ISingleAccountPublicClientApplication) mApplication;
            ...
        }

下列差異適用，取決於您的應用程式是在共用裝置還是在個人裝置上執行：

	共用模式裝置	個人裝置
帳戶	單一帳戶	多個帳戶
登入	全球	全球
登出	全球	每個應用程式都可以控制登出是在應用程式的本機進行。
支援的帳戶類型	僅限工作帳戶	支援的個人和工作帳戶

將您的應用程式設定為使用共用裝置模式

如需有關設定組態檔的詳細資訊，請參閱設定文件。

在 MSAL 組態檔中，將 "shared_device_mode_supported" 設定為 true。

您可能並沒有打算支援多帳戶模式。 此情況可能是您並非使用共用裝置，而且使用者可以同時使用一個以上的帳戶登入應用程式。 若是如此，請將 "account_mode" 設定為 "SINGLE"。 這可保證您的應用程式一律會取得 ISingleAccountPublicClientApplication，並大幅簡化您的 MSAL 整合。 "account_mode" 的預設值是 "MULTIPLE"，因此若使用 "single account" 模式，請務必在組態檔中變更此值。

以下是 auth_config.json 檔案的範例，包含在範例應用程式的 app>main>res>raw 目錄中：

{
  "client_id": "Client ID after app registration at https://aka.ms/MobileAppReg",
  "authorization_user_agent": "DEFAULT",
  "redirect_uri": "Redirect URI after app registration at https://aka.ms/MobileAppReg",
  "account_mode": "SINGLE",
  "broker_redirect_uri_registered": true,
  "shared_device_mode_supported": true,
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

偵測共用裝置模式

共用裝置模式可讓您將 Android 裝置設定為可由多個員工共用，同時為裝置提供 Microsoft 身分識別支援的管理方式。 員工可以登入他們的裝置，並快速存取客戶資訊。 在他們完成輪班或工作時，只要按一下就能登出共用裝置上所有應用程式，而裝置可立即供下一位員工使用。

使用 isSharedDevice() 判斷應用程式是否在使用共用裝置模式的裝置上執行。 您的應用程式可以使用此旗標來判斷是否應該據此修改 UX。

以下是說明如何使用 isSharedDevice() 的程式碼片段。 其來自範例應用程式中的 SingleAccountModeFragment 類別：

deviceModeTextView.setText(mSingleAccountApp.isSharedDevice() ? "Shared" : "Non-Shared");

初始化 PublicClientApplication 物件

如果您在 MSAL 設定檔中設定 "account_mode":"SINGLE"，則可以將傳回的應用程式物件安全地轉換為 ISingleAccountPublicCLientApplication。

private ISingleAccountPublicClientApplication mSingleAccountApp;

/*Configure your sample app and save state for this activity*/
PublicClientApplication.create(this.getApplicationCOntext(),
  R.raw.auth_config,
  new PublicClientApplication.ApplicationCreatedListener(){
  @Override
  public void onCreated(IPublicClientApplication application){
  mSingleAccountApp = (ISingleAccountPublicClientApplication)application;
  loadAccount();
  }
  @Override
  public void onError(MsalException exception){
  /*Fail to initialize PublicClientApplication */
  }
});

偵測單一與多個帳戶模式

若撰寫的應用程式只會用於共用裝置上的一線工作者角色，建議您將應用程式撰寫為只支援單一帳戶模式。 這包括大部分以工作為主的應用程式，例如醫療記錄應用程式、發票應用程式，以及大多數的企業營運應用程式。 這可簡化您的開發，因為不需要容納 SDK 的許多功能。

若應用程式支援多個帳戶及共用裝置模式，您必須執行類型檢查並轉換成適在的介面，如下所示。

private IPublicClientApplication mApplication;

        if (mApplication instanceOf IMultipleAccountPublicClientApplication) {
          IMultipleAccountPublicClientApplication multipleAccountApplication = (IMultipleAccountPublicClientApplication) mApplication;
          ...
        } else if (mApplication instanceOf    ISingleAccountPublicClientApplication) {
           ISingleAccountPublicClientApplication singleAccountApplication = (ISingleAccountPublicClientApplication) mApplication;
            ...
        }

取得已登入的使用者，並判斷裝置上的使用者是否已變更

loadAccount 方法會擷取登入使用者的帳戶。 onAccountChanged 方法會判斷登入的使用者是否已變更，如果是，則執行清除作業：

private void loadAccount()
{
  mSingleAccountApp.getCurrentAccountAsync(new ISingleAccountPublicClientApplication.CurrentAccountCallback())
  {
    @Override
    public void onAccountLoaded(@Nullable IAccount activeAccount)
    {
      if (activeAccount != null)
      {
        signedInUser = activeAccount;
        mSingleAccountApp.acquireTokenSilentAsync(SCOPES,"http://login.microsoftonline.com/common",getAuthSilentCallback());
      }
    }
    @Override
    public void onAccountChanged(@Nullable IAccount priorAccount, @Nullable Iaccount currentAccount)
    {
      if (currentAccount == null)
      {
        //Perform a cleanup task as the signed-in account changed.
        updateSingedOutUI();
      }
    }
    @Override
    public void onError(@NonNull Exception exception)
    {
    }
  }
}

全域登入使用者

下列動作會將裝置上的使用者登入搭配使用 MSAL 和 Authenticator 應用程式的其他應用程式：

private void onSignInClicked()
{
  mSingleAccountApp.signIn(getActivity(), SCOPES, null, getAuthInteractiveCallback());
}

全域登出使用者

下列動作會移除已登入的帳戶，並從應用程式和使用共用裝置模式的裝置中清除快取權杖：

private void onSignOutClicked()
{
  mSingleAccountApp.signOut(new ISingleAccountPublicClientApplication.SignOutCallback()
  {
    @Override
    public void onSignOut()
    {
      updateSignedOutUI();
    }
    @Override
    public void onError(@NonNull MsalException exception)
    {
      /*failed to remove account with an exception*/
    }
  });
}

接收廣播以偵測從其他應用程式起始的全域登出

若要接收帳戶變更廣播，您必須註冊廣播接收器。 建議您透過內容註冊的接收器註冊廣播接收器。

收到帳戶變更廣播時，立即取得登入的使用者，並判斷使用者是否已在裝置上變更。 如果偵測到變更，即會為先前登入的帳戶起始資料清除。 建議您適當地停止所有作業並清除資料。

下列程式碼片段示範如何註冊廣播接收器。

private static final String CURRENT_ACCOUNT_CHANGED_BROADCAST_IDENTIFIER = "com.microsoft.identity.client.sharedmode.CURRENT_ACCOUNT_CHANGED";
private BroadcastReceiver mAccountChangedBroadcastReceiver;
private void registerAccountChangeBroadcastReceiver(){
    mAccountChangedBroadcastReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            //INVOKE YOUR PRIOR ACCOUNT CLEAN UP LOGIC HERE
        }
    };
    IntentFilter filter = new

    IntentFilter(CURRENT_ACCOUNT_CHANGED_BROADCAST_IDENTIFIER);
    this.registerReceiver(mAccountChangedBroadcastReceiver, filter);
}

註冊應用程式並設定您的租用戶以進行測試

在設定應用程式並將裝置置於共用裝置模式之前，您必須先在組織租用戶中註冊應用程式。 然後在 auth_config.json 中提供這些值，以便應用程式正確執行。

如需如何執行此動作的相關資訊，請參閱註冊應用程式。

注意

當您註冊應用程式時，請使用左側的快速入門指南，然後選取 [Android]。 這會引導您到一個頁面，然後要求您提供應用程式的套件名稱及簽章雜湊。 這些是確保您應用程式組態能夠正常執行的重要項目。 接著，您會收到用於應用程式的組態物件，可以將其剪下並貼到 auth_config.json 檔案中。

您應該選取 [為我進行這項變更]，然後提供快速入門要求的值。 完成後，Microsoft Entra ID 會產生您需要的所有設定檔。

基於測試目的，請在您的租用戶中設定下列角色：至少兩名員工與一個雲端裝置管理員。 設定雲端裝置管理員，需要修改組織角色。 從 Microsoft Entra 系統管理中心，選取 [身分識別] > [角色與系統管理員] > [角色和系統管理員] > [所有角色]，然後選取 [雲端裝置管理員]。 新增可讓裝置處於共用模式的使用者。

執行範例應用程式

範例應用程式是簡單的應用程式，可用來呼叫您組織的圖形 API。 第一次執行時，系統會顯示要求同意的提示，因為對您的員工帳戶而言，這是新的應用程式。

下一步

設定 Android 裝置以共用裝置模式執行應用程式，並測試您的應用程式。

適用於 Android 裝置的共用裝置模式