Tutorial: Adicionar o suporte ao modo dispositivo compartilhado no aplicativo Android

Neste tutorial, os desenvolvedores do Android aprendem a adicionar suporte ao modo dispositivo compartilhado em um aplicativo Android usando a MSAL (Biblioteca de Autenticação da Microsoft) para Android.

Neste tutorial:

Criar ou modificar um aplicativo Android existente

Para concluir o restante do tutorial, você precisa criar um novo aplicativo Android ou modificar um existente. Confira o tutorial do MSAL para Android para obter orientações sobre como integrar o MSAL a um aplicativo Android, conectar um usuário, chamar o Microsoft Graph e desconectar um usuário. Se você preferir usar um exemplo de código completo para aprendizagem e teste, clone o aplicativo de exemplo do GitHub. O exemplo tem a capacidade de trabalhar em modo conta única ou contas múltiplas.

Adicionar o SDK do MSAL ao repositório Maven local

Se você não estiver usando o aplicativo de exemplo, adicione a biblioteca do MSAL como uma dependência no arquivo build.gradle, desta forma:

dependencies{
  implementation 'com.microsoft.identity.client.msal:4.9.+'
}

Adicionar suporte para o modo conta única

Os aplicativos escritos usando o SDK da MSAL (Biblioteca de Autenticação da Microsoft) podem gerenciar uma única conta ou várias contas. Para obter detalhes, consulte modo conta única ou modo várias contas.

Os recursos da plataforma de identidade da Microsoft disponíveis para o aplicativo variam dependendo se o aplicativo está sendo executado no modo conta única ou várias contas.

Os aplicativos do modo dispositivo compartilhado funcionam apenas no modo conta única.

O aplicativo pode ser criado para dar suporte à execução em dispositivos pessoais e compartilhados. Se o aplicativo atualmente oferece suporte a várias contas e você quiser oferecer suporte ao modo dispositivo compartilhado, adicione suporte para o modo conta única.

Você também pode querer que o aplicativo altere o comportamento, conforme o tipo de dispositivo onde ele estiver sendo executado. Use ISingleAccountPublicClientApplication.isSharedDevice() para determinar quando executar no modo conta única.

Duas interfaces diferentes representam o tipo de dispositivo no qual seu aplicativo estiver. Quando você solicita uma instância de aplicativo do Application Factory da MSAL, o objeto de aplicativo correto é fornecido automaticamente.

O modelo de objeto a seguir ilustra o tipo de objeto que você pode receber e o que significa no contexto de um dispositivo compartilhado:

Você precisa fazer uma verificação de tipo e uma conversão para a interface apropriada ao obter o objeto PublicClientApplication. O código a seguir verifica os modos de várias contas ou de conta única e faz a conversão apropriada do objeto de aplicativo:

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;
            ...
        }

As diferenças a seguir se aplicam dependendo se o aplicativo está em execução em um dispositivo compartilhado ou pessoal:

Configure seu aplicativo para usar o modo dispositivo compartilhado

Consulte a documentação de configuração para obter mais informações sobre como definir o arquivo de configuração.

Defina "shared_device_mode_supported" como true no arquivo de configuração do MSAL.

Talvez você não esteja planejando dar suporte ao modo várias contas. Isso poderá ocorrer se você não estiver usando um dispositivo compartilhado e o usuário puder entrar no aplicativo com mais de uma conta ao mesmo tempo. Nesse caso, defina "account_mode" como "SINGLE". Isso garante que o aplicativo sempre obtenha ISingleAccountPublicClientApplication e simplifica significativamente a integração do MSAL. O valor padrão de "account_mode" é "MULTIPLE", portanto é importante alterar esse valor no arquivo de configuração se você estiver usando o modo "single account".

Aqui está um exemplo do arquivo auth_config.json incluído no diretório app>main>res>raw do aplicativo de exemplo:

{
  "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"
      }
    }
  ]
}

Detectar modo dispositivo compartilhado

O modo dispositivo compartilhado permite configurar dispositivos Android para serem compartilhados por vários funcionários enquanto fornece o gerenciamento com suporte do Microsoft Identity do dispositivo. Os funcionários podem entrar em seus dispositivos e acessar as informações do cliente rapidamente. Quando concluírem seus turnos ou tarefas, eles poderão sair de todos os aplicativos no dispositivo compartilhado com um clique, e o dispositivo estará imediatamente pronto para uso pelo próximo funcionário.

Use isSharedDevice() para determinar se um aplicativo está em execução em um dispositivo que esteja no modo dispositivo compartilhado. O aplicativo pode usar esse sinalizador para determinar se ele deve modificar a UX adequadamente.

