Rövid útmutató: Bejelentkezés a felhasználókba, és a Microsoft Graph meghívása Android-alkalmazásból
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.
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
- Egy Azure-fiók, aktív előfizetéssel. Fiók ingyenes létrehozása.
- Android Studio
- Android 16+
A minta működése
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.
Mintaalkalmazás letöltése
- Java: Töltse le a kódot.
- Kotlin: Töltse le a kódot.
A mintaalkalmazás regisztrálása
Tipp.
A cikkben szereplő lépések a portáltól függően kissé eltérhetnek.
Jelentkezzen be a Microsoft Entra felügyeleti központba legalább alkalmazásfejlesztőként.
Ha több bérlőhöz is hozzáfér, a felső menü Beállítások ikonjával
válthat arra a bérlőre, amelyben regisztrálni szeretné az alkalmazást a Könyvtárak + előfizetések menüből.
Keresse meg az identitásalkalmazásokat>> Alkalmazásregisztrációk.
Új regisztráció kiválasztása.
Adja meg az alkalmazás nevét. Előfordulhat, hogy az alkalmazás felhasználói látják ezt a nevet, és később módosíthatja.
Támogatott fióktípusok esetén válassza a Fiókok lehetőséget bármely szervezeti könyvtárban (Bármely Microsoft Entra címtár – Több-bérlős) és személyes Microsoft-fiókokban (pl. Skype, Xbox). A különböző fióktípusokkal kapcsolatos információkért válassza a Súgó kiválasztása lehetőséget.
Válassza ki a pénztárgépet.
A Kezelés területen válassza a Hitelesítés>hozzáadása platform>Androidhoz lehetőséget.
Adja meg a projekt csomagnevét a fent letöltött mintatípus alapján.
- Java-minta –
com.azuresamples.msalandroidapp
- Kotlin-minta –
com.azuresamples.msalandroidkotlinapp
- Java-minta –
Az Android-alkalmazás konfigurálása panel Aláírás kivonat szakaszában válassza a Fejlesztési aláírás kivonat létrehozása lehetőséget, és másolja a KeyTool parancsot a parancssorba.
- KeyTool.exe a Java Development Kit (JDK) részeként van telepítve. A KeyTool parancs végrehajtásához telepítenie kell az OpenSSL eszközt is. További információkért tekintse meg az Android dokumentációját a kulcsok generálására vonatkozóan.
Adja meg a KeyTool által létrehozott aláíráskivonatot .
Válassza a Konfigurálás lehetőséget, és mentse az Android konfigurációs panelen megjelenő MSAL-konfigurációt, hogy később beírhassa azt az alkalmazás konfigurálásakor.
Válassza a Kész lehetőséget.
A mintaalkalmazás konfigurálása
Az Android Studio projektpaneljén lépjen az app\src\main\res elemre.
Kattintson a jobb gombbal a res elemre, és válassza az Új>könyvtár lehetőséget. Adja meg
raw
az új könyvtárnevet, és válassza az OK gombot.Az app>src>main>res>raw fájljában lépjen a hívott JSON-fájlra
auth_config_single_account.json
, és illessze be a korábban mentett MSAL-konfigurációt.Az átirányítási URI alatt illessze be a következőt:
"account_mode" : "SINGLE",
A konfigurációs fájlnak a következő példához kell hasonlítania:
{ "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" } } ] }
Mivel ez az oktatóanyag csak azt mutatja be, hogyan konfigurálhat egy alkalmazást egyetlen fiók módban, tekintse meg az egy vagy több fiókos módot , és konfigurálja az alkalmazást további információkért.
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.
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:
- 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.
- 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.
További információ
Az erre a rövid útmutatóra vonatkozó további információért tekintse meg ezeket a szakaszokat.
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.java
metó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.java
felhaszná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.java
felhaszná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.java
loadAccount()
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 file
tá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.
Visszajelzés
https://aka.ms/ContentUserFeedback.
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ:Visszajelzés küldése és megtekintése a következőhöz: