Rövid útmutató: Bejelentkezés a felhasználókba, és a Microsoft Graph meghívása Android-alkalmazásból

  • Cikk

Ebben a rövid útmutatóban letölthet és futtathat egy kódmintát, amely bemutatja, hogyan jelentkezhet be egy Android-alkalmazás a felhasználókba, és hogyan szerezhet be hozzáférési jogkivonatot a Microsoft Graph API meghívásához.

Tekintse meg , hogyan működik a minta egy illusztrációhoz.

Az alkalmazásokat egy alkalmazásobjektumnak kell ábrázolnia a Microsoft Entra-azonosítóban, hogy a Microsoft Identitásplatform jogkivonatokat biztosítson az alkalmazásnak.

Előfeltételek

1. lépés: A mintaalkalmazás lekérése

Töltse le a kódot.

2. lépés: A mintaalkalmazás futtatása

Válassza ki emulátorát vagy fizikai eszközét az Android Studio elérhető eszközeinek legördülő listájából, és futtassa az alkalmazást.

A mintaalkalmazás az Egyfiókos mód képernyőn kezdődik. Alapértelmezés szerint egy alapértelmezett hatókört ( user.read) ad meg a rendszer, amelyet a microsoft graph API-hívás során a saját profiladatainak beolvasásakor használ. A Microsoft Graph API-hívás URL-címe alapértelmezés szerint meg van adva. Ha szeretné, mindkettőt módosíthatja.

Screenshot of the MSAL sample app showing single and multiple account usage.

Az alkalmazásmenü használatával válthat egy és több fiók mód között.

Egyfiókos módban jelentkezzen be munkahelyi vagy otthoni fiókkal:

  1. A gráfadatok interaktív lekérése lehetőséget választva kérje meg a felhasználót a hitelesítő adataik megadásához. A microsoft graph API-ra irányuló hívás kimenete a képernyő alján jelenik meg.
  2. Miután bejelentkezett, válassza a gráfadatok csendes lekérése lehetőséget a Microsoft Graph API meghívásához anélkül, hogy ismét hitelesítő adatokat kér a felhasználótól. A microsoft graph API-ra irányuló hívás kimenete a képernyő alján jelenik meg.

Több fiók módban is megismételheti ugyanazokat a lépéseket. Emellett eltávolíthatja a bejelentkezett fiókot is, amely szintén eltávolítja az adott fiók gyorsítótárazott jogkivonatait.

A minta működése

Diagram showing how the sample app generated by this quickstart works.

A kód töredékekbe van rendezve, amelyek bemutatják, hogyan írhat egyetlen és több fiókból álló MSAL-alkalmazást. A kódfájlok a következőképpen vannak rendszerezve:

Fájl Bemutatja
MainActivity A felhasználói felület kezelése
MSGraphRequestWrapper A Microsoft Graph API meghívása az MSAL által biztosított jogkivonat használatával
MultipleAccountModeFragment Inicializál egy többfiókos alkalmazást, betölt egy felhasználói fiókot, és jogkivonatot kap a Microsoft Graph API meghívásához
SingleAccountModeFragment Inicializál egy egyfiókos alkalmazást, betölt egy felhasználói fiókot, és jogkivonatot kap a Microsoft Graph API meghívásához
res/auth_config_multiple_account.json A több fiók konfigurációs fájlja
res/auth_config_single_account.json Az egyetlen fiók konfigurációs fájlja
Gradle Scripts/build.grade (Modul:alkalmazás) Itt adhatók hozzá az MSAL-kódtár függőségei

Most részletesebben áttekintjük ezeket a fájlokat, és mindegyikben fel fogjuk hívni az MSAL-specifikus kódot.

MSAL hozzáadása az alkalmazáshoz

Az MSAL (com.microsoft.identity.client) a felhasználók bejelentkezéséhez és a Microsoft Identitásplatform által védett API eléréséhez használt jogkivonatok lekéréséhez használt kódtár. A Gradle 3.0+ telepíti a kódtárat, amikor hozzáadja a következőt a Gradle Scripts>build.gradle -hoz (Modul: alkalmazás) a Függőségek területen:

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

Ez arra utasítja a Gradle-t, hogy töltse le és hozza létre az MSAL-t a maven centralról.

A mavenre mutató hivatkozásokat is hozzá kell adnia a settings.gradle (Modul: alkalmazás) allprojects-adattáraihoz> a dependencyResolutionManagement alatt:

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

MSAL-import

Az MSAL-kódtárra vonatkozó importálások a következők com.microsoft.identity.client.*: . Láthatja például, hogy import com.microsoft.identity.client.PublicClientApplication; melyik az osztály névtere PublicClientApplication , amely a nyilvános ügyfélalkalmazást jelöli.

SingleAccountModeFragment.java

Ez a fájl bemutatja, hogyan hozhat létre egyetlen fiókos MSAL-alkalmazást, és hogyan hívhat meg Egy Microsoft Graph API-t.

Az egyfiókos alkalmazásokat csak egyetlen felhasználó használja. Előfordulhat például, hogy csak egy fiókkal jelentkezik be a leképezési alkalmazásba.

Egyfiókos MSAL-inicializálás

A SingleAccountModeFragment.javametódusban onCreateView() egyetlen fiók PublicClientApplication jön létre a fájlban auth_config_single_account.json tárolt konfigurációs adatok használatával. Így inicializálhatja az MSAL-kódtárat egy egyfiókos MSAL-alkalmazásban való használatra:

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

Felhasználó bejelentkezése

A SingleAccountModeFragment.javafelhasználó bejelentkezéséhez szükséges kód a kattintáskezelőben signInButton találhatóinitializeUI().

Hívás signIn() jogkivonatok beszerzése előtt. signIn() úgy viselkedik, mintha acquireToken() meghívták, és interaktív kérést eredményezett a felhasználónak a bejelentkezéshez.

A felhasználó bejelentkezése aszinkron művelet. A rendszer visszahívást küld, amely meghívja a Microsoft Graph API-t, és frissíti a felhasználói felületet, amint a felhasználó bejelentkezik:

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

Felhasználó kijelentkeztetése

A SingleAccountModeFragment.javafelhasználó kijelentkeztetéséhez szükséges kód a kattintáskezelőben initializeUI()signOutButton található. A felhasználó kijelentkeztetése aszinkron művelet. Ha kijelentkezteti a felhasználót, azzal törli a fiók jogkivonat-gyorsítótárát is. A felhasználói fiók kijelentkezése után a rendszer visszahívást hoz létre a felhasználói felület frissítéséhez:

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

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

Jogkivonat interaktív vagy csendes lekérése

Ha a legkevesebb kérést szeretné megjeleníteni a felhasználónak, általában csendesen kap egy jogkivonatot. Ezután, ha hiba történik, próbálja meg interaktív módon lekérni a jogkivonatot. Az alkalmazás első hívásakor signIn()gyakorlatilag hívásként acquireToken()működik, amely hitelesítő adatok megadását kéri a felhasználótól.

Bizonyos helyzetek, amikor a felhasználót a rendszer arra kéri, hogy válassza ki a fiókját, adja meg a hitelesítő adatait, vagy adja meg az alkalmazás által kért engedélyeket:

  • Amikor a felhasználó először jelentkezik be az alkalmazásba
  • Ha egy felhasználó visszaállítja a jelszavát, meg kell adnia a hitelesítő adatait
  • Hozzájárulás visszavonása esetén
  • Ha az alkalmazás kifejezetten hozzájárulást igényel
  • Amikor az alkalmazás első alkalommal kér hozzáférést egy erőforráshoz
  • Ha MFA- vagy egyéb feltételes hozzáférési szabályzatra van szükség

A jogkivonat interaktív lekérésére szolgáló kód, azaz a felhasználót érintő felhasználói felület, a kattintáskezelőben initializeUI()callGraphApiInteractiveButton találhatóSingleAccountModeFragment.java:

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

Ha a felhasználó már bejelentkezett, lehetővé teszi, acquireTokenSilentAsync() hogy az alkalmazások csendesen kérhessenek jogkivonatokat a callGraphApiSilentButton kattintáskezelőben initializeUI()látható módon:

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

Fiók betöltése

A fiók betöltéséhez szükséges kód a következőben SingleAccountModeFragment.javaloadAccount()található: . A felhasználó fiókjának betöltése aszinkron művelet, ezért a visszahívások kezelése a fiók betöltésekor, módosításakor vagy hiba esetén az MSAL-nak történik. Az alábbi kód kezeli azt is onAccountChanged(), amely egy fiók eltávolításakor következik be, a felhasználó egy másik fiókra változik stb.

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

A Microsoft Graph meghívása

Amikor egy felhasználó bejelentkezik, a Microsoft Graph hívása egy HTTP-kérésen callGraphAPI() keresztül történik, amely a következőben van definiálva SingleAccountModeFragment.java: . Ez a függvény egy burkoló, amely leegyszerűsíti a mintát bizonyos feladatok elvégzésével, például a hozzáférési jogkivonat lekérésével authenticationResult és az MSGraphRequestWrapper hívásának csomagolásával, valamint a hívás eredményeinek megjelenítésével.

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

Ez egy egyetlen fiókot használó MSAL-alkalmazás konfigurációs fájlja.

A mezők magyarázatát az Android MSAL konfigurációs fájljának ismertetése című témakörben talál.

Figyelje meg, hogy az alkalmazás egyetlen "account_mode" : "SINGLE"fiók használatára van-e konfigurálva.

"client_id" előre konfigurálva van a Microsoft által fenntartott alkalmazásobjektum-regisztráció használatára. "redirect_uri"előre konfigurálva van a kódmintához megadott aláíró kulcs használatára.

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

