Rövid útmutató: Felhasználók bejelentkeztetése és a Microsoft Graph API meghívása Android-alkalmazásokból

Ebben a rövid útmutatóban egy kódmintát fog letölteni és futtatni, amely bemutatja, hogyan tud egy Android-alkalmazás felhasználókat bejelentkezni, és lekért egy hozzáférési jogkivonatot a Microsoft Graph API hívásához.

Ábra: A minta működése.

Az alkalmazásoknak egy alkalmazásobjektumnak kell Azure Active Directory, hogy a Microsoft Identitásplatform jogkivonatokat adjanak az alkalmazásnak.

Előfeltételek

1. lépés: Az alkalmazás konfigurálása a Azure Portal

Ahhoz, hogy a rövid útmutatóban a kódminta működjön, adjon hozzá egy, az Auth brokerrel kompatibilis átirányítási URI-t.

Már konfigurált Az alkalmazás már konfigurálva van ezekkel az attribútumokkal

2. lépés: A projekt letöltése

Futtassa a projektet a Android Studio.

3. lépés: Az alkalmazás konfigurálva van, és készen áll a futtatásra

Konfigurálta a projektet az alkalmazás tulajdonságainak értékeivel, és készen áll a futtatásra. A mintaalkalmazás az Egyfiókos mód képernyőn indul el. Alapértelmezés szerint a user.read hatókör van megtéve, amely a saját profiladatok microsoftos API-hívás során való Graph lesz használva. A Microsoft Graph API-hívás URL-címe alapértelmezés szerint meg van állítva. Ha szeretné, mindkettőt módosíthatja.

MSAL-mintaalkalmazás az egy- és többfiókos használattal

Az alkalmazásmenüvel válthat egy- és több fiókmód között.

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

  1. Válassza a Gráfadatok interaktív lekérdezve lehetőséget a felhasználó hitelesítő adatainak megadásához. A képernyő alján megjelenik a Microsoft Graph API hívásának kimenete.
  2. Miután bejelentkezett, válassza a Gráfadatok csendes lehívása lehetőséget a Microsoft Graph API hívásához anélkül, hogy a felhasználónak újra meg kell adnia a hitelesítő adatokat. A képernyő alján megjelenik a Microsoft Graph API hívásának kimenete.

Több fiók módban megismételheti ugyanezeket a lépéseket. Emellett eltávolíthatja a bejelentkezett fiókot, amely a fiók gyorsítótárazott jogkivonatát is eltávolítja.

Megjegyzés

Enter_the_Supported_Account_Info_Here

1. lépés: A mintaalkalmazás letöltése

Töltse le a kódot.

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

Válassza ki az emulátort vagy fizikai eszközt Android Studio elérhető eszközök legördülő menüből, és futtassa az alkalmazást.

A mintaalkalmazás az Egyfiókos mód képernyőn indul el. Alapértelmezés szerint a user.read hatókör van megtéve, amely a saját profiladatok microsoftos API-hívás során való Graph lesz használva. A Microsoft Graph API-hívás URL-címe alapértelmezés szerint meg van állítva. Ha szeretné, mindkettőt módosíthatja.

MSAL-mintaalkalmazás az egy- és többfiókos használattal

Az alkalmazásmenüvel válthat egy- és több fiókmód között.

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

  1. Válassza a Gráfadatok interaktív lekérdezve lehetőséget a felhasználó hitelesítő adatainak megadásához. A képernyő alján megjelenik a Microsoft Graph API hívásának kimenete.
  2. Miután bejelentkezett, válassza a Gráfadatok csendes lehívása lehetőséget a Microsoft Graph API hívásához anélkül, hogy a felhasználónak újra meg kell adnia a hitelesítő adatokat. A képernyő alján megjelenik a Microsoft Graph API hívásának kimenete.

Több fiók módban megismételheti ugyanezeket a lépéseket. Emellett eltávolíthatja a bejelentkezett fiókot, amely a fiók gyorsítótárazott jogkivonatát is eltávolítja.

A minta működése

A mintaalkalmazás képernyőképe

A kód töredékekbe van rendezve, amelyek egy és több fiók MSAL-alkalmazás írását mutatják be. A kódfájlok a következőképpen vannak rendszerezve:

Fájl Útmutató ehhez:
MainActivity (Fő tevékenység) A felhasználói felületet kezeli
MSGraphRequestWrapper A Microsoft Graph API hívása az MSAL által biztosított jogkivonattal
MultipleAccountModeFragment Inicializál egy többfiókos alkalmazást, betölt egy felhasználói fiókot, és lekért egy jogkivonatot a Microsoft Graph API-hoz
SingleAccountModeFragment Inicializál egy egyfiókos alkalmazást, betölt egy felhasználói fiókot, és lekért egy jogkivonatot a Microsoft Graph API-hoz
res/auth_config_multiple_account.jsbe A több fiók konfigurációs fájlja
res/auth_config_single_account.jsbe Az egyetlen fiók konfigurációs fájlja
Gradle Scripts/build.grade (Module:app) Az MSAL-kódtár függőségei itt vannak hozzáadva

Most részletesebben is megnézzük ezeket a fájlokat, és mindegyikben kihívjuk az MSAL-specifikus kódot.

MSAL hozzáadása az alkalmazáshoz

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

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

Ez arra utasítja a Gradle-t, hogy töltse le és építse fel az MSAL-t a Maven centralból.

A mavenre mutató hivatkozásokat is hozzá kell adni a > build.gradle (Modul: alkalmazás) összesprojekt adattár részéhez a következő szerint:

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-importok

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

SingleAccountModeFragment.java

Ez a fájl bemutatja, hogyan hozhat létre egy egyetlen fiókot használó 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 egyetlen fiókkal jelentkezik be a leképezési alkalmazásba.

Egyfiókos MSAL inicializálása

A fájlban egyetlen fiók jön létre a fájlban tárolt konfigurációs auth_config_single_account.json onCreateView() adatok PublicClientApplication auth_config_single_account.json 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 fájlban a felhasználó bejelentkeztető kódja a fájlban van SingleAccountModeFragment.java initializeUI() a signInButton kattintáskezelőben.

A signIn() jogkivonatok lekérte előtt hívja meg a (hívás) hívást. signIn() A úgy viselkedik, mintha a rendszer hívva lenne, így a felhasználónak egy interaktív kérést kell kérnie acquireToken() a bejelentkezéshez.

A felhasználóba való bejelentkezés aszinkron művelet. A rendszer visszahívást ad át, amely a Microsoft Graph API-t hívja meg, és frissíti a felhasználói felületet, miután a felhasználó bejelentkezik:

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

Felhasználó kijelentkezetet

A fájlban a felhasználót kijelentkeztető kód a fájlban van SingleAccountModeFragment.java initializeUI() a signOutButton kattintáskezelőben. A felhasználó kijelentkeztet egy aszinkron művelet. A felhasználó kijelentkezése törli a fiók jogkivonat-gyorsítótárát is. A felhasználói felület a felhasználói fiók kijelentkeztével való frissítéséhez létrejön egy visszahívás:

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 beszerzése

Ahhoz, hogy a felhasználónak a legtöbb kérést meg tudja jelenülni, általában csendesen kap jogkivonatot. Ezután hiba esetén próbálja meg interaktívan lehozni a jogkivonatot. Amikor az alkalmazás először hívja meg a-t, gyakorlatilag a hívásaként működik, amely hitelesítő adatokat kér a signIn() acquireToken() felhasználótól.

Bizonyos helyzetekben előfordulhat, hogy a felhasználónak ki kell választania a fiókját, meg kell adnia a hitelesítő adatait, vagy meg kell adnia 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
  • A hozzájárulás visszavonása esetén
  • Ha az alkalmazás kifejezetten jóváhagyást igényel
  • Amikor az alkalmazás első alkalommal kér hozzáférést egy erőforráshoz
  • Ha MFA vagy más feltételes hozzáférési szabályzatok szükségesek

A jogkivonat interaktív lekért kódja, amely a felhasználót is magában foglalja a felhasználói felületen, a fájlban van a SingleAccountModeFragment.java initializeUI() callGraphApiInteractiveButton kattintáskezelőben:

