Partilhar via

Guia de início rápido: entre usuários e chame o Microsoft Graph a partir de um aplicativo Android

  • Artigo

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

Os aplicativos devem ser representados por um objeto de aplicativo no Microsoft Entra ID para que a plataforma de identidade da Microsoft possa fornecer tokens para seu aplicativo.

Pré-requisitos

Como funciona a amostra

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

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 forma:

Ficheiro Demonstra
Atividade Principal Gerencia a interface do usuário
MSGraphRequestWrapper Chama a API do Microsoft Graph usando o token fornecido pela MSAL
MultipleAccountModeFragment Inicializa um aplicativo de várias contas, 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 várias contas
res/auth_config_single_account.json O arquivo de configuração de conta única
Gradle Scripts/build.grade (Módulo:aplicativo) As dependências da biblioteca MSAL são adicionadas aqui

Agora vamos examinar esses arquivos com mais detalhes e chamar o código específico do MSAL em cada um.

Obter a aplicação de exemplo

Registrar o aplicativo de exemplo

Gorjeta

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

  1. Entre no centro de administração do Microsoft Entra como pelo menos um desenvolvedor de aplicativos.

  2. Se você tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.

  3. Navegue até Registros do aplicativo Identity>Applications>.

  4. Selecione Novo registo.

  5. Introduza um Nome para a sua aplicação. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.

  6. Para Tipos de conta suportados, selecione Contas em qualquer diretório organizacional (Qualquer diretório Microsoft Entra - Multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox). Para obter informações sobre diferentes tipos de conta, selecione a opção Ajude-me a escolher .

  7. Selecione Registar.

  8. Em Gerir, selecione Autenticação>Adicionar uma plataforma>Android.

  9. Insira o nome do pacote do seu projeto com base no tipo de exemplo que você baixou acima.

    • Exemplo Java - com.azuresamples.msalandroidapp
    • Amostra de Kotlin - com.azuresamples.msalandroidkotlinapp

  10. Na seção Hash de assinatura do painel Configurar seu aplicativo Android, selecione Gerando um hash de assinatura de desenvolvimento e copie o comando KeyTool para sua linha de comando.

    • KeyTool.exe é instalado como parte do Java Development Kit (JDK). Você também deve instalar a ferramenta OpenSSL para executar o comando KeyTool. Para obter mais informações, consulte a documentação do Android sobre como gerar uma chave para obter mais informações.

  11. Introduza o Hash de assinatura gerado pelo KeyTool.

  12. Selecione Configurar e salvar a Configuração do MSAL que aparece no painel de configuração do Android para que você possa inseri-la quando configurar seu aplicativo mais tarde.

  13. Selecionar Concluído.

Configurar a aplicação de exemplo

  1. No painel de projetos do Android Studio, navegue até app\src\main\res.

  2. Clique com o botão direito do mouse em res e escolha Novo>diretório. Digite raw como o novo nome do diretório e selecione OK.

  3. No app>src>main>res>raw, vá para 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 de Conta Única, consulte Modo de conta única versus múltipla e Configuração do aplicativo para obter mais informações

Execute a aplicação de exemplo

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

O aplicativo de exemplo começa na tela Modo de Conta Única. Um escopo padrão, user.read, é fornecido por padrão, que é usado ao ler seus próprios dados de perfil durante a chamada da API do Microsoft Graph. A URL para a chamada da API do Microsoft Graph é fornecida por padrão. Você pode alterar ambos se desejar.

Captura de ecrã da aplicação de exemplo MSAL a mostrar a utilização de uma ou várias contas.

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

No modo de conta única, inicie sessão com uma conta profissional ou doméstica:

  1. Selecione Obter dados do gráfico interativamente para solicitar ao usuário suas credenciais. Você verá a saída da chamada para a API do Microsoft Graph na parte inferior da tela.
  2. Depois de entrar, selecione Obter dados do gráfico silenciosamente para fazer uma chamada para a API do Microsoft Graph sem solicitar credenciais ao usuário novamente. Você verá a saída da chamada para a 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 para essa conta.

Mais Informações

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

Adicionando MSAL ao aplicativo

MSAL (com.microsoft.identity.client) é a biblioteca usada para entrar 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 ao Gradle Scripts>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 construir o MSAL a partir do maven central.

Você também deve adicionar referências a maven à parte de repositórios de todos os projetos>do settings.gradle (Módulo: aplicativo) em dependencyResolutionManagement:

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

Importações 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; qual é o namespace para a PublicClientApplication classe, 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 apenas por um único usuário. Por exemplo, você pode ter apenas uma conta com a qual você entra em seu aplicativo de mapeamento.

Inicialização MSAL de conta única

No SingleAccountModeFragment.javamétodo , in onCreateView() , uma única conta PublicClientApplication é criada usando as informações de configuração armazenadas no auth_config_single_account.json arquivo. É assim que você inicializa a biblioteca MSAL para uso 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);
            }
        });

Iniciar sessão num utilizador

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

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

Entrar em um usuário é uma operação assíncrona. É passado um retorno de chamada que chama a API do Microsoft Graph e atualiza a interface do usuário assim que o usuário entra:

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

Sair de um usuário

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

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

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

Obtenha um token de forma interativa ou silenciosa

Para apresentar o menor número de prompts ao usuário, você normalmente receberá um token silenciosamente. Em seguida, se houver um erro, tente obter um token interativamente. Na primeira vez que o aplicativo chama signIn(), ele efetivamente age como uma chamada para acquireToken(), que solicitará credenciais ao usuário.

Algumas situações em que o usuário pode ser solicitado a selecionar sua conta, inserir suas credenciais ou consentir com as permissões solicitadas pelo seu aplicativo são:

  • A primeira vez que o usuário entra no aplicativo
  • Se um utilizador redefinir a palavra-passe, terá de introduzir as suas credenciais
  • Se o consentimento for revogado
  • Se o seu aplicativo exigir consentimento explicitamente
  • Quando seu aplicativo está solicitando acesso a um recurso pela primeira vez
  • Quando MFA ou outras políticas de Acesso Condicional são necessárias

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

/**
 * 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, permite que os aplicativos solicitem tokens silenciosamente, acquireTokenSilentAsync() conforme mostrado no initializeUI(), no callGraphApiSilentButton manipulador de cliques:

/**
 * 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.javaloadAccount(). Carregar a conta do usuário é uma operação assíncrona, portanto, retornos de chamada para lidar quando a conta carrega, muda ou ocorre um erro é passado para a MSAL. O código a seguir também lida com 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);
        }
    });

Ligue para o Microsoft Graph

Quando um usuário está conectado, a chamada para o Microsoft Graph é feita por meio de uma solicitação HTTP pela callGraphAPI() qual é definido em SingleAccountModeFragment.java. Esta função é um wrapper que simplifica o exemplo fazendo 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 para um aplicativo MSAL que usa uma única conta.

Consulte Compreender o arquivo de configuração MSAL do Android para obter uma explicação desses campos.

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

"client_id" está pré-configurado para usar um registro de objeto de aplicativo que a Microsoft mantém. "redirect_uri"está pré-configurado para usar a chave de assinatura fornecida com o exemplo 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 várias contas e chamar uma API do Microsoft Graph.

Um exemplo de um aplicativo de várias contas é um aplicativo de email que permite que você trabalhe com várias contas de usuário, como uma conta profissional e uma conta pessoal.

Inicialização MSAL de várias contas

MultipleAccountModeFragment.java No arquivo, no onCreateView(), um objeto de aplicativo de várias contas (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 criado MultipleAccountPublicClientApplication é 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

Vários aplicativos de conta geralmente ligam getAccounts() para selecionar a conta a ser usada para operações MSAL. O código para carregar uma conta está no MultipleAccountModeFragment.java arquivo, em loadAccounts(). Carregar a conta do usuário é uma operação assíncrona. Assim, um retorno de chamada lida com as situações em que a conta é carregada, muda ou 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);
        }
    });
}

Obtenha um token de forma interativa ou silenciosa

Algumas situações em que o usuário pode ser solicitado a selecionar sua conta, inserir suas credenciais ou consentir com as permissões solicitadas pelo seu aplicativo são:

  • A primeira vez que os utilizadores iniciam sessão na aplicação
  • Se um utilizador redefinir a palavra-passe, terá de introduzir as suas credenciais
  • Se o consentimento for revogado
  • Se o seu aplicativo exigir consentimento explicitamente
  • Quando seu aplicativo está solicitando acesso a um recurso pela primeira vez
  • Quando MFA ou outras políticas de Acesso Condicional são necessárias

Normalmente, os aplicativos de várias contas devem adquirir tokens interativamente, ou seja, com a interface do usuário que envolve o usuário, com uma chamada para acquireToken(). O código para obter um token interativamente está no MultipleAccountModeFragment.java arquivo em initializeUI(), no manipulador de callGraphApiInteractiveButton cliques:

/**
 * 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 os aplicativos solicitem tokens sem avisar o usuário, conforme mostrado no MultipleAccountModeFragment.java arquivo, no callGraphApiSilentButtoninitializeUI() manipulador de cliques:

/**
 * 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 quaisquer tokens armazenados em cache para a conta, está no MultipleAccountModeFragment.java arquivo no initializeUI() 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 onRemoved chamada é 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.

Consulte Compreender o arquivo de configuração MSAL do Android para obter uma explicação dos vários campos.

Ao contrário do arquivo de configuração auth_config_single_account.json , este arquivo de configuração tem "account_mode" : "MULTIPLE" em vez de porque este é um aplicativo de "account_mode" : "SINGLE" várias contas.

"client_id" está pré-configurado para usar um registro de objeto de aplicativo que a Microsoft mantém. "redirect_uri"está pré-configurado para usar a chave de assinatura fornecida com o exemplo 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": "MULTIPLE",
  "broker_redirect_uri_registered": true,
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

Ajuda e suporte

Se precisar de ajuda, quiser comunicar um problema ou quiser saber mais sobre as suas opções de suporte, consulte Ajuda e suporte para programadores.

Próximos passos

Passe para o tutorial do Android no qual você cria um aplicativo Android que obtém um token de acesso da plataforma de identidade da Microsoft e o usa para chamar a API do Microsoft Graph.

Tutorial: Inicie sessão de utilizadores e chame o Microsoft Graph a partir de uma aplicação Android