Tutorial: Adicionar o suporte ao modo de dispositivo compartilhado em seu aplicativo Android
Neste tutorial, os desenvolvedores do Android aprendem a adicionar suporte ao modo de dispositivo compartilhado em um aplicativo Android usando a MSAL (Biblioteca de Autenticação da Microsoft) para Android.
Neste tutorial:
- Crie ou modifique um projeto de aplicativo Android existente.
- Habilite e detecte o modo dispositivo compartilhado
- Detecte o modo única conta ou várias contas
- Detectar uma opção de usuário
- Ativar entrada e saída global
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 saber como integrar o MSAL ao seu aplicativo Android, conectar um usuário, chamar o Microsoft Graph e sair de um usuário. Se você preferir usar um exemplo de código completo para aprender e testar, 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 seu 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 de 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 de conta única ou modo de várias contas.
Os recursos da plataforma de identidade da Microsoft disponíveis para seu aplicativo variam dependendo se o aplicativo está sendo executado no modo de conta única ou em modo de várias contas.
Os aplicativos de modo de dispositivo compartilhado funcionam apenas no modo de conta única.
Importante
Aplicativos que dão suporte apenas ao modo de várias contas não podem ser executados em um dispositivo compartilhado. Se um funcionário carregar um aplicativo que não dá suporte ao modo de conta única, ele não será executado no dispositivo compartilhado.
Os aplicativos gravados antes do lançamento do SDK da MSAL, são executados no modo de várias contas e devem ser atualizados para dar suporte ao modo de conta única antes que possam ser executados em um dispositivo de modo compartilhado. Suporte a conta única e a várias contas
Seu aplicativo pode ser criado para dar suporte à execução em dispositivos pessoais e compartilhados. Se seu aplicativo atualmente dá suporte a várias contas e você deseja dar suporte ao modo de dispositivo compartilhado, adicione suporte para o modo de conta única.
Você também pode querer que seu aplicativo altere o comportamento a depender do tipo de dispositivo onde ele está sendo executado. Use ISingleAccountPublicClientApplication.isSharedDevice() para determinar quando executar no modo de conta única.
Há duas interfaces diferentes que representam o tipo de dispositivo no qual seu aplicativo está. 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 seguintes diferenças se aplicam dependendo se seu aplicativo está em execução em um dispositivo compartilhado ou pessoal:
| Dispositivo no modo compartilhado | Dispositivo pessoal | |
|---|---|---|
| Contas | Conta única | Várias contas |
| Entrar | Global | Global |
| Sair | Global | Cada aplicativo pode controlar se a saída é local para o aplicativo ou para a família de aplicativos. |
| Tipos de conta compatíveis | Somente contas corporativas | Contas pessoais e corporativas compatíveis |
Configurar seu aplicativo para usar o modo de dispositivo compartilhado
Veja a documentação de configuração para obter mais informações sobre como configurar 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 de 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 seu aplicativo sempre obterá 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ê está usando o modo "single account".
Aqui está um exemplo do arquivo auth_config.json incluído no diretório aplicativo>principal>res>bruto 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 de dispositivo compartilhado
O modo de dispositivo compartilhado permite configurar dispositivos Android para serem compartilhados por vários funcionários enquanto fornece o gerenciamento de Microsoft Identity do dispositivo. Os funcionários podem entrar em seus dispositivos e acessar as informações do cliente rapidamente. Quando eles 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 o uso do próximo funcionário.
Use isSharedDevice() para determinar se um aplicativo está em execução em um dispositivo que esteja no modo dispositivo compartilhado. Seu aplicativo poderia usar esse sinalizador para determinar se ele deve modificar o UX adequadamente.
Aqui está um snippet de código que mostra como você poderia usar isSharedDevice(). Está na classe SingleAccountModeFragment no 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 dar suporte apenas ao modo de 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 dá suporte a várias contas e ao modo de dispositivo compartilhado, você deve executar uma verificação de tipo e converter 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;
...
}
Obter o usuário conectado e determinar 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 mudou 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 seguinte 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 está no modo de 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 uma difusão para detectar a saída global iniciada em outros aplicativos
Para receber uma difusão de alteração de conta, você precisa registrar um receptor de difusão. É recomendável registrar o receptor de difusão por meio dos Receptores registrados com contexto.
Quando uma difusão de alteração de conta for recebida, obtenha imediatamente o usuário conectado e determine se o usuário foi alterado no dispositivo. Se uma alteração for detectada, inicie a limpeza de dados da conta inserida 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 seu aplicativo e colocar seu dispositivo no modo de dispositivo compartilhado, você precisa registrar o aplicativo em seu locatário organizacional. Em seguida, forneça esses valores em auth_config.json para que seu aplicativo seja executado corretamente.
Para obter informações sobre como fazer isso, confira Registrar o aplicativo.
Observação
Ao registrar seu aplicativo, use o guia de início rápido no lado esquerdo e, em seguida, selecione Android. Isso levará a uma página em que você deverá fornecer o Nome do Pacote e o Hash de Assinatura para seu aplicativo. Isso é muito importante para garantir que a configuração do aplicativo funcione. Em seguida, você receberá um objeto de configuração que pode ser usado para o aplicativo e que será recortado e colado no arquivo auth_config.json.
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 suas 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, você será solicitado a consentir, pois o aplicativo é novo na sua conta de funcionário.
Próximas etapas
Configure um dispositivo Android para executar aplicativos no modo de dispositivo compartilhado e teste seu aplicativo.