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'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.+'
}

Aggiunta del supporto per la modalità 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.

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 applicativo 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 seguente codice verifica la presenza di più modalità account o modalità di account singolo ed esegue il cast appropriato dell'oggetto applicativo:

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:

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. Potrebbe essere 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à di 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 dal personale sul campo 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 la trasmissione di modifiche dell'account, è necessario ottenere immediatamente l'utente connesso e stabilire se è cambiato un utente 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.

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.