Tutorial: Usar o modo de dispositivo compartilhado em seu aplicativo Android
Neste tutorial, os desenvolvedores do Android e os administradores de locatários do Microsoft Entra aprenderão mais sobre o código, o aplicativo Authenticator e as configurações de locatário necessárias para habilitar o modo de dispositivo compartilhado em um aplicativo Android.
Neste tutorial:
- Baixe um exemplo de código
- Habilite e detecte o modo de dispositivo compartilhado
- Detecte o modo único ou o modo de várias contas
- Detecte uma opção do usuário e habilite a entrada e a saída globais
- Configure um locatário e registre o aplicativo
- Configure um dispositivo Android para o modo de dispositivo compartilhado
- Executar o aplicativo de exemplo
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Guia do desenvolvedor
Esta seção do tutorial fornece aos desenvolvedores diretrizes de como implementar o modo de dispositivo compartilhado em um aplicativo Android usando o MSAL (Biblioteca de Autenticação da Microsoft). 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.
Baixar o exemplo
Clone o aplicativo de exemplo do GitHub. O exemplo tem a capacidade de trabalhar em modo de conta única ou modo de 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.+'
}
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 conectar 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 de 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 único versus modo de 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 a seguir mostra como você pode registrar um receptor de difusã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);
}
Guia do administrador
As etapas a seguir descrevem a configuração do seu aplicativo e a colocação do dispositivo no modo de dispositivo compartilhado.
Registrar o aplicativo
Primeiro, registre seu aplicativo no seu locatário organizacional. Em seguida, forneça esses valores abaixo em auth_config.json para que seu aplicativo seja executado corretamente.
Para obter informações sobre como fazer isso, confira Registrar seu 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 seu aplicativo e que será recortado e colado em seu arquivo auth_config.json.
Você deve selecionar Faça essa alteração por mim e forneça os valores solicitados pelo início rápido. Feito isso, geraremos todos os arquivos de configuração necessários.
Configurar um locatário
Para fins de teste, configure o seguinte em seu locatário: pelo menos dois funcionários, um Administrador de dispositivo de nuvem e um Administrador global. Defina o Administrador de Dispositivo de Nuvem modificando as Funções Organizacionais. Acesse suas Funções Organizacionais selecionando Identidade>Funções e administradores>Funções e administradores>Todas as funções e selecione Administrador de Dispositivo de Nuvem. Adicione os usuários que poderão colocar um dispositivo no modo compartilhado.
Configurar um dispositivo Android para modo compartilhado
Baixar o Aplicativo Authenticator
Baixe o aplicativo Microsoft Authenticator na Google Play Store. Se o aplicativo já estiver baixado, verifique se é a versão mais recente.
Configurações do aplicativo Authenticator & registrar o dispositivo na nuvem
Inicie o aplicativo Authenticator e navegue até a página da conta principal. Depois de ver a página Adicionar Conta, você estará pronto para tornar o dispositivo compartilhado.
Vá para o painel de Configurações usando a barra de menus à direita. Selecione Registro de Dispositivo em Contas de Trabalho & Estudo.
Ao clicar nesse botão, será solicitado que você autorize o acesso aos contatos do dispositivo. Isso ocorre devido à integração de conta do Android no dispositivo. Escolha permitir.
O Administrador de Dispositivo de Nuvem deve inserir seu email organizacional em Ou registre-se como um dispositivo compartilhado. Em seguida, clique no botão registrar-se como dispositivo compartilhado e insira suas credenciais.
Agora o dispositivo está no modo compartilhado.
As entradas e saídas no dispositivo serão globais, o que significa que se aplicam a todos os aplicativos integrados ao MSAL e ao Microsoft Authenticator no dispositivo. Agora você pode implantar aplicativos que usam recursos de modo de dispositivo compartilhado.
Exibir o dispositivo compartilhado
Depois de colocar um dispositivo no modo compartilhado, ele se torna conhecido em sua organização e é acompanhado em seu locatário organizacional. Você pode visualizar seus dispositivos compartilhados observando o Tipo de Associação.
Executando 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
Saiba mais sobre como trabalhar com a Biblioteca de Autenticação da Microsoft e o modo de dispositivo compartilhado em dispositivos Android: