Tutorial: Adicionar suporte ao modo de dispositivo compartilhado ao seu aplicativo Android
Neste tutorial, os desenvolvedores do Android aprendem como adicionar suporte ao modo de dispositivo compartilhado em um aplicativo Android usando a Biblioteca de Autenticação da Microsoft (MSAL) para Android.
Neste tutorial:
- Crie ou modifique um projeto de aplicativo Android existente.
- Ativar e detetar o modo de dispositivo partilhado
- Detetar o modo de conta única ou múltipla
- Detetar uma opção de usuário
- Habilitar entrada e saída globais
Criar ou modificar um aplicativo Android existente
Para concluir o restante do tutorial, você precisa criar um novo aplicativo Android ou modificar um existente. Se ainda não o fez, consulte o tutorial do MSAL Android para obter orientações sobre como integrar o MSAL com a sua aplicação Android, iniciar sessão num utilizador, ligar para o Microsoft Graph e terminar sessão num utilizador. Se preferir usar um exemplo de código concluído para aprendizado e teste, clone o aplicativo de exemplo do GitHub. O exemplo tem a capacidade de trabalhar no modo de conta única ou múltipla.
Adicione o SDK do MSAL ao repositório Maven local
Se você não estiver usando o aplicativo de exemplo, adicione a biblioteca MSAL como uma dependência em seu arquivo build.gradle, da seguinte 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 Biblioteca de Autenticação da Microsoft (MSAL) podem gerenciar uma única conta ou várias contas. Para obter detalhes, consulte Modo de conta única ou Modo de conta múltipla.
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 no modo de várias contas.
As aplicações de modo de dispositivo partilhado só funcionam no modo de conta única.
Importante
As aplicações que suportam apenas o modo de várias contas não podem ser executadas num dispositivo partilhado. Se um funcionário carregar um aplicativo que não suporta o modo de conta única, ele não será executado no dispositivo compartilhado.
Os aplicativos escritos antes do lançamento do SDK do MSAL são executados no modo de várias contas e devem ser atualizados para oferecer suporte ao modo de conta única antes de poderem ser executados em um dispositivo de modo compartilhado. Suporte a contas únicas e múltiplas
Seu aplicativo pode ser criado para suportar a execução em dispositivos pessoais e compartilhados. Se a sua aplicação suportar atualmente várias contas e pretender suportar o modo de dispositivo partilhado, adicione suporte para o modo de conta única.
Você também pode querer que seu aplicativo altere seu comportamento dependendo do tipo de dispositivo em que 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 em que seu aplicativo está. Quando você solicita uma instância de aplicativo da fábrica de aplicativos 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 ele significa no contexto de um dispositivo compartilhado:
Você precisa fazer uma verificação de tipo e transmitir para a interface apropriada quando você recebe seu PublicClientApplication objeto. O código a seguir verifica vários modos de conta ou modos de conta única e transmite o objeto de aplicativo apropriadamente:
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á sendo executado em um dispositivo compartilhado ou pessoal:
| Dispositivo de modo compartilhado | Dispositivo pessoal | |
|---|---|---|
| Contas | Conta única | Várias contas |
| Iniciar sessão | Global | Global |
| Sair | Global | Cada aplicativo pode controlar se a saída é local para o aplicativo. |
| Tipos de conta suportados | Apenas contas de trabalho | Contas pessoais e profissionais suportadas |
Configurar seu aplicativo para usar o modo de dispositivo compartilhado
Consulte a documentação de configuração para obter mais informações sobre como configurar seu arquivo de configuração.
Defina "shared_device_mode_supported" como no true arquivo de configuração do MSAL.
Você pode não estar planejando oferecer suporte ao modo de várias contas. Isso pode 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. Em caso afirmativo, defina "account_mode" como "SINGLE". Isso garante que seu aplicativo sempre terá ISingleAccountPublicClientApplication, e simplifica significativamente sua integração MSAL. O valor padrão de é "MULTIPLE", portanto, é importante alterar esse valor no arquivo de "account_mode" configuração se você estiver usando "single account" o modo.
Aqui está um exemplo do arquivo auth_config.json incluído no diretório raw res principal>>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"
}
}
]
}
Detetar o modo de dispositivo compartilhado
O modo de dispositivo compartilhado permite configurar dispositivos Android para serem compartilhados por vários funcionários, ao mesmo tempo em que fornece gerenciamento do dispositivo com suporte de identidade da Microsoft. Os funcionários podem fazer login em seus dispositivos e acessar as informações do cliente rapidamente. Quando terminarem o turno ou tarefa, eles poderão sair de todos os aplicativos no dispositivo compartilhado com um único clique e o dispositivo estará imediatamente pronto para o próximo funcionário usar.
Use isSharedDevice() para determinar se um aplicativo está sendo executado em um dispositivo que está no modo de dispositivo compartilhado. Seu aplicativo pode usar esse sinalizador para determinar se deve modificar a experiência do usuário de acordo.
Aqui está um trecho de código que mostra como você pode usar isSharedDevice()o . É da SingleAccountModeFragment classe 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, poderá converter com segurança o objeto de aplicativo retornado como um ISingleAccountPublicCLientApplicationarquivo .
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 */
}
});
Detetar o modo de conta única versus múltipla
Se você estiver escrevendo um aplicativo que será usado apenas para trabalhadores da linha de frente em um dispositivo compartilhado, recomendamos que você escreva seu aplicativo para oferecer suporte apenas ao modo de conta única. Isso inclui a maioria dos aplicativos focados em tarefas, como aplicativos de registros médicos, aplicativos de fatura e a maioria dos aplicativos de linha de negócios. Isso simplificará seu desenvolvimento, pois muitos recursos do SDK não precisarão ser acomodados.
Se o seu aplicativo suportar várias contas e o modo de dispositivo compartilhado, você deverá executar uma verificação de tipo e transmitir 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 loadAccount método recupera a conta do usuário conectado. O onAccountChanged método determina se o usuário conectado foi alterado e, em caso afirmativo, limpe:
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)
{
}
}
}
Iniciar sessão globalmente num utilizador
O seguinte inicia sessão num utilizador através do dispositivo para outras aplicações que utilizam o MSAL com a Aplicação Autenticadora:
private void onSignInClicked()
{
mSingleAccountApp.signIn(getActivity(), SCOPES, null, getAuthInteractiveCallback());
}
Sair globalmente de um usuário
O seguinte remove a conta conectada e limpa os tokens armazenados 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 transmissão para detetar saída global iniciada de outros aplicativos
Para receber a transmissão de mudança de conta, você precisa registrar um recetor de transmissão. Recomenda-se registar o seu recetor de transmissão através dos recetores registados no contexto.
Quando uma transmissão de alteração de conta é recebida, obtenha imediatamente o usuário conectado e determine se um usuário foi alterado no dispositivo. Se uma alteração for detetada, inicie a limpeza de dados para a conta conectada anteriormente. Recomenda-se parar corretamente todas as operações e fazer a limpeza de dados.
O trecho de código a seguir mostra como você pode registrar um recetor 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, consulte Registrar seu aplicativo.
Nota
Quando registar a sua aplicação, utilize o guia de início rápido no lado esquerdo e, em seguida, selecione Android. Isso levará você a uma página onde você será solicitado a fornecer o Nome do Pacote e o Hash de Assinatura para seu aplicativo. Eles são muito importantes para garantir que a configuração do seu aplicativo funcione. Em seguida, você receberá um objeto de configuração que poderá usar para seu aplicativo que será cortado e colado em seu arquivo de auth_config.json.
Você deve selecionar Fazer essa alteração para mim e, em seguida, fornecer os valores que o início rápido pede. Quando terminar, o Microsoft Entra ID gera todos os arquivos de configuração necessários.
Para fins de teste, configure as seguintes funções em seu locatário - pelo menos dois funcionários e um Administrador de Dispositivo na Nuvem. Para definir o Cloud Device Administrator, você precisa modificar as Funções Organizacionais. No centro de administração do Microsoft Entra, aceda às suas Funções Organizacionais selecionando Identity>Roles & admins>Roles & admins>All roles e, em seguida, selecione Cloud Device Administrator. Adicione os usuários que podem colocar um dispositivo no modo compartilhado.
Executando o aplicativo de exemplo
O Aplicativo de Exemplo é um aplicativo simples que chamará a API do Graph da sua organização. Na primeira execução, você será solicitado a consentir, pois o aplicativo é novo na sua conta de funcionário.
Próximos passos
Configure um dispositivo Android para executar aplicações no modo de dispositivo partilhado e teste a sua aplicação.