Руководство. Использование режима общего устройства в приложении Android
В этом руководстве разработчики Android и администраторы клиента Microsoft Entra знают о коде, приложении Authenticator и параметрах клиента, необходимых для включения режима общего устройства для приложения Android.
В этом руководстве рассматриваются следующие темы:
- Скачивание примера кода
- Включение и обнаружение режима общего устройства
- Обнаружение режима использования одной и нескольких учетных записей
- Обнаружение смены пользователя и включение глобальных входа и выхода
- Настройка клиента и регистрация приложения
- Настройка устройства Android в режиме общего устройства
- Запуск примера приложения
Необходимые компоненты
- Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Руководство для разработчиков
В этом разделе руководства содержатся рекомендации для разработчиков по реализации режима общего устройства в приложении Android с помощью библиотеки проверки подлинности Майкрософт (MSAL). Сведения о том, как интегрировать MSAL с приложением Android, войти в систему, вызвать Microsoft Graph и выйти из учетной записи пользователя, см. в руководстве по MSAL Android.
Скачивание примера приложения
Клонируйте пример приложения из GitHub. Этот пример поддерживает работу в режиме одной или нескольких учетных записей.
Добавление пакета SDK для MSAL в локальный репозиторий Maven
Если вы не используете пример приложения, добавьте библиотеку MSAL в качестве зависимости в файл build.gradle, примерно так:
dependencies{
implementation 'com.microsoft.identity.client.msal:4.9.+'
}
Настройка приложения для использования режима общего устройства
Дополнительные сведения о настройках в файле конфигурации см. в документации по настройке.
В файле конфигурации 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.
Вы должны выбрать команду "Внести это изменение" для меня , а затем указать значения, которые запрашивает краткое руководство. По завершении мы создадим все необходимые файлы конфигурации.
Настройка клиента
Для тестирования настройте в клиенте по крайней мере два сотрудника, один администратор облачных устройств и один разработчик приложений. Задайте администратора облачных устройств, изменив роли организации. Для доступа к ролям организации выберите "Роли удостоверений>" и "Роли администраторов>>" и "Все роли" и выберите "Администратор облачных устройств". Добавьте пользователей, которые могут перевести устройство в режим общего доступа.
Настройка устройства Android в режиме общего доступа
Скачивание приложения Authenticator
Скачайте приложение Microsoft Authenticator из магазина Google Play. Если вы уже скачали приложение, убедитесь, что это последняя версия.
Параметры приложения Authenticator и регистрации устройства в облаке
Запустите приложение Authenticator и перейдите на главную страницу учетной записи. На странице Добавление учетной записи вы можете сразу перевести устройство в режим общего доступа.
Перейдите на панель Параметры, используя панель меню справа. Щелкните Регистрации устройства в разделе Work & School accounts (Рабочие и учебные учетные записи).
При нажатии этой кнопки вам будет предложено авторизовать доступ к контактам устройства. Это требования к интеграции учетных записей на устройстве Android. Выберите разрешить.
Администратору облачных устройств следует ввести адрес электронной почты своей организации в разделе Также возможна регистрация как общего устройства. После этого нажмите кнопку Зарегистрировать как общее устройство и введите учетные данные.
Теперь устройство находится в режиме общего доступа.
Все операции входа и выхода на этом устройстве будут глобальными. Это означает, что они будут применяться ко всем приложениям, интегрированным с MSAL и Microsoft Authenticator на этом устройстве. Теперь вы можете развертывать на устройстве приложения, которые используют возможности режима общего устройства.
Просмотр общего устройства
Когда вы переводите устройство в режим общего доступа, оно регистрируется для вашей организации и отслеживается в ее арендаторе. Вы можете просматривать общие устройства, просматривая тип соединения.
Выполнение примера приложения
Это простой пример приложения, которое обращается к API Graph вашей организации. При первом запуске вам будет предложено предоставить согласие, так как приложение является новым для вашей учетной записи сотрудника.
Следующие шаги
Узнайте больше о работе с библиотекой проверки подлинности Майкрософт и использовании режима общего устройства на устройствах Android: