Dela via


Snabbstart: Logga in användare och anropa Microsoft Graph 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.

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

Förutsättningar

Så här fungerar exemplet

Diagram som visar hur exempelappen som genereras av den här snabbstarten fungerar.

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

Fil Demonstrationer
MainActivity Hanterar användargränssnittet
MSGraphRequestWrapper Anropar Microsoft Graph API med hjälp av den token som tillhandahålls av MSAL
MultipleAccountModeFragment Initierar ett program med flera konton, läser in ett användarkonto och hämtar en token för att anropa Microsoft Graph API
SingleAccountModeFragment Initierar ett program med ett enda konto, läser in ett användarkonto och hämtar en token för att anropa Microsoft Graph API
res/auth_config_multiple_account.json Konfigurationsfilen för flera konton
res/auth_config_single_account.json Konfigurationsfilen för ett konto
Gradle Scripts/build.grade (Modul:app) MSAL-biblioteksberoenden läggs till här

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

Hämta exempelappen

Registrera exempelappen

Dricks

Stegen i den här artikeln kan variera något beroende på vilken portal du börjar från.

  1. Logga in på administrationscentret för Microsoft Entra som minst programutvecklare.

  2. Om du har åtkomst till flera klienter använder du ikonen Inställningar på den översta menyn för att växla till den klientorganisation där du vill registrera programmet från menyn Kataloger + prenumerationer.

  3. Bläddra till Appregistreringar för identitetsprogram>>.

  4. Välj Ny registrering.

  5. Ange ett namn för ditt program. Användare av din app kan se det här namnet och du kan ändra det senare.

  6. För Kontotyper som stöds väljer du Konton i valfri organisationskatalog (Alla Microsoft Entra-kataloger – Multitenant) och personliga Microsoft-konton (t.ex. Skype, Xbox). Om du vill ha information om olika kontotyper väljer du alternativet Hjälp mig .

  7. Välj Registrera.

  8. Under Hantera väljer du Autentisering>Lägg till en plattforms>Android.

  9. Ange projektets paketnamn baserat på exempeltypen som du laddade ned ovan.

    • Java-exempel – com.azuresamples.msalandroidapp
    • Kotlin-exempel - com.azuresamples.msalandroidkotlinapp
  10. I avsnittet Signaturhash i fönstret Konfigurera din Android-app väljer du Generera en utvecklingssignaturhash. Kopiera kommandot KeyTool till kommandoraden.

    • KeyTool.exe installeras som en del av Java Development Kit (JDK). Du måste också installera OpenSSL-verktyget för att köra KeyTool-kommandot. Mer information finns i Android-dokumentation om hur du genererar en nyckel för mer information.
  11. Ange den signaturhash som genererats av KeyTool.

  12. Välj Konfigurera och spara MSAL-konfigurationen som visas i Android-konfigurationsfönstret så att du kan ange den när du konfigurerar appen senare.

  13. Välj Klar.

Konfigurera exempelappen

  1. I Android Studio-projektfönstret navigerar du till app\src\main\res.

  2. Högerklicka på res och välj Ny>katalog. Ange raw som nytt katalognamn och välj OK.

  3. I app>src>main>res>raw går du till JSON-filen med namnet auth_config_single_account.json och klistrar in MSAL-konfigurationen som du sparade tidigare.

    Under omdirigerings-URI:n klistrar du in:

      "account_mode" : "SINGLE",
    

    Konfigurationsfilen bör likna det här exemplet:

    {
      "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"
          }
        }
      ]
    }
    

    Eftersom den här självstudien bara visar hur du konfigurerar en app i läget För ett enskilt konto kan du läsa enkel- eller flera kontolägen och konfigurera din app för mer information

Kör exempelappen

Välj din emulator eller fysiska enhet från listrutan För Android Studio-tillgängliga enheter och kör appen.

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.

Skärmbild av MSAL-exempelappen som visar enkel och flera kontoanvändning.

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.

Mer information

Läs dessa avsnitten om du vill lära dig mer om den här snabbstarten.

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 Microsoft platforma za identitete. 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:5.1.0'
    implementation 'com.android.volley:volley:1.2.1'
    ...
}

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 settings.gradle (Modul: app) under dependencyResolutionManagement:

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

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 SingleAccountModeFragment.javai onCreateView() -metoden 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 hämta en 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": "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

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": "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"
      }
    }
  ]
}

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 Microsoft platforma za identitete och använder den för att anropa Microsoft Graph API.