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 aprendem sobre o código, o aplicativo Authenticator e as configurações de locatário necessárias para habilitar o modo de dispositivo compartilhado para um aplicativo Android.
Neste tutorial:
- Baixar um exemplo de código
- Ativar e detetar o modo de dispositivo partilhado
- Detetar o modo de conta única ou múltipla
- Detetar um comutador de utilizador e ativar o início de sessão e a saída globais
- Configurar locatário e registrar o aplicativo
- Configurar um dispositivo Android no modo de dispositivo partilhado
- Execute a aplicação de exemplo
Pré-requisitos
- Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
Guia do programador
Esta seção do tutorial fornece orientação do desenvolvedor para implementar o modo de dispositivo compartilhado em um aplicativo Android usando a Biblioteca de Autenticação da Microsoft (MSAL). Consulte o tutorial do MSAL Android para ver como integrar o MSAL com seu aplicativo Android, entrar em um usuário, chamar o Microsoft graph e sair de um usuário.
Transferir o exemplo
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.+'
}
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);
}
Guia do administrador
As etapas a seguir descrevem como configurar seu aplicativo e colocar seu dispositivo no modo de dispositivo compartilhado.
Registar a candidatura
Primeiro, registre o aplicativo em 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, 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 no arquivo 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. Feito isso, geraremos todos os arquivos de configuração necessários.
Configurar um inquilino
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 Dispositivos na Nuvem modificando as Funções Organizacionais. 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.
Configurar um dispositivo Android no modo partilhado
Baixe o aplicativo autenticador
Transfira a aplicação Microsoft Authenticator a partir da Google Play Store. Se já tiver a aplicação transferida, certifique-se de que é a versão mais recente.
Configurações do aplicativo autenticador & registrando o dispositivo na nuvem
Inicie o aplicativo autenticador e navegue até a página principal da conta. Assim que vir a página Adicionar Conta , está pronto para partilhar o dispositivo.
Vá para o painel Configurações usando a barra de menu à direita. Selecione Registro de dispositivo em Contas de trabalho e escola.
Quando clicar neste botão, ser-lhe-á pedido para autorizar o acesso aos contactos do dispositivo. Isso se deve à integração da conta do Android no dispositivo. Escolha permitir.
O Administrador de Dispositivos na Nuvem deve introduzir o seu e-mail organizacional em Ou registar-se como um dispositivo partilhado. Em seguida, clique no botão registrar como dispositivo compartilhado e insira suas credenciais.
O dispositivo está agora em modo partilhado.
Todas 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 no dispositivo que usam recursos de modo de dispositivo compartilhado.
Ver o dispositivo partilhado
Depois de colocar um dispositivo no modo compartilhado, ele se torna conhecido pela sua organização e é rastreado em seu locatário organizacional. Pode ver os seus dispositivos partilhados consultando o Tipo de Adesão.
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
Saiba mais sobre como trabalhar com a Biblioteca de Autenticação da Microsoft e o modo de dispositivo compartilhado em dispositivos Android: