Início Rápido: logar usuários e chamar o Microsoft Graph em um aplicativo Android - Microsoft identity platform

Artigo
06/18/2024

Neste guia de início rápido, você baixará e executará um exemplo de código que demonstra como um aplicativo Android pode conectar usuários e obter um token de acesso para chamar a API do Microsoft Graph.

Os aplicativos precisam ser representados por um objeto de aplicativo na ID do Microsoft Entra, de modo que a plataforma de identidade da Microsoft possa fornecer tokens ao aplicativo.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Android Studio
Android 16 ou superior

Como o exemplo funciona

Diagrama mostrando como o aplicativo de exemplo gerado por este início rápido funciona.

O código é organizado em fragmentos que mostram como escrever um aplicativo MSAL de contas únicas e múltiplas. Os arquivos de código são organizados da seguinte maneira:

Arquivo	Demonstra
MainActivity	Gerencia a interface do usuário
MSGraphRequestWrapper	Chama a API do Microsoft Graph usando o token fornecido pela MSAL
MultipleAccountModeFragment	Inicializa um aplicativo de conta múltipla, carrega uma conta de usuário e obtém um token para chamar a API do Microsoft Graph
SingleAccountModeFragment	Inicializa um aplicativo de conta única, carrega uma conta de usuário e obtém um token para chamar a API do Microsoft Graph
res/auth_config_multiple_account.json	O arquivo de configuração de conta múltipla
res/auth_config_single_account.json	O arquivo de configuração de conta única
Gradle Scripts/build.grade (Module:app)	As dependências da biblioteca MSAL são adicionadas aqui

Agora examinaremos esses arquivos mais detalhadamente e chamaremos o código específico da MSAL em cada um.

Obter o aplicativo de exemplo

Java: Baixar o código.
Kotlin: Baixar o código.

Registrar o aplicativo de exemplo

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

Faça login no Centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de aplicativos.
Se você tiver acesso a vários locatários, use o ícone de Configurações no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.
Navegue até Identidade>Aplicativos>Registros do aplicativo.
Selecione Novo registro.
Insira um Nome para seu aplicativo. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.
Em Tipos de conta com suporte, selecione Contas em qualquer diretório da organização (qualquer diretório do Microsoft Entra — com vários locatários) e contas Microsoft pessoais (por exemplo, Skype, Xbox). Para obter informações sobre diferentes tipos de conta, selecione a opção Ajudar-me a escolher.
Selecione Registrar.
Em Gerenciar, selecione Autenticação>Adicionar uma plataforma>Android.
Digite o Nome do Pacote do seu projeto com base no tipo de amostra que você baixou acima.
- Exemplo de Java - com.azuresamples.msalandroidapp
- Exemplo de Kotlin - com.azuresamples.msalandroidkotlinapp
Em Hash de assinatura, que é uma seção do painel Configure seu aplicativo Android, selecione Gerar um Hash de Assinatura de desenvolvimento e copie o comando KeyTool na sua linha de comando.
- KeyTool.exe é instalado como parte do JDK (Java Development Kit). Você também precisará instalar a ferramenta OpenSSL para executar o comando KeyTool. Para mais informações, veja a documentação do Android sobre como gerar uma chave para obter mais informações.
Insira o Hash de assinatura gerado por KeyTool.
Selecione Configurar e salve a Configuração da MSAL exibida no painel Configuração do Android, de modo que você possa inseri-la quando configurar o aplicativo mais tarde.
Selecione Concluído.

Configurar o aplicativo de exemplo

No painel do projeto do Android Studio, navegue até app\src\main\res.
Clique com o botão direito do mouse em res e escolha Novo>Diretório. Insira raw como o nome do novo diretório e selecione OK.
Em aplicativo>src>principal>res>bruto, acesse o arquivo JSON chamado auth_config_single_account.json e cole a Configuração MSAL que você salvou anteriormente.

Abaixo do URI de Redirecionamento, cole:
```
  "account_mode" : "SINGLE",
```
Seu arquivo de configuração deve ser semelhante a este exemplo:
```
{
  "client_id": "00001111-aaaa-bbbb-3333-cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "redirect_uri": "msauth://com.azuresamples.msalandroidapp/00001111%cccc4444%3D",
  "broker_redirect_uri_registered": true,
  "account_mode": "SINGLE",
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}
```
Como este tutorial demonstra apenas como configurar um aplicativo no modo Conta Única, confira o modo de conta única versus múltipla e como configurar seu aplicativo para obter mais informações

Executar o aplicativo de exemplo

Selecione seu emulador ou dispositivo físico da lista suspensa de dispositivos disponíveis do Android Studio e execute o aplicativo.

O aplicativo de exemplo é iniciado na tela Modo de Conta Único. Um escopo padrão, user.read, é fornecido por padrão, usado ao ler seus próprios dados de perfil durante a chamada à API do Microsoft Graph. A URL da chamada à API do Microsoft Graph é fornecida por padrão. Se desejar, você poderá alterar as duas.

Captura de tela do Aplicativo de exemplo MSAL mostrando o uso de conta única e múltipla.

Use o menu do aplicativo para alterar entre modos de conta única e múltipla.

No modo de conta única, entre usando uma conta corporativa ou doméstica:

Selecione Obter dados de grafo interativamente para solicitar que o usuário insira suas credenciais. Você verá a saída da chamada à API do Microsoft Graph na parte inferior da tela.
Após entrar, selecione Obter dados de grafo silenciosamente para fazer uma chamada à API do Microsoft Graph sem solicitar as credenciais do usuário novamente. Você verá a saída da chamada à API do Microsoft Graph na parte inferior da tela.

No modo de conta múltipla, você pode repetir as mesmas etapas. Além disso, você pode remover a conta conectada, que também remove os tokens armazenados em cache dessa conta.

Mais informações

Leia estas seções para saber mais sobre este guia de início rápido.

Adicionar MSAL ao aplicativo

MSAL (com.microsoft.identity.client) é a biblioteca usada para conectar usuários e solicitar tokens usados para acessar uma API protegida pela plataforma de identidade da Microsoft. O Gradle 3.0+ instala a biblioteca quando você adiciona o seguinte aos Scripts do Gradle>build.gradle (Módulo: aplicativo) em Dependências:

dependencies {
    ...
    implementation 'com.microsoft.identity.client:msal:5.1.0'
    implementation 'com.android.volley:volley:1.2.1'
    ...
}

Isso instrui o Gradle a baixar e compilar o MSAL da central do maven.

Você também deve adicionar referências ao maven à parte allprojects>repositories do settings.gradle (Module: app) em dependencyResolutionManagement:

dependencyResolutionManagement {
...
maven 
{
 url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
}
... 
}

Importações da MSAL

As importações relevantes para a biblioteca MSAL são com.microsoft.identity.client.*. Por exemplo, você verá import com.microsoft.identity.client.PublicClientApplication; que é o namespace da classe PublicClientApplication, que representa seu aplicativo cliente público.

SingleAccountModeFragment.java

Este arquivo demonstra como criar um aplicativo MSAL de conta única e chamar uma API do Microsoft Graph.

Os aplicativos de conta única são usados por um usuário único. Por exemplo, talvez você só tenha uma conta com a qual você entra em seu aplicativo de mapeamento.

Inicialização da MSAL de conta única

No SingleAccountModeFragment.java, no método onCreateView(), uma conta única PublicClientApplication é criada usando as informações de configuração armazenadas no arquivo auth_config_single_account.json. É assim como você inicializa a biblioteca MSAL para que ela seja usada em um aplicativo MSAL de conta única:

...
// Creates a PublicClientApplication object with res/raw/auth_config_single_account.json
PublicClientApplication.createSingleAccountPublicClientApplication(getContext(),
        R.raw.auth_config_single_account,
        new IPublicClientApplication.ISingleAccountApplicationCreatedListener() {
            @Override
            public void onCreated(ISingleAccountPublicClientApplication application) {
                /**
                 * This test app assumes that the app is only going to support one account.
                 * This requires "account_mode" : "SINGLE" in the config json file.
                 **/
                mSingleAccountApp = application;
                loadAccount();
            }

            @Override
            public void onError(MsalException exception) {
                displayError(exception);
            }
        });

No SingleAccountModeFragment.java, o código para conectar um usuário está no initializeUI(), no manipulador de cliques signInButton.

Chame signIn() antes de tentar adquirir tokens. signIn() se comporta como se acquireToken() foi chamado, resultando em um prompt interativo para o usuário entrar.

Conectar um usuário é uma operação assíncrona. Um retorno de chamada é passado que chama a API do Microsoft Graph e atualiza a interface do usuário depois que o usuário se conecta:

mSingleAccountApp.signIn(getActivity(), null, getScopes(), getAuthInteractiveCallback());

Desconectar um usuário

No SingleAccountModeFragment.java, o código para desconectar um usuário está no initializeUI(), no manipulador de cliques signOutButton. Desconectar um usuário é uma operação assíncrona. Desconectar o usuário também apaga o cache de token dessa conta. Um retorno de chamada será criado para atualizar a interface do usuário depois que a conta de usuário for desconectada:

mSingleAccountApp.signOut(new ISingleAccountPublicClientApplication.SignOutCallback() {
    @Override
    public void onSignOut() {
        updateUI(null);
        performOperationOnSignOut();
    }

    @Override
    public void onError(@NonNull MsalException exception) {
        displayError(exception);
    }
});

Obter um token de maneira interativa ou silenciosa

Para representar o menor número de solicitações para o usuário, normalmente você obterá um token silenciosamente. Em seguida, se houver um erro, tente obter o token interativamente. Na primeira vez em que o aplicativo chama signIn(), ele funciona efetivamente como uma chamada a acquireToken(), que solicitará as credenciais do usuário.

Algumas situações em que o usuário pode ser solicitado a selecionar sua conta, inserir credenciais ou dar consentimento às permissões que seu aplicativo solicitou são:

A primeira vez que o usuário entra no aplicativo
Se um usuário redefinir a senha, ele precisará inserir as credenciais
Se o consentimento for revogado
Se o aplicativo exigir consentimento explicitamente
Quando seu aplicativo estiver solicitando acesso a um recurso pela primeira vez
Quando a MFA ou outras políticas de Acesso Condicional forem necessárias

O código para obter um token interativamente, que está com a interface do usuário que envolverá o usuário, está em SingleAccountModeFragment.java, no initializeUI(), no manipulador de cliques callGraphApiInteractiveButton:

/**
 * If acquireTokenSilent() returns an error that requires an interaction (MsalUiRequiredException),
 * invoke acquireToken() to have the user resolve the interrupt interactively.
 *
 * Some example scenarios are
 *  - password change
 *  - the resource you're acquiring a token for has a stricter set of requirement than your Single Sign-On refresh token.
 *  - you're introducing a new scope which the user has never consented for.
 **/
mSingleAccountApp.acquireToken(getActivity(), getScopes(), getAuthInteractiveCallback());

Se o usuário já tiver entrado, acquireTokenSilentAsync() permitirá que aplicativos solicitem tokens silenciosamente, conforme mostrado em initializeUI(), no manipulador de cliques callGraphApiSilentButton:

/**
 * Once you've signed the user in,
 * you can perform acquireTokenSilent to obtain resources without interrupting the user.
 **/
  mSingleAccountApp.acquireTokenSilentAsync(getScopes(), AUTHORITY, getAuthSilentCallback());

Carregar uma conta

O código para carregar uma conta está em SingleAccountModeFragment.java em loadAccount(). Carregar a conta do usuário é uma operação assíncrona. Portanto, retornos de chamada para manipular quando a conta é carregada ou alterada ou quando um erro ocorre são passados para a MSAL. O código a seguir também manipula onAccountChanged(), que ocorre quando uma conta é removida, o usuário é muda para outra conta e assim por diante.

