Guia de início rápido: iniciar sessão dos utilizadores e chamar a API do Microsoft Graph a partir de uma aplicação Android

Neste guia de início rápido, o utilizador descarrega e executa um exemplo de código que demonstra como uma aplicação Android pode iniciar sessão para utilizadores e obter um token de acesso para chamar a API do Microsoft Graph.

Consulte Como funciona o exemplo para obter uma ilustração.

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

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• Android Studio
• Android 16+

Etapa 1: Configurar seu aplicativo no portal do Azure

Para que o exemplo de código neste início rápido funcione, adicione um URI de redirecionamento compatível com o broker de autenticação.

Passo 2: Faça o download do projeto

Execute o projeto usando o Android Studio.

Etapa 3: Seu aplicativo está configurado e pronto para ser executado

Configuramos seu projeto com valores das propriedades do seu aplicativo e ele está pronto para ser executado. A aplicação 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.

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.

Como funciona a amostra

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:

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

Adicionando MSAL ao aplicativo

MSAL (com.microsoft.identity.client) é a biblioteca usada para autenticar utilizadores e solicitar tokens usados para aceder a 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:2.+'
    ...
}

Isso instrui o Gradle a baixar e construir o MSAL a partir do maven central.

Você também deve adicionar referências ao maven à parte de todos os projetos> do build.gradle (Módulo: aplicação) da seguinte forma:

allprojects {
    repositories {
        mavenCentral()
        google()
        mavenLocal()
        maven {
            url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
        }
        maven {
            name "vsts-maven-adal-android"
            url "https://identitydivision.pkgs.visualstudio.com/_packaging/AndroidADAL/maven/v1"
            credentials {
                username System.getenv("ENV_VSTS_MVN_ANDROIDADAL_USERNAME") != null ? System.getenv("ENV_VSTS_MVN_ANDROIDADAL_USERNAME") : project.findProperty("vstsUsername")
                password System.getenv("ENV_VSTS_MVN_ANDROIDADAL_ACCESSTOKEN") != null ? System.getenv("ENV_VSTS_MVN_ANDROIDADAL_ACCESSTOKEN") : project.findProperty("vstsMavenAccessToken")
            }
        }
        jcenter()
    }
}

Importações de 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 de conta única do MSAL

No auth_config_single_account.json, no 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 de um utilizador

No SingleAccountModeFragment.java, o código para iniciar sessão de um utilizador está em initializeUI(), no manipulador de cliques signInButton.

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.

Iniciar sessão de um utilizador é uma operação assíncrona. Passa-se um callback que chama a API do Microsoft Graph e atualiza a interface do utilizador assim que o utilizador inicia sessão.

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

Terminar a sessão de um utilizador

No SingleAccountModeFragment.java, o código para desassinar um utilizador está no initializeUI(), no manipulador de cliques signOutButton. Terminar a sessão de um utilizador é uma operação assíncrona. Terminar a sessão do utilizador também limpa a cache de tokens dessa conta. Um callback é criado para atualizar a interface de utilizador assim que a conta de utilizador é desligada.

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, procure acessar o 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 a sua aplicação exigir explicitamente consentimento
• 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 utilizador que envolve o utilizador, está em SingleAccountModeFragment.java, em 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 utilizador já tiver iniciado sessão, acquireTokenSilentAsync() permite que as aplicações solicitem tokens silenciosamente, conforme mostrado no >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.javaloadAccount(). Carregar a conta do utilizador é uma operação assíncrona, portanto, callbacks para lidar quando a conta carrega, muda ou ocorre um erro são passados 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 utilizador está conectado, a chamada para a Microsoft Graph é feita através de uma solicitação HTTP por callGraphAPI(), que é definida 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" : "DEFAULT",
  "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(), é criado um objeto de aplicação para gestão de múltiplas contas (IMultipleAccountPublicClientApplication), 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

Aplicações de múltiplas contas geralmente chamam getAccounts() para selecionar a conta a ser usada para operações do 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 callback lida com as situações em que a conta é carregada, é alterada 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 usuários entram no aplicativo
• Se um utilizador redefinir a palavra-passe, terá de introduzir as suas credenciais
• Se o consentimento for revogado
• Se a sua aplicação exigir explicitamente consentimento
• 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, as aplicações de várias contas devem adquirir tokens de forma interativa, ou seja, com uma interface que envolve o utilizador, com uma chamada para acquireToken(). O código para obter um token interativamente está no MultipleAccountModeFragment.java arquivo em 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 os aplicativos solicitem tokens sem avisar o usuário, conforme mostrado no MultipleAccountModeFragment.java arquivo, no initializeUI()callGraphApiSilentButton 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, bem como quaisquer tokens em cache dessa conta, está no arquivo MultipleAccountModeFragment.java no manipulador em initializeUI() para o botão de remoção de 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 callback onRemoved é fornecido para atualizar a UI.

/**
 * 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 ficheiro de configuração auth_config_single_account.json, este ficheiro de configuração tem "account_mode" : "MULTIPLE" em vez de "account_mode" : "SINGLE", porque é uma aplicação de múltiplas 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" : "DEFAULT",
  "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.