Esercitazione: Aggiungere il supporto della modalità dispositivo condiviso in un'applicazione Android
In questa esercitazione gli sviluppatori Android apprendono come aggiungere il supporto della modalità dispositivo condiviso in un'applicazione Android usando Microsoft Authentication Library (MSAL) per Android.
Contenuto dell'esercitazione:
- Creare o modificare un progetto di applicazione Android esistente.
- Abilitare e rilevare la modalità dispositivo condiviso
- Rilevare la modalità per account singolo o per più account
- Rilevare un cambio di utente
- Abilitare l'accesso e la disconnessione globali
Creare o modificare un'applicazione Android esistente
Per completare il resto dell'esercitazione, è necessario creare una nuova applicazione Android o modificarne una esistente. Se non lo si è già fatto, vedere l'esercitazione su MSAL per Android per informazioni su come integrare MSAL con l'app Android, connettere un utente, chiamare Microsoft Graph e disconnettere un utente. Se si preferisce usare un esempio di codice completo per l'apprendimento e il test, clonare l'esempio di applicazione da GitHub. L'esempio consente di lavorare in modalità per account singolo o per account multipli.
Aggiungere MSAL SDK al repository Maven locale
Se non si usa l'app di esempio, aggiungere la libreria MSAL come dipendenza nel file build.gradle, come segue:
dependencies{
implementation 'com.microsoft.identity.client.msal:4.9.+'
}
Aggiungere il supporto per la modalità con account singolo
Le applicazioni scritte con SDK Microsoft Authentication Library (MSAL) possono gestire un singolo account o più account. Per informazioni dettagliate, vedere modalità con account singolo o modalità con più account.
Le funzionalità di Microsoft Identity Platform disponibili per l'app variano a seconda che l'applicazione sia in esecuzione in modalità con account singolo o con più account.
Le app in modalità dispositivo condiviso funzionano solo in modalità con account singolo.
Importante
Le applicazioni che supportano solo la modalità con più account non possono essere eseguite in un dispositivo condiviso. Se un dipendente carica un'app che non supporta la modalità con account singolo, non verrà eseguita nel dispositivo condiviso.
Le app scritte prima del rilascio di MSAL SDK sono state eseguite in modalità con più account e devono essere aggiornate per supportare la modalità con account singolo prima di poter essere eseguite in un dispositivo in modalità condivisa. Supporto sia di account singolo che di più account
L'app può essere compilata per supportare l'esecuzione su dispositivi personali e dispositivi condivisi. Se l'app supporta attualmente più account e si vuole supportare la modalità dispositivo condiviso, aggiungere il supporto per la modalità account singolo.
È anche possibile che l'app modifichi il comportamento a seconda del tipo di dispositivo in cui è in esecuzione. Usare ISingleAccountPublicClientApplication.isSharedDevice() per determinare quando eseguire in modalità account singolo.
Esistono due interfacce diverse che rappresentano il tipo di dispositivo in cui è presente l'applicazione. Quando si richiede un'istanza dell'applicazione dalla factory dell'applicazione MSAL, l'oggetto applicazione corretto viene fornito automaticamente.
Il modello a oggetti seguente illustra il tipo di oggetto che è possibile ricevere e il relativo significato nel contesto di un dispositivo condiviso:
È necessario eseguire un controllo del tipo ed eseguire il cast all'interfaccia appropriata quando si ottiene l'oggetto PublicClientApplication. Il codice seguente verifica la presenza di modalità più account o account singolo ed esegue il cast appropriato dell'oggetto applicazione:
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;
...
}
Le differenze seguenti si applicano a seconda che l'app sia in esecuzione in un dispositivo condiviso o personale:
| Dispositivo in modalità condivisa | Dispositivo personale | |
|---|---|---|
| Account | Account singolo | Più account |
| Accesso | Globale | Globale |
| Disconnessione | Globale | Ogni applicazione può controllare se la disconnessione è locale per l'app. |
| Tipi di account supportati | Solo account di lavoro | Account personali e aziendali supportati |
Configurare l'app per l'uso della modalità dispositivo condiviso
Per altre informazioni sull'impostazione del file di configurazione, vedere la documentazione sulla configurazione.
Impostare "shared_device_mode_supported" su true nel file di configurazione MSAL.
Se non si prevede di supportare la modalità per account multipli, come nel caso in cui non si usa un dispositivo condiviso e l'utente può accedere all'app con più account nello stesso momento, impostare "account_mode" su "SINGLE". Ciò garantisce che l'app ottenga sempre ISingleAccountPublicClientApplication, semplificando notevolmente l'integrazione di MSAL. Il valore predefinito di "account_mode" è "MULTIPLE", quindi è importante modificare questo valore nel file di configurazione, se si usa la modalità "single account".
Ecco un esempio del file auth_config.json incluso nella directory app>main>res>raw dell'app di esempio:
{
"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"
}
}
]
}
Rilevare la modalità dispositivo condiviso
La modalità dispositivo condiviso consente di configurare i dispositivi Android in modo che vengano condivisi da più dipendenti, fornendo al contempo la gestione del dispositivo supportata da Microsoft Identity. I dipendenti possono accedere ai propri dispositivi e visualizzare rapidamente le informazioni dei clienti. Al termine del turno o dell’attività, sarà possibile disconnettersi da tutte le app nel dispositivo condiviso con un solo clic e il dispositivo sarà immediatamente pronto all’uso dal dipendente successivo.
Usare isSharedDevice() per determinare se un'app è in esecuzione in un dispositivo che è in modalità dispositivo condiviso. L'app può usare questo flag per determinare se l'esperienza utente deve essere modificata di conseguenza.
Ecco un frammento di codice che mostra come è possibile usare isSharedDevice(). È tratto dalla classe SingleAccountModeFragment nell'app di esempio:
deviceModeTextView.setText(mSingleAccountApp.isSharedDevice() ? "Shared" : "Non-Shared");
Inizializzare l'oggetto PublicClientApplication
Se si imposta "account_mode":"SINGLE" nel file di configurazione MSAL, è possibile eseguire il cast sicuro dell'oggetto applicazione restituito come 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 */
}
});
Rilevare la modalità per account singolo o per account multipli
Se si vuole scrivere un'app che verrà usata solo dai dipendenti in prima linea su un dispositivo condiviso, si consiglia di scrivere l’app in modo che supporti solo la modalità account singolo. Questo vale per la maggior parte delle applicazioni incentrate su attività, come le app medicali, le app di fatturazione e quasi tutte le app line-of-business. In questo modo si semplifica lo sviluppo, in quanto molte funzionalità dell'SDK non saranno necessarie.
Se l'app supporta più account e la modalità dispositivo condiviso, è necessario eseguire un controllo del tipo ed eseguire il cast all'interfaccia appropriata, come mostrato di seguito.
private IPublicClientApplication mApplication;
if (mApplication instanceOf IMultipleAccountPublicClientApplication) {
IMultipleAccountPublicClientApplication multipleAccountApplication = (IMultipleAccountPublicClientApplication) mApplication;
...
} else if (mApplication instanceOf ISingleAccountPublicClientApplication) {
ISingleAccountPublicClientApplication singleAccountApplication = (ISingleAccountPublicClientApplication) mApplication;
...
}
Ottenere l'utente connesso e determinare se un utente è cambiato nel dispositivo
Il metodo loadAccount recupera l'account dell'utente che ha eseguito l'accesso. Il metodo onAccountChanged determina se l'utente connesso è cambiato e, in tal caso, esegue la pulizia:
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)
{
}
}
}
Connettere un utente a livello globale
Il codice seguente connette un utente attraverso il dispositivo ad altre app che usano MSAL con l'app Authenticator:
private void onSignInClicked()
{
mSingleAccountApp.signIn(getActivity(), SCOPES, null, getAuthInteractiveCallback());
}
Disconnettere un utente a livello globale
Il codice seguente rimuove l'account connesso e cancella i token memorizzati nella cache non solo dall'app, ma anche dal dispositivo in modalità dispositivo condiviso:
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*/
}
});
}
Ricevere la trasmissione per rilevare la disconnessione globale avviata da altre applicazioni
Per ricevere la trasmissione delle modifiche dell'account è necessario registrare un ricevitore di trasmissione. Si consiglia di registrare il ricevitore di trasmissione tramite i Ricevitori registrati dal contesto.
Quando viene ricevuta una trasmissione di modifiche dell'account, ottenere immediatamente l'utente connesso e determinare se un utente è cambiato nel dispositivo. Se viene rilevata una modifica, avviare la pulizia dei dati per l'account connesso in precedenza. È consigliabile arrestare correttamente le operazioni ed eseguire la pulizia dei dati.
Il frammento di codice seguente mostra come registrare un ricevitore di trasmissione.
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);
}
Registrare l'applicazione e configurare il tenant per il test
Prima di poter configurare l'applicazione e inserire il dispositivo in modalità dispositivo condiviso, è necessario registrare l'applicazione all'interno del tenant dell'organizzazione. Quindi fornire i valori indicati di seguito nel file auth_config.json per consentire la corretta esecuzione dell'applicazione.
Per informazioni sula procedura, vedere Registrare l'applicazione.
Nota
Per registrare l'app, usare la guida di avvio rapido sul lato sinistro e quindi selezionare Android. Si aprirà una pagina in cui si dovranno compilare i campi Nome pacchetto e Hash della firma per l'app. Questi valori sono molto importanti per assicurare la corretta configurazione dell'app. Si riceverà quindi un oggetto di configurazione per l'app da tagliare e incollare nel file auth_config.json.
Selezionare Apporta queste modifiche per me e quindi specificare i valori richiesti dall'avvio rapido. Al termine, Microsoft Entra ID genera tutti i file di configurazione necessari.
A scopo di test, configurare nel tenant i seguenti ruoli - almeno due dipendenti, un amministratore dispositivo cloud. Per impostare l'amministratore dispositivo cloud, è necessario modificare i ruoli dell'organizzazione. Dall'interfaccia di amministrazione di Microsoft Entra passare ai ruoli dell'organizzazione selezionando Identità> Ruoli amministratori e amministratori>Ruoli amministratori>Tutti i ruoli e quindi selezionare Amministratore dispositivo cloud. Aggiungere gli utenti autorizzati a impostare un dispositivo in modalità condivisa.
Esecuzione dell'app di esempio
L'applicazione di esempio è un'app semplice che chiama l'API Graph dell'organizzazione. Alla prima esecuzione verrà richiesto di fornire il consenso perché l'account del dipendente è una novità per l'applicazione.
Passaggi successivi
Configurare un dispositivo Android per eseguire app in modalità dispositivo condiviso e testare l'app.