private void loadAccount() {
    ...

    mSingleAccountApp.getCurrentAccountAsync(new ISingleAccountPublicClientApplication.CurrentAccountCallback() {
        @Override
        public void onAccountLoaded(@Nullable IAccount activeAccount) {
            // You can use the account data to update your UI or your app database.
            updateUI(activeAccount);
        }

        @Override
        public void onAccountChanged(@Nullable IAccount priorAccount, @Nullable IAccount currentAccount) {
            if (currentAccount == null) {
                // Perform a cleanup task as the signed-in account changed.
                performOperationOnSignOut();
            }
        }

        @Override
        public void onError(@NonNull MsalException exception) {
            displayError(exception);
        }
    });

Chamar o Microsoft Graph

Quando um usuário é conectado, a chamada ao Microsoft Graph é feita por meio de uma solicitação HTTP pelo callGraphAPI(), que é definido em SingleAccountModeFragment.java. Essa função é um wrapper que simplifica o exemplo realizando algumas tarefas como obter o token de acesso do authenticationResult e empacotar a chamada para o MSGraphRequestWrapper e exibir os resultados da chamada.

private void callGraphAPI(final IAuthenticationResult authenticationResult) {
    MSGraphRequestWrapper.callGraphAPIUsingVolley(
            getContext(),
            graphResourceTextView.getText().toString(),
            authenticationResult.getAccessToken(),
            new Response.Listener<JSONObject>() {
                @Override
                public void onResponse(JSONObject response) {
                    /* Successfully called graph, process data and send to UI */
                    ...
                }
            },
            new Response.ErrorListener() {
                @Override
                public void onErrorResponse(VolleyError error) {
                    ...
                }
            });
}

auth_config_single_account.json

Este é o arquivo de configuração de um aplicativo MSAL que usa uma conta única.

Confira Noções básicas sobre o arquivo de configuração da MSAL do Android para obter uma explicação desses campos.

Observe a presença de "account_mode" : "SINGLE", que configura esse aplicativo para usar uma conta única.

O "client_id" é pré-configurado para usar um registro de objeto de aplicativo que a Microsoft mantém. O "redirect_uri" é pré-configurado para usar a chave de assinatura fornecida com a amostra de código.

{
  "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "redirect_uri": "msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "account_mode": "SINGLE",
  "broker_redirect_uri_registered": true,
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

MultipleAccountModeFragment.java

Este arquivo demonstra como criar um aplicativo MSAL de conta múltipla e chamar uma API do Microsoft Graph.

Um exemplo de um aplicativo de conta múltipla é um aplicativo pequeno que permite que você trabalhe com várias contas de usuário, como uma conta corporativa e uma conta pessoal.

Inicialização da MSAL de conta múltipla

No arquivo MultipleAccountModeFragment.java, no onCreateView(), um objeto de aplicativo de conta múltipla (IMultipleAccountPublicClientApplication) é criado usando as informações de configuração armazenadas no auth_config_multiple_account.json file:

// Creates a PublicClientApplication object with res/raw/auth_config_multiple_account.json
PublicClientApplication.createMultipleAccountPublicClientApplication(getContext(),
        R.raw.auth_config_multiple_account,
        new IPublicClientApplication.IMultipleAccountApplicationCreatedListener() {
            @Override
            public void onCreated(IMultipleAccountPublicClientApplication application) {
                mMultipleAccountApp = application;
                loadAccounts();
            }

            @Override
            public void onError(MsalException exception) {
                ...
            }
        });

O objeto MultipleAccountPublicClientApplication criado é armazenado em uma variável de membro de classe para que possa ser usado para interagir com a biblioteca MSAL para adquirir tokens e carregar e remover a conta de usuário.

Carregar uma conta

Aplicativos de conta múltipla geralmente chamam getAccounts() para selecionar a conta a ser usada para operações de MSAL. O código para carregar uma conta está no arquivo MultipleAccountModeFragment.java em loadAccounts(). Carregar a conta de usuário é uma operação assíncrona. Portanto, um retorno de chamada lida com as situações em que a conta é carregada ou alterada ou quando ocorre um erro.

/**
 * Load currently signed-in accounts, if there's any.
 **/
private void loadAccounts() {
    if (mMultipleAccountApp == null) {
        return;
    }

    mMultipleAccountApp.getAccounts(new IPublicClientApplication.LoadAccountsCallback() {
        @Override
        public void onTaskCompleted(final List<IAccount> result) {
            // You can use the account data to update your UI or your app database.
            accountList = result;
            updateUI(accountList);
        }

        @Override
        public void onError(MsalException exception) {
            displayError(exception);
        }
    });
}

Obter um token de maneira interativa ou silenciosa

Algumas situações em que o usuário pode ser solicitado a selecionar sua conta, inserir credenciais ou dar consentimento às permissões que seu aplicativo solicitou são:

A primeira vez que os usuários entram no aplicativo
Se um usuário redefinir a senha, ele precisará inserir as credenciais
Se o consentimento for revogado
Se o aplicativo exigir consentimento explicitamente
Quando seu aplicativo estiver solicitando acesso a um recurso pela primeira vez
Quando a MFA ou outras políticas de Acesso Condicional forem necessárias

Os aplicativos de conta múltipla normalmente devem adquirir tokens interativamente, ou seja, com uma interface do usuário que envolva o usuário, com uma chamada para acquireToken(). O código para obter um token interativamente está no arquivo MultipleAccountModeFragment.java no initializeUI(), no manipulador de cliques callGraphApiInteractiveButton:

/**
 * Acquire token interactively. It will also create an account object for the silent call as a result (to be obtained by getAccount()).
 *
 * If acquireTokenSilent() returns an error that requires an interaction,
 * invoke acquireToken() to have the user resolve the interrupt interactively.
 *
 * Some example scenarios are
 *  - password change
 *  - the resource you're acquiring a token for has a stricter set of requirement than your SSO refresh token.
 *  - you're introducing a new scope which the user has never consented for.
 **/
mMultipleAccountApp.acquireToken(getActivity(), getScopes(), getAuthInteractiveCallback());

Os aplicativos não devem exigir que o usuário entre sempre que solicitar um token. Se o usuário já tiver entrado, acquireTokenSilentAsync() permitirá que aplicativos solicitem tokens sem solicitar o usuário, conforme mostrado no arquivo MultipleAccountModeFragment.java, no initializeUI() no manipulador de cliques callGraphApiSilentButton:

/**
 * Performs acquireToken without interrupting the user.
 *
 * This requires an account object of the account you're obtaining a token for.
 * (can be obtained via getAccount()).
 */
mMultipleAccountApp.acquireTokenSilentAsync(getScopes(),
    accountList.get(accountListSpinner.getSelectedItemPosition()),
    AUTHORITY,
    getAuthSilentCallback());

Remover uma conta

O código para remover uma conta e todos os tokens em cache da conta está no arquivo MultipleAccountModeFragment.java no initializeUI() no manipulador para o botão Remover conta. Antes de remover uma conta, você precisa de um objeto de conta, que você obtém de métodos MSAL como getAccounts() e acquireToken(). Como a remoção de uma conta é uma operação assíncrona, o retorno de chamada onRemoved é fornecido para atualizar a interface do usuário.

/**
 * Removes the selected account and cached tokens from this app (or device, if the device is in shared mode).
 **/
mMultipleAccountApp.removeAccount(accountList.get(accountListSpinner.getSelectedItemPosition()),
        new IMultipleAccountPublicClientApplication.RemoveAccountCallback() {
            @Override
            public void onRemoved() {
                ...
                /* Reload account asynchronously to get the up-to-date list. */
                loadAccounts();
            }

            @Override
            public void onError(@NonNull MsalException exception) {
                displayError(exception);
            }
        });

auth_config_multiple_account.json

Este é o arquivo de configuração para um aplicativo MSAL que usa várias contas.

Confira Noções básicas sobre o arquivo de configuração da MSAL do Android para obter uma explicação dos vários campos.

Diferentemente do arquivo de configuração auth_config_single_account.json, esse arquivo de configuração tem "account_mode" : "MULTIPLE", em vez de "account_mode" : "SINGLE", porque este é um aplicativo de conta múltipla.

{
  "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "redirect_uri": "msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "account_mode": "MULTIPLE",
  "broker_redirect_uri_registered": true,
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

Ajuda e suporte

Se precisar de ajuda, quiser relatar um problema ou desejar saber mais sobre as opções de suporte, confira Ajuda e suporte para desenvolvedores.

Próximas etapas

Prossiga para o tutorial do Android, em que você criará um aplicativo Android que obtém um token de acesso da plataforma de identidade da Microsoft e o utilizará para chamar a API do Microsoft Graph.

Tutorial: Conectar usuários e chamar o Microsoft Graph em um aplicativo Android

Compartilhar via

Pré-requisitos

Como o exemplo funciona

Obter o aplicativo de exemplo

Registrar o aplicativo de exemplo

Configurar o aplicativo de exemplo

Executar o aplicativo de exemplo

Mais informações

Adicionar MSAL ao aplicativo

Importações da MSAL

SingleAccountModeFragment.java

Inicialização da MSAL de conta única

Desconectar um usuário

Obter um token de maneira interativa ou silenciosa

Carregar uma conta

Chamar o Microsoft Graph

auth_config_single_account.json

MultipleAccountModeFragment.java

Inicialização da MSAL de conta múltipla

Carregar uma conta

Obter um token de maneira interativa ou silenciosa

Remover uma conta

auth_config_multiple_account.json

Ajuda e suporte

Próximas etapas

Comentários

Recursos adicionais