Руководство. Добавление поддержки режима общего устройства в приложение 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;
...
}
В зависимости от того, работает ли приложение на общем или личном устройстве, применяются следующие отличия:
| Устройство с режимом совместной работы | Личное устройство | |
|---|---|---|
| Измерение счетов | Одна учетная запись | Несколько учетных записей |
| Вход | Глобальный | Глобальный |
| Выход | Глобальный | Каждое приложение может контролировать, является ли выход локальным для приложения. |
| Поддерживаемые типы учетных записей | Только рабочие учетные записи | Поддерживаются личные и рабочие учетные записи |
Настройка приложения для использования режима общего устройства
Дополнительные сведения о настройках в файле конфигурации см. в документации по настройке.
В файле конфигурации 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 Identity. Сотрудники могут входить на устройства и быстро получать доступ к сведениям о клиентах. После завершения смены или задачи они смогут выйти из всех приложений на общем устройстве с одним щелчком мыши, и устройство будет немедленно готово для следующего сотрудника.
С помощью isSharedDevice() определите, выполняется ли приложение на устройстве в режиме общего доступа. По значению этого флага приложение может изменять пользовательский интерфейс соответствующим образом.
Ниже приведен фрагмент кода с примером использования 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 создает все необходимые файлы конфигурации.
Для тестирования настройте следующие роли в клиенте как минимум два сотрудника и администратор облачных устройств. Чтобы задать администратора облачных устройств, необходимо изменить роли организации. В Центре администрирования Microsoft Entra перейдите к ролям организации, выбрав роли удостоверений>и администраторов>Всех ролей, а затем выберите "Администратор облачных>устройств". Добавьте пользователей, которые могут перевести устройство в режим общего доступа.
Выполнение примера приложения
Это простой пример приложения, которое обращается к API Graph вашей организации. При первом запуске вам будет предложено предоставить согласие, так как приложение является новым для вашей учетной записи сотрудника.
Следующие шаги
Настройте устройство Android для запуска приложений в режиме общего устройства и протестируйте приложение.