Tutorial: Incorporación de la compatibilidad con el modo de dispositivo compartido en la aplicación Android
En este tutorial, los desarrolladores de Android descubrirán cómo agregar la compatibilidad con el modo de dispositivo compartido en una aplicación Android mediante la biblioteca de autenticación de Microsoft (MSAL) para Android.
En este tutorial:
- Creará o modificará un proyecto de aplicación Android existente.
- Habilitará y detectará el modo de dispositivo compartido
- Detectará el modo de varias cuentas o de una sola
- Detectará un cambio de usuario
- Habilitará el inicio y cierre de sesión global
Creación o modificación de una aplicación de Android existente
Para completar el resto del tutorial, debe modificar una aplicación Android existente o crear una. Si todavía no lo ha hecho, vea el tutorial de MSAL de Android para obtener orientación sobre cómo integrar MSAL con la aplicación Android, iniciar sesión con un usuario, llamar a Microsoft Graph y cerrar la sesión de un usuario. Si prefiere utilizar un ejemplo de código completo para aprender y realizar pruebas, clone la aplicación de ejemplo de GitHub. El ejemplo puede funcionar en modo de una o de varias cuentas.
Incorporación del SDK de MSAL al repositorio local de Maven
Si no está usando la aplicación de ejemplo, agregue la biblioteca MSAL como una dependencia en el archivo build.gradle, como se muestra a continuación:
dependencies{
implementation 'com.microsoft.identity.client.msal:4.9.+'
}
Incorporación de compatibilidad con el modo de cuenta única
Las aplicaciones escritas mediante el SDK de la biblioteca de autenticación de Microsoft (MSAL) pueden administrar una sola cuenta o varias cuentas. Para obtener más información, vea el modo de una sola cuenta o el modo de varias cuentas.
Las características de la Plataforma de identidad de Microsoft disponibles para la aplicación varían en función de si la aplicación se ejecuta en modo de una sola cuenta o en modo de varias cuentas.
Las aplicaciones en modo de dispositivo compartido solo funcionan en el modo de una sola cuenta.
Importante
Las aplicaciones que solo admiten el modo de varias cuentas no se pueden ejecutar en un dispositivo compartido. Si un empleado carga una aplicación que no admite el modo de una sola cuenta, no se ejecutará en el dispositivo compartido.
Las aplicaciones escritas antes de que se publicara el SDK de MSAL se ejecutan en modo de varias cuentas y deben actualizarse para admitir el modo de una sola cuenta antes de poder ejecutarse en un dispositivo de modo compartido. Compatibilidad con una sola cuenta y con varias cuentas
La aplicación se puede crear para admitir la ejecución tanto en dispositivos personales como en dispositivos compartidos. Si la aplicación admite actualmente varias cuentas y quiere admitir el modo de dispositivo compartido, agregue compatibilidad para el modo de una sola cuenta.
Es posible que también quiera que la aplicación cambie su comportamiento en función del tipo de dispositivo en el que se ejecuta. Use ISingleAccountPublicClientApplication.isSharedDevice() para determinar cuándo se debe ejecutar en el modo de una sola cuenta.
Hay dos interfaces diferentes que representan el tipo de dispositivo en el que se encuentra la aplicación. Cuando se solicita una instancia de aplicación de la factoría de aplicaciones de MSAL, se proporciona el objeto de aplicación correcto automáticamente.
En el modelo de objetos siguiente se muestra el tipo de objeto que puede recibir y lo que significa en el contexto de un dispositivo compartido:
Tiene que realizar una comprobación de tipos y la conversión a la interfaz adecuada cuando obtenga el objeto PublicClientApplication. El siguiente código comprueba los modos de varias cuentas o de una sola cuenta, y convierte el objeto de aplicación de forma adecuada:
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;
...
}
Las siguientes diferencias se aplican en función de si la aplicación se ejecuta en un dispositivo compartido o personal:
| Dispositivo en modo compartido | Dispositivo personal | |
|---|---|---|
| Cuentas | Una sola cuenta | Varias cuentas |
| Inicio de sesión | Global | Global |
| Cierre de sesión | Global | Cada aplicación puede controlar si el cierre de sesión es local para la aplicación. |
| Tipos de cuenta admitidos | Solo cuentas profesionales | Se admiten cuentas personales y profesionales |
Configuración de la aplicación para que use el modo de dispositivo compartido
Vea la documentación de configuración para obtener más información sobre cómo configurar el archivo de configuración.
Establezca "shared_device_mode_supported" como true en el archivo de configuración de MSAL.
Es posible que no tenga previsto admitir el modo de varias cuentas. Este podría ser el caso si no va a usar un dispositivo compartido y el usuario puede iniciar sesión en la aplicación con más de una cuenta al mismo tiempo. Si es así, establezca "account_mode" en "SINGLE". De esta forma, se garantiza que la aplicación siempre obtendrá ISingleAccountPublicClientApplication y simplifica considerablemente la integración de MSAL. El valor predeterminado de "account_mode" es "MULTIPLE", por lo que es importante cambiar este valor en el archivo de configuración si utiliza el modo "single account".
Este es un ejemplo del archivo auth_config.json incluido en el directorio app>main>res>raw de la aplicación de ejemplo:
{
"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"
}
}
]
}
Detección del modo de dispositivo compartido
El modo de dispositivo compartido le permite configurar dispositivos Android para que los compartan varios empleados, a la vez que ofrece la administración respaldada del dispositivo por parte de Microsoft Identity. Los empleados pueden iniciar sesión en sus dispositivos y acceder a la información sobre los clientes rápidamente. Cuando terminan su turno o su tarea, podrán cerrar la sesión de todas las aplicaciones en el dispositivo compartido con un solo clic y el dispositivo estará inmediatamente listo para que lo use el siguiente empleado.
Use isSharedDevice() para determinar si una aplicación se está ejecutando en un dispositivo que está en modo de dispositivo compartido. La aplicación podría usar esta marca para determinar si debe modificar la experiencia de usuario según corresponda.
Este es un fragmento de código que muestra cómo puede usar isSharedDevice(). Procede de la clase SingleAccountModeFragment de la aplicación de ejemplo:
deviceModeTextView.setText(mSingleAccountApp.isSharedDevice() ? "Shared" : "Non-Shared");
Inicialización del objeto PublicClientApplication
Si establece "account_mode":"SINGLE" en el archivo de configuración de MSAL, puede convertir de forma segura el objeto de aplicación devuelto como un 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 */
}
});
Detección del modo de varias cuentas o de una sola
Si va a escribir una aplicación que solo utilizarán los trabajadores de primera línea en un dispositivo compartido, se recomienda escribirla para que admita únicamente el modo de una sola cuenta. Esto incluye a la mayoría de las aplicaciones que se centran en tareas, como las de registros médicos, facturas y la mayor parte de las de línea de negocio. De este modo, se simplificará el desarrollo, ya que no es necesario acomodar muchas características del SDK.
Si la aplicación admite varias cuentas y el modo de dispositivo compartido, debe realizar una comprobación de tipo y convertirla en la interfaz adecuada, como se muestra a continuación.
private IPublicClientApplication mApplication;
if (mApplication instanceOf IMultipleAccountPublicClientApplication) {
IMultipleAccountPublicClientApplication multipleAccountApplication = (IMultipleAccountPublicClientApplication) mApplication;
...
} else if (mApplication instanceOf ISingleAccountPublicClientApplication) {
ISingleAccountPublicClientApplication singleAccountApplication = (ISingleAccountPublicClientApplication) mApplication;
...
}
Obtención del usuario que ha iniciado sesión y comprobación de si un usuario ha cambiado en el dispositivo
El método loadAccount recupera la cuenta del usuario que ha iniciado sesión. El método onAccountChanged determina si el usuario con la sesión iniciada ha cambiado y, en tal caso, se limpia:
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)
{
}
}
}
Inicio de sesión de un usuario de forma global
El siguiente código permite al usuario del dispositivo iniciar sesión en otras aplicaciones que usan MSAL con la aplicación Authenticator:
private void onSignInClicked()
{
mSingleAccountApp.signIn(getActivity(), SCOPES, null, getAuthInteractiveCallback());
}
Cierre de sesión de un usuario de forma global
El siguiente código elimina la cuenta con la sesión iniciada y borra los tokens almacenados en caché no solo de la aplicación, sino también del dispositivo que está en modo de dispositivo compartido:
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*/
}
});
}
Recepción de difusión para detectar el cierre de sesión global iniciado desde otras aplicaciones
Para recibir la difusión de cambio de cuenta, debe registrar un receptor de difusión. Se recomienda registrar el receptor de difusión mediante los receptores registrados en contexto.
Cuando se recibe una difusión de cambio de cuenta, obtiene inmediatamente el usuario que ha iniciado sesión y determina si un usuario ha cambiado en el dispositivo. Si se detecta un cambio, inicie la limpieza de datos para la cuenta que ha iniciado sesión anteriormente. Se recomienda detener correctamente las operaciones y realizar la limpieza de datos.
En el siguiente fragmento de código se muestra cómo se puede registrar un receptor de difusión.
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);
}
Registro de la aplicación y configuración del inquilino para pruebas
Antes de poder configurar la aplicación y colocar el dispositivo en modo de dispositivo compartido, debe registrar la aplicación en el inquilino de la organización. Luego, proporcione estos valores en auth_config.json para que la aplicación se ejecute correctamente.
Para obtener más información sobre cómo hacerlo, vea Registro de la aplicación.
Nota:
Al registrar la aplicación, use la guía de inicio rápido que se encuentra a la izquierda y, después, seleccione Android. De esta forma, llegará a una página en la que se le pedirá que proporcione el valor de Nombre del paquete y Hash de firma de la aplicación. Son muy importantes para garantizar que la configuración de la aplicación funcione. Después recibirá un objeto de configuración que puede usar para la aplicación que va a cortar y pegar en el archivo auth_config.json.
Debe seleccionar Hacer este cambio por mí y, después, proporcionar los valores que le solicite el inicio rápido. Cuando haya terminado, Microsoft Entra ID genera todos los archivos de configuración que necesita.
Para las pruebas, configure lo siguiente en el inquilino los siguientes roles: al menos dos empleados y un Administrador de dispositivos en la nube. Para establecer el Administrador de dispositivos en la nube, necesita modificar los roles de la organización. En el Centro de administración Microsoft Entra, vaya a los roles de la organización seleccionando Identidad>Roles y administradores>Roles y administradores>Todos los roles y, después, seleccione Administrador de dispositivos en la nube. Agregue los usuarios que puedan poner un dispositivo en modo compartido.
Ejecución de la aplicación de ejemplo
La aplicación de ejemplo es una aplicación sencilla que llamará a la instancia de Graph API de la organización. En la primera ejecución, se le pedirá el consentimiento ya que la aplicación es nueva en la cuenta de empleado.
Pasos siguientes
Configure un dispositivo Android para ejecutar aplicaciones en modo de dispositivo compartido y probar la aplicación.