Ez a fájl bemutatja, hogyan hozhat létre több fiókos MSAL-alkalmazást, és hogyan hívhat meg Egy Microsoft Graph API-t.

Több fiókalkalmazásra példa egy levelezőalkalmazás, amely lehetővé teszi, hogy több felhasználói fiókkal, például munkahelyi fiókkal és személyes fiókkal dolgozzon.

Több fiók MSAL-inicializálása

A fájlban több MultipleAccountModeFragment.java fiókalkalmazás-objektum (IMultipleAccountPublicClientApplication) jön létre a következő fájlban auth_config_multiple_account.json filetárolt konfigurációs adatok onCreateView()használatával:

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

A létrehozott MultipleAccountPublicClientApplication objektum egy osztálytag változóban van tárolva, így az MSAL-kódtár használatával jogkivonatokat szerezhet be, valamint betöltheti és eltávolíthatja a felhasználói fiókot.

Fiók betöltése

Általában több fiókalkalmazás hívja getAccounts() meg az MSAL-műveletekhez használni kívánt fiók kiválasztását. A fiók betöltéséhez szükséges kód a MultipleAccountModeFragment.java fájlban loadAccounts()található. A felhasználó fiókjának betöltése aszinkron művelet. A visszahívás tehát kezeli a fiók betöltésekor, módosításakor vagy hiba esetén előforduló helyzeteket.

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

Jogkivonat interaktív vagy csendes lekérése

Bizonyos helyzetek, amikor a felhasználót a rendszer arra kéri, hogy válassza ki a fiókját, adja meg a hitelesítő adatait, vagy adja meg az alkalmazás által kért engedélyeket:

  • Az első alkalommal, amikor felhasználók bejelentkeznek az alkalmazásba
  • Ha egy felhasználó visszaállítja a jelszavát, meg kell adnia a hitelesítő adatait
  • Hozzájárulás visszavonása esetén
  • Ha az alkalmazás kifejezetten hozzájárulást igényel
  • Amikor az alkalmazás első alkalommal kér hozzáférést egy erőforráshoz
  • Ha MFA- vagy egyéb feltételes hozzáférési szabályzatra van szükség

Több fiókalkalmazásnak általában interaktív módon kell jogkivonatokat beszereznie, azaz a felhasználót érintő felhasználói felülettel, és fel kell hívnia a felhasználót acquireToken(). A jogkivonat interaktív lekéréséhez szükséges kód a MultipleAccountModeFragment.java kattintáskezelő fájljában initializeUI()callGraphApiInteractiveButton található:

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

Az alkalmazások nem követelhetik meg, hogy a felhasználó minden alkalommal jelentkezzen be, amikor jogkivonatot kér. Ha a felhasználó már bejelentkezett, lehetővé teszi az alkalmazások számára, acquireTokenSilentAsync() hogy jogkivonatokat kérjenek anélkül, hogy rákérdeznek a felhasználóra, ahogyan az a MultipleAccountModeFragment.java fájlban látható, a callGraphApiSilentButton kattintáskezelőbeninitializeUI():

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

Fiók eltávolítása

A fiók eltávolítására szolgáló kód és a fiók gyorsítótárazott jogkivonatai a MultipleAccountModeFragment.java fiók eltávolítása gomb kezelőjében található fájlban initializeUI() vannak. Mielőtt eltávolíthat egy fiókot, szüksége lesz egy fiókobjektumra, amelyet az MSAL metódusok, például getAccounts() és acquireToken(). Mivel egy fiók eltávolítása aszinkron művelet, a rendszer a onRemoved visszahívást a felhasználói felület frissítéséhez adja meg.

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

Ez egy több fiókot használó MSAL-alkalmazás konfigurációs fájlja.

A különböző mezők magyarázatát az Android MSAL konfigurációs fájljának ismertetése című témakörben talál.

A auth_config_single_account.json konfigurációs fájltól eltérően ez a konfigurációs fájl nem azért van "account_mode" : "SINGLE""account_mode" : "MULTIPLE", mert több fiókalkalmazásról van szó.

"client_id" előre konfigurálva van a Microsoft által fenntartott alkalmazásobjektum-regisztráció használatára. "redirect_uri"előre konfigurálva van a kódmintához megadott aláíró kulcs használatára.

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

Súgó és támogatás

Ha segítségre van szüksége, szeretne jelentést készíteni egy problémáról, vagy szeretne többet megtudni a támogatási lehetőségekről, olvassa el a súgót és a fejlesztők támogatását.

Következő lépések

Lépjen tovább az Android-oktatóanyagra, amelyben létrehoz egy Android-alkalmazást, amely lekéri a hozzáférési jogkivonatot a Microsoft Identitásplatform, és a Microsoft Graph API meghívására használja.

Oktatóanyag: Felhasználók bejelentkezése és a Microsoft Graph meghívása Android-alkalmazásból