Aqui está um snippet de código que mostra como você poderia usar o isSharedDevice(). Ele é originado na classe SingleAccountModeFragment do aplicativo de exemplo:

deviceModeTextView.setText(mSingleAccountApp.isSharedDevice() ? "Shared" : "Non-Shared");

Inicializar o objeto PublicClientApplication

Se você definir "account_mode":"SINGLE" no arquivo de configuração do MSAL, você poderá converter com segurança o objeto de aplicativo retornado como um 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 */
  }
});

Detectar modo conta única versus várias contas

Se você estiver escrevendo um aplicativo que será usado apenas por trabalhadores na linha de frente em um dispositivo compartilhado, recomendamos que você codifique o aplicativo para ser compatível somente com o modo conta única. Isso inclui a maioria dos aplicativos focados em tarefas, como os aplicativos de registros médicos, aplicativos de fatura e a maioria dos aplicativos de linha de negócios. Isso simplificará o desenvolvimento, pois muitos recursos do SDK não precisarão ser acomodados.

Se o aplicativo é compatível com várias contas e com o modo dispositivo compartilhado, execute uma verificação de tipo e converta para a interface apropriada, conforme mostrado abaixo.

private IPublicClientApplication mApplication;

        if (mApplication instanceOf IMultipleAccountPublicClientApplication) {
          IMultipleAccountPublicClientApplication multipleAccountApplication = (IMultipleAccountPublicClientApplication) mApplication;
          ...
        } else if (mApplication instanceOf    ISingleAccountPublicClientApplication) {
           ISingleAccountPublicClientApplication singleAccountApplication = (ISingleAccountPublicClientApplication) mApplication;
            ...
        }

Conheça o usuário conectado e determine se um usuário foi alterado no dispositivo

O método loadAccount recupera a conta do usuário conectado. O método onAccountChanged determina se o usuário conectado foi alterado e, nesse caso, limpa:

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)
    {
    }
  }
}

Conectar um usuário globalmente

O procedimento a seguir conecta um usuário em todo o dispositivo para outros aplicativos que usam o MSAL com o Aplicativo Authenticator:

private void onSignInClicked()
{
  mSingleAccountApp.signIn(getActivity(), SCOPES, null, getAuthInteractiveCallback());
}

Desconectar um usuário globalmente

O seguinte remove a conta conectada e limpa os tokens em cache não apenas do aplicativo, mas também do dispositivo que estiver no modo dispositivo compartilhado:

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*/
    }
  });
}

Receber transmissão para detectar a saída global iniciada em outros aplicativos

Para receber a transmissão de alteração de conta, você precisa registrar um receptor de transmissão. É recomendável registrar o receptor de transmissão por meio dos Receptores registrados com contexto.

Quando uma transmissão de alteração de conta for recebida, obtenha imediatamente o usuário conectado e determine se esse usuário foi alterado no dispositivo. Se uma alteração for detectada, inicie a limpeza de dados da conta conectada anteriormente. É recomendável interromper corretamente todas as operações e fazer a limpeza dos dados.

O snippet de código abaixo mostra como você pode registrar um receptor de transmissão.

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);
}

Registre o aplicativo e configure seu locatário para teste

Antes de configurar o aplicativo e colocar o dispositivo no modo dispositivo compartilhado, será necessário registrar o aplicativo no locatário organizacional. Em seguida, forneça esses valores em auth_config.json para que o aplicativo seja executado corretamente.

Para obter informações sobre como fazer isso, confira Registrar o aplicativo.

Você deve selecionar Faça essa alteração por mim e fornecer os valores solicitados pelo início rápido. Quando terminar, o Microsoft Entra ID gera todos os arquivos de configuração necessários.

Para fins de teste, configure as funções a seguir em seu locatário – pelo menos dois funcionários e um Administrador de dispositivo de nuvem. Para configurar o Administrador de dispositivo de nuvem, modifique as Funções Organizacionais. No centro de administração do Microsoft Entra, vá para as Funções Organizacionais selecionando Identidade>Funções e administradores>Funções e administradores>Todas as funções e, em seguida, selecione Administrador de dispositivo de nuvem. Adicione os usuários que poderão colocar um dispositivo no modo compartilhado.

Executar o aplicativo de exemplo

O Aplicativo de Exemplo é um aplicativo simples que chamará a API do Graph de sua organização. Na primeira execução, será necessário consentir, pois o aplicativo é novo na sua conta de funcionário.

Próximas etapas

Configure um dispositivo Android para executar aplicativos no modo dispositivo compartilhado e teste o aplicativo.