Руководство. Добавление поддержки режима общего устройства в приложение Android

В этом руководстве разработчики Android узнали, как добавить поддержку режима общего устройства в приложении Android с помощью библиотеки проверки подлинности Майкрософт (MSAL) для Android.

В этом руководстве:

• Создайте или измените существующий проект приложения Android.
• Включение и обнаружение режима общего устройства
• Определение режима одной или нескольких учетных записей
• Обнаружение коммутатора пользователя
• Включение глобального входа и выхода

Создание или изменение существующего приложения Android

Чтобы завершить работу с остальным руководством, необходимо создать новое или изменить существующее приложение Android. Если вы еще не сделали этого, ознакомьтесь с руководством по MSAL Android по интеграции MSAL с приложением Android, войдите в систему пользователя, вызовите Microsoft Graph и выйдите из него. Если вы предпочитаете использовать полный пример кода для обучения и тестирования, клонируйте пример приложения из GitHub. В примере есть возможность работать в режиме одной или нескольких учетных записей.

Добавление пакета SDK MSAL в локальный репозиторий Maven

Если вы не используете пример приложения, добавьте библиотеку MSAL в качестве зависимости в файле build.gradle, например:

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

Добавление поддержки для режима одной учетной записи

Приложения, написанные с помощью пакета SDK библиотеки проверки подлинности Майкрософт (MSAL), могут управлять одной учетной записью или несколькими учетными записями. Дополнительные сведения см . в режиме с одной учетной записью или в режиме с несколькими учетными записями.

Функции платформа удостоверений Майкрософт, доступные приложению, зависят от того, работает ли приложение в режиме с одной учетной записью или в режиме нескольких учетных записей.

Приложения в режиме общего устройства работают только в режиме с одной учетной записью.

Важный

Приложения, поддерживающие только режим нескольких учетных записей, не могут выполняться на общем устройстве. Если сотрудник загружает приложение, которое не поддерживает режим одной учетной записи, оно не будет работать на общем устройстве.

Приложения, написанные до выпуска пакета SDK MSAL, запускаются в режиме с несколькими учетными записями и должны быть обновлены для поддержки режима одной учетной записи, прежде чем они смогут работать на устройстве общего режима. Поддержка одной учетной записи и нескольких учетных записей

Приложение можно создать для поддержки работы как на личных устройствах, так и на общих устройствах. Если приложение в настоящее время поддерживает несколько учетных записей и хотите поддерживать режим общего устройства, добавьте поддержку в режиме одной учетной записи.

Возможно, приложение также измените его поведение в зависимости от типа устройства, на котором он работает. Используется 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;
            ...
        }

Следующие различия применяются в зависимости от того, работает ли ваше приложение на общем или личном устройстве:

	Устройство общего режима	Личное устройство
Счета	Отдельная учетная запись	Несколько учетных записей
Вход	Глобальный	Глобальный
Выход	Глобальный	Каждое приложение может контролировать, является ли выход локальным для приложения.
Поддерживаемые типы учетных записей	Только рабочие учетные записи	Поддерживаемые личные и рабочие учетные записи

Настройка приложения для использования режима общего устройства

Дополнительные сведения о настройке файла конфигурации см. в документации по конфигурации.

Задайте значение "shared_device_mode_supported" true в файле конфигурации MSAL.

Возможно, вы не планируете поддерживать режим нескольких учетных записей. Это может быть, если вы не используете общее устройство, и пользователь может войти в приложение с несколькими учетными записями одновременно. Если да, задайте для этого значение "account_mode" "SINGLE". Это гарантирует, что приложение всегда будет получать ISingleAccountPublicClientApplicationи значительно упрощает интеграцию MSAL. Значением "account_mode" по умолчанию является "MULTIPLE", поэтому важно изменить это значение в файле конфигурации, если вы используете "single account" режим.

Ниже приведен пример файла auth_config.json, включенного в основной>каталог необработанных ресурсов приложения:>>

{
  "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 Identity. Сотрудники могут входить на свои устройства и быстро получать доступ к информации о клиентах. После завершения смены или задачи они смогут выйти из всех приложений на общем устройстве с одним щелчком мыши, и устройство будет немедленно готово для следующего сотрудника.

Используется isSharedDevice() для определения того, работает ли приложение на устройстве, которое находится в режиме общего устройства. Приложение может использовать этот флаг, чтобы определить, следует ли изменять UX соответствующим образом.

Ниже приведен фрагмент кода, в который показано, как можно использовать isSharedDevice(). Это из SingleAccountModeFragment класса в примере приложения:

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

Инициализация объекта PublicClientApplication

Если вы задаете "account_mode":"SINGLE" в файле конфигурации MSAL, можно безопасно привести возвращаемый объект приложения в качестве 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 создает все необходимые файлы конфигурации.

Для тестирования настройте следующие роли в клиенте как минимум два сотрудника и администратор облачных устройств. Чтобы задать администратора облачных устройств, необходимо изменить роли организации. В Центре администрирования Microsoft Entra перейдите к ролям организации, выбрав роли удостоверений>и администраторов>Всех ролей, а затем выберите "Администратор облачных>устройств". Добавьте пользователей, которые могут поместить устройство в общий режим.

Запуск примера приложения

Пример приложения — это простое приложение, которое вызовет API Graph вашей организации. При первом запуске вам будет предложено предоставить согласие, так как приложение является новым для вашей учетной записи сотрудника.

Дальнейшие действия

Настройте устройство Android для запуска приложений в режиме общего устройства и протестируйте приложение.

Режим общего устройства для устройств Android