/**
 * 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, az lehetővé teszi az alkalmazások számára, hogy csendesen kérjenek jogkivonatokat a acquireTokenSilentAsync() initializeUI() callGraphApiSilentButton kattintáskezelőben 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 a kód a következőben SingleAccountModeFragment.java van: loadAccount() . A felhasználó fiókjának betöltése aszinkron művelet, így a visszahívások kezelik, amikor a fiók betöltődik, módosul, vagy hiba történik az MSAL-nek. A következő kód a fiókot is kezeli, amely akkor fordul elő, ha egy fiókot eltávolít, a felhasználó egy másik fiókra módosít onAccountChanged() 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

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

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.jsbe

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

A mezők magyarázatát lásd: Az Android MSAL konfigurációs fájljának magyarázata.

Figyelje meg a "account_mode" : "SINGLE" jelenlétét, amely úgy konfigurálja az alkalmazást, hogy egyetlen fiókot használjon.

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

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

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

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

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

A fájlban a fájlban egy több fiókalkalmazás-objektum ( ) jön létre a fájlban tárolt konfigurációs MultipleAccountModeFragment.java onCreateView() információk IMultipleAccountPublicClientApplication auth_config_multiple_account.json file 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 objektum egy osztálytag-változóban van tárolva, így használható az MSAL-kódtárban a jogkivonatok lekért és a felhasználói fiók betöltéséhez és MultipleAccountPublicClientApplication eltávolításához.

Fiók betöltése

Az MSAL-műveletekhez használt fiókot általában több getAccounts() fiókalkalmazás hívja meg. A fiók betöltéséhez a kód a MultipleAccountModeFragment.java fájlban loadAccounts() található. A felhasználói fiók betöltése aszinkron művelet. Így a visszahívás kezeli azokat a helyzeteket, amikor a fiók betöltődik, módosul vagy hiba történik.

/**
 * 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 beszerzése

Bizonyos helyzetekben előfordulhat, hogy a felhasználónak ki kell választania a fiókját, meg kell adnia a hitelesítő adatait, vagy meg kell adnia 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
  • A hozzájárulás visszavonása esetén
  • Ha az alkalmazás kifejezetten jóváhagyást igényel
  • Amikor az alkalmazás első alkalommal kér hozzáférést egy erőforráshoz
  • Ha MFA vagy más feltételes hozzáférési szabályzatok szükségesek

Általában több fiókalkalmazásnak kell interaktív módon jogkivonatokat szereznie, azaz olyan felhasználói felülettel, amely magában foglalja a felhasználót a acquireToken() hívásával. A jogkivonat interaktív lekért kódja a fájljában található MultipleAccountModeFragment.java initializeUI() a callGraphApiInteractiveButton kattintáskezelőben:

/**
 * 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 a felhasználótól, hogy minden alkalommal jelentkezzen be, amikor jogkivonatot kér. Ha a felhasználó már bejelentkezett, az lehetővé teszi, hogy az alkalmazások jogkivonatokat kérjenek anélkül, hogy a felhasználónak a kattintáskezelőben a fájlban látható módon lekérte acquireTokenSilentAsync() MultipleAccountModeFragment.java initializeUI() callGraphApiSilentButton volna:

/**
 * 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 és a fiókhoz gyorsítótárazott jogkivonatok eltávolítására vonatkozó kód a fiók eltávolítása gomb MultipleAccountModeFragment.java initializeUI() kezelőfájljában található. A fiók eltávolítása előtt szüksége lesz egy fiókobjektumra, amelyet az olyan MSAL-metódusok segítségével szerezhet be, mint a getAccounts() és acquireToken() a . Mivel a fiók eltávolítása aszinkron művelet, a felhasználói felület frissítéséhez a visszahívás onRemoved lesz megadva.

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

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 magyarázatát lásd: Understand the Android MSAL configuration file (Az Android MSAL konfigurációs fájljának magyarázata).

A konfigurációs auth_config_single_account.jsfájlon található fájltól eltérően ez a konfigurációs fájl nem a,, mert "account_mode" : "MULTIPLE" ez egy több "account_mode" : "SINGLE" fiókalkalmazás.

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

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

Súgó és támogatás

Ha segítségre van szüksége, jelentsen egy problémát, vagy szeretne többet megtudni a támogatási lehetőségekről, lásd: Súgó és támogatás fejlesztőknek.

Következő lépések

Lépjen tovább az Android-oktatóanyagra, amelyben olyan Android-alkalmazást hoz létre, amely lekért egy hozzáférési jogkivonatot a Microsoft Identitásplatform és a használatával hívja meg a Microsoft Graph API-t.