Snabbstart: Logga in användare och anropa Microsoft Graph API från en Android-app

I den här snabbstarten laddar du ned och kör ett kodexempel som visar hur ett Android-program kan logga in användare och få en åtkomsttoken för att anropa Microsoft Graph API.

Se Så här fungerar exemplet för en bild.

Program måste representeras av ett appobjekt i Microsoft Entra-ID så att Microsofts identitetsplattform kan tillhandahålla token till ditt program.

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
• Android Studio
• Android 16+

Steg 1: Konfigurera din app i Azure-portalen

För att kodexemplet i den här snabbstarten ska fungera lägger du till en omdirigerings-URI som är kompatibel med Auth Broker.

Steg 2: Ladda ned projektet

Kör projektet med Android Studio.

Steg 3: Din app är konfigurerad och redo att köras

Vi har konfigurerat projektet med värden för appens egenskaper och är redo att köras. Exempelappen startar på skärmen Läge för enskilt konto. Ett standardomfång, user.read, tillhandahålls som standard, vilket används när du läser dina egna profildata under Microsoft Graph API-anropet. URL:en för Microsoft Graph API-anropet tillhandahålls som standard. Du kan ändra båda om du vill.

Använd appmenyn för att ändra mellan enstaka och flera kontolägen.

Logga in med ett arbets- eller hemkonto i läget för ett enskilt konto:

1. Välj Hämta diagramdata interaktivt för att fråga användaren om deras autentiseringsuppgifter. Du ser utdata från anropet till Microsoft Graph API längst ned på skärmen.
2. När du har loggat in väljer du Hämta grafdata tyst för att göra ett anrop till Microsoft Graph API utan att fråga användaren om autentiseringsuppgifter igen. Du ser utdata från anropet till Microsoft Graph API längst ned på skärmen.

I flera kontolägen kan du upprepa samma steg. Dessutom kan du ta bort det inloggade kontot, vilket även tar bort cachelagrade token för det kontot.

Så här fungerar exemplet

Koden är uppdelad i fragment som visar hur du skriver en enskild och flera konton MSAL-app. Kodfilerna ordnas på följande sätt:

Nu ska vi titta närmare på de här filerna och framhäva den MSAL-specifika koden i var och en.

Lägga till MSAL i appen

MSAL (com.microsoft.identity.client) är det bibliotek som används för att logga in användare och begära token som används för att komma åt ett API som skyddas av Microsofts identitetsplattform. Gradle 3.0+ installerar biblioteket när du lägger till följande i Gradle Scripts>build.gradle (modul: app) under Beroenden:

dependencies {
    ...
    implementation 'com.microsoft.identity.client:msal:2.+'
    ...
}

Detta instruerar Gradle att ladda ned och skapa MSAL från maven central.

Du måste också lägga till referenser till maven till allprojects-lagringsplatserna> i build.gradle (modul: app) så här:

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()
    }
}

MSAL-importer

De importer som är relevanta för MSAL-biblioteket är com.microsoft.identity.client.*. Du ser import > com.microsoft.identity.client.PublicClientApplication; till exempel vilket namnområde för PublicClientApplication klassen som representerar ditt offentliga klientprogram.

SingleAccountModeFragment.java

Den här filen visar hur du skapar en MSAL-app för ett konto och anropar ett Microsoft Graph API.

Appar med ett enda konto används bara av en enskild användare. Du kanske till exempel bara har ett konto som du loggar in på din mappningsapp med.

MSAL-initiering för enskilt konto

I auth_config_single_account.jsoni onCreateView()skapas ett enda konto PublicClientApplication med hjälp av konfigurationsinformationen auth_config_single_account.json som lagras i filen. Så här initierar du MSAL-biblioteket för användning i en MSAL-app med ett enda konto:

...
// 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);
            }
        });

Logga in en användare

I SingleAccountModeFragment.javafinns koden för att logga in en användare i initializeUI()i signInButton klickhanteraren.

Anropa signIn() innan du försöker hämta token. signIn() beter sig som om acquireToken() anropas, vilket resulterar i en interaktiv uppmaning för användaren att logga in.

Att logga in en användare är en asynkron åtgärd. Ett återanrop skickas som anropar Microsoft Graph API och uppdaterar användargränssnittet när användaren loggar in:

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

Logga ut en användare

I SingleAccountModeFragment.javafinns koden för att logga ut en användare i initializeUI()i signOutButton klickhanteraren. Att logga ut en användare är en asynkron åtgärd. När användaren loggas ut rensas även tokencachen för det kontot. Ett återanrop skapas för att uppdatera användargränssnittet när användarkontot har loggats ut:

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

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

Hämta en token interaktivt eller tyst

Om du vill visa det minsta antalet uppmaningar till användaren får du vanligtvis en token tyst. Om det sedan uppstår ett fel försöker du komma åt token interaktivt. Första gången appen anropar signIn()fungerar den effektivt som ett anrop till acquireToken(), vilket uppmanar användaren att ange autentiseringsuppgifter.

Vissa situationer när användaren kan uppmanas att välja sitt konto, ange sina autentiseringsuppgifter eller godkänna de behörigheter som din app har begärt är:

• Första gången användaren loggar in på programmet
• Om en användare återställer sitt lösenord måste de ange sina autentiseringsuppgifter
• Om medgivande återkallas
• Om din app uttryckligen kräver medgivande
• När ditt program begär åtkomst till en resurs för första gången
• När MFA eller andra principer för villkorsstyrd åtkomst krävs

Koden för att hämta en token interaktivt, som är med användargränssnittet som ska involvera användaren, finns i SingleAccountModeFragment.java, i initializeUI(), i callGraphApiInteractiveButton klickhanteraren:

/**
 * 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());

Om användaren redan har loggat in acquireTokenSilentAsync() tillåter appar att begära token tyst enligt vad som visas i >initializeUI(), i callGraphApiSilentButton klickhanteraren:

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

Läsa in ett konto

Koden för att läsa in ett konto finns i SingleAccountModeFragment.javaloadAccount(). Att läsa in användarens konto är en asynkron åtgärd, så återanrop som ska hanteras när kontot läses in, ändras eller ett fel inträffar skickas till MSAL. Följande kod hanterar onAccountChanged()också , som inträffar när ett konto tas bort, användaren ändras till ett annat konto och så vidare.

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);
        }
    });

Anropa Microsoft Graph

När en användare är inloggad görs anropet till Microsoft Graph via en HTTP-begäran som callGraphAPI() definieras i SingleAccountModeFragment.java. Den här funktionen är en omslutning som förenklar exemplet genom att utföra vissa uppgifter, till exempel att hämta åtkomsttoken från authenticationResult och paketera anropet till MSGraphRequestWrapper och visa resultatet av anropet.

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

Det här är konfigurationsfilen för en MSAL-app som använder ett enda konto.

En förklaring av dessa fält finns i Förstå Android MSAL-konfigurationsfilen .

Observera förekomsten av "account_mode" : "SINGLE", som konfigurerar den här appen för att använda ett enda konto.

"client_id" är förkonfigurerad för att använda en appobjektregistrering som Microsoft underhåller. "redirect_uri"är förkonfigurerad för att använda signeringsnyckeln som medföljer kodexemplet.

{
  "client_id" : "0984a7b6-bc13-4141-8b0d-8f767e136bb7",
  "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

Den här filen visar hur du skapar en MSAL-app för flera konton och anropar ett Microsoft Graph API.

Ett exempel på en app för flera konton är en e-postapp som gör att du kan arbeta med flera användarkonton, till exempel ett arbetskonto och ett personligt konto.

MSAL-initiering för flera konton

MultipleAccountModeFragment.java I filen i onCreateView()skapas ett objekt för flera kontoappar (IMultipleAccountPublicClientApplication) med hjälp av konfigurationsinformationen auth_config_multiple_account.json filesom lagras i :

// 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) {
                ...
            }
        });

Det skapade MultipleAccountPublicClientApplication objektet lagras i en klassmedlemsvariabel så att det kan användas för att interagera med MSAL-biblioteket för att hämta token och läsa in och ta bort användarkontot.

Läsa in ett konto

Flera kontoappar anropar getAccounts() vanligtvis för att välja det konto som ska användas för MSAL-åtgärder. Koden för att läsa in ett konto finns i MultipleAccountModeFragment.java filen i loadAccounts(). Att läsa in användarens konto är en asynkron åtgärd. Så ett återanrop hanterar situationer när kontot läses in, ändringar eller ett fel inträffar.

/**
 * 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);
        }
    });
}

Hämta en token interaktivt eller tyst

Vissa situationer när användaren kan uppmanas att välja sitt konto, ange sina autentiseringsuppgifter eller godkänna de behörigheter som din app har begärt är:

• Första gången användaren loggar in på programmet
• Om en användare återställer sitt lösenord måste de ange sina autentiseringsuppgifter
• Om medgivande återkallas
• Om din app uttryckligen kräver medgivande
• När ditt program begär åtkomst till en resurs för första gången
• När MFA eller andra principer för villkorsstyrd åtkomst krävs

Flera kontoappar bör vanligtvis hämta token interaktivt, det vill säga med användargränssnittet som involverar användaren, med ett anrop till acquireToken(). Koden för att hämta en token interaktivt finns i MultipleAccountModeFragment.java filen i initializeUI> (), i callGraphApiInteractiveButton klickhanteraren:

/**
 * 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());

Appar bör inte kräva att användaren loggar in varje gång de begär en token. Om användaren redan har loggat in acquireTokenSilentAsync() tillåter appar att begära token utan att fråga användaren, som visas i MultipleAccountModeFragment.java filen, iinitializeUI()callGraphApiSilentButton klickhanteraren:

/**
 * 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());

Ta bort ett konto

Koden för att ta bort ett konto och eventuella cachelagrade token för kontot finns i MultipleAccountModeFragment.java filen i initializeUI() hanteraren för knappen ta bort konto. Innan du kan ta bort ett konto behöver du ett kontoobjekt som du hämtar från MSAL-metoder som getAccounts() och acquireToken(). Eftersom det är en asynkron åtgärd att ta bort ett konto tillhandahålls återanropet onRemoved för att uppdatera användargränssnittet.

/**
 * 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

Det här är konfigurationsfilen för en MSAL-app som använder flera konton.

En förklaring av de olika fälten finns i Förstå Android MSAL-konfigurationsfilen .

Till skillnad från auth_config_single_account.json konfigurationsfilen har "account_mode" : "MULTIPLE" den här konfigurationsfilen "account_mode" : "SINGLE" i stället för eftersom det här är en app med flera konton.

"client_id" är förkonfigurerad för att använda en appobjektregistrering som Microsoft underhåller. "redirect_uri"är förkonfigurerad för att använda signeringsnyckeln som medföljer kodexemplet.

{
  "client_id" : "0984a7b6-bc13-4141-8b0d-8f767e136bb7",
  "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"
      }
    }
  ]
}

Hjälp och support

Om du behöver hjälp, vill rapportera ett problem eller vill lära dig mer om dina supportalternativ kan du läsa Hjälp och support för utvecklare.

Nästa steg

Gå vidare till Android-självstudien där du skapar en Android-app som hämtar en åtkomsttoken från Microsofts identitetsplattform och använder den för att anropa Microsoft Graph API.