Rychlý start: Přihlášení uživatelů a volání Microsoft Graphu z aplikace pro Android - Microsoft identity platform

Článek
06/14/2024

V tomto rychlém startu stáhnete a spustíte ukázku kódu, která předvádí, jak se aplikace pro Android může přihlásit uživatele a získat přístupový token pro volání rozhraní Microsoft Graph API.

Aplikace musí být reprezentovány objektem aplikace v Microsoft Entra ID, aby platforma Microsoft Identity Platform mohla vaší aplikaci poskytovat tokeny.

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Android Studio
Android 16 a novější

Jak ukázka funguje

Diagram znázorňující, jak funguje ukázková aplikace generovaná v tomto rychlém startu

Kód je uspořádaný do fragmentů, které ukazují, jak napsat jednu a více účtů aplikace MSAL. Soubory kódu jsou uspořádány takto:

Soubor	Demonstruje
MainActivity	Spravuje uživatelské rozhraní.
MSGraphRequestWrapper	Volá rozhraní Microsoft Graph API pomocí tokenu poskytovaného knihovnou MSAL.
MultipleAccountModeFragment	Inicializuje aplikaci s více účty, načte uživatelský účet a získá token pro volání rozhraní Microsoft Graph API.
SingleAccountModeFragment	Inicializuje aplikaci s jedním účtem, načte uživatelský účet a získá token pro volání rozhraní Microsoft Graph API.
res/auth_config_multiple_account.json	Konfigurační soubor s více účty
res/auth_config_single_account.json	Konfigurační soubor s jedním účtem
Gradle Scripts/build.grade (Module:app)	Tady jsou přidány závislosti knihovny MSAL.

Teď se na tyto soubory podíváme podrobněji a v každém z nich označíme kód specifický pro MSAL.

Získání ukázkové aplikace

Java: Stáhněte si kód.
Kotlin: Stáhněte si kód.

Registrace ukázkové aplikace

Tip

Postup v tomto článku se může mírně lišit v závislosti na portálu, od který začínáte.

Přihlaste se do Centra pro správu Microsoft Entra jako alespoň vývojář aplikací.
Pokud máte přístup k více tenantům, pomocí ikony Nastavení v horní nabídce přepněte na tenanta, ve kterém chcete aplikaci zaregistrovat z nabídky Adresáře a předplatná.
Přejděte k aplikacím> identit>Registrace aplikací.
Vyberte Nová registrace.
Zadejte název aplikace. Uživatelé vaší aplikace můžou vidět tento název a později ho můžete změnit.
U podporovaných typů účtů vyberte Účty v libovolném adresáři organizace (libovolný adresář Microsoft Entra – Víceklient) a osobní účty Microsoft (např. Skype, Xbox). Pokud chcete získat informace o různých typech účtů, vyberte možnost Nápověda pro výběr .
Vyberte Zaregistrovat.
V části Spravovat vyberte Možnost Přidat ověřování>pro Android platformy>.
Zadejte název balíčku projektu na základě výše staženého ukázkového typu.
- Ukázka v Javě – com.azuresamples.msalandroidapp
- Ukázka Kotlinu - com.azuresamples.msalandroidkotlinapp
V části Hash podpisu podokna Konfigurace aplikace pro Android vyberte Generování hodnoty hash vývojového podpisu. A zkopírujte příkaz KeyTool do příkazového řádku.
- KeyTool.exe se instaluje jako součást sady Java Development Kit (JDK). Musíte také nainstalovat nástroj OpenSSL ke spuštění příkazu KeyTool. Další informace najdete v dokumentaci k Androidu o generování klíče .
Zadejte hodnotu hash podpisu vygenerovanou nástrojem KeyTool.
Vyberte Konfigurovat a uložte konfiguraci MSAL, která se zobrazí v podokně konfigurace Androidu, abyste ji mohli zadat při pozdější konfiguraci aplikace.
Vyberte Hotovo.

Konfiguraci ukázkové aplikace

V podokně projektu Android Studia přejděte na app\src\main\res.
Klikněte pravým tlačítkem myši na možnost Res a zvolte Nový>adresář. Zadejte raw jako název nového adresáře a vyberte OK.
V souboru>src>main>res>raw přejděte do souboru JSON s názvem auth_config_single_account.json a vložte konfiguraci MSAL, kterou jste si uložili dříve.

Pod identifikátor URI přesměrování vložte:
```
  "account_mode" : "SINGLE",
```
Konfigurační soubor by měl vypadat podobně jako v tomto příkladu:
```
{
  "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"
      }
    }
  ]
}
```
Jak tento kurz ukazuje, jak nakonfigurovat aplikaci pouze v režimu jednoho účtu, podívejte se na režim jednoho nebo více účtů a konfiguraci aplikace , kde najdete další informace.

Spuštění ukázkové aplikace

V rozevíracím seznamu dostupných zařízení s Android Studio vyberte emulátor nebo fyzické zařízení a spusťte aplikaci.

Ukázková aplikace se spustí na obrazovce Režimu jednoho účtu. Ve výchozím nastavení je k dispozici výchozí obor user.read, který se používá při čtení vlastních dat profilu během volání rozhraní Microsoft Graph API. Ve výchozím nastavení je k dispozici adresa URL pro volání rozhraní Microsoft Graph API. Pokud chcete, můžete obě tyto možnosti změnit.

Snímek obrazovky ukázkové aplikace MSAL zobrazující jednoúčelové a více účtů

Pomocí nabídky aplikace můžete změnit režimy jednoho a více účtů.

V režimu jednoho účtu se přihlaste pomocí pracovního nebo domácího účtu:

Výběrem možnosti Získat data grafu interaktivně vyzvete uživatele k zadání přihlašovacích údajů. V dolní části obrazovky se zobrazí výstup volání rozhraní Microsoft Graph API.
Po přihlášení vyberte Získat data grafu bezobslužně , aby se volání rozhraní Microsoft Graph API bez výzvy uživatele k zadání přihlašovacích údajů znovu zobrazilo. V dolní části obrazovky se zobrazí výstup volání rozhraní Microsoft Graph API.

V režimu více účtů můžete stejný postup zopakovat. Kromě toho můžete odebrat přihlášený účet, který také odebere tokeny uložené v mezipaměti pro tento účet.

Další informace

Další informace o tomto rychlém startu najdete v následujících částech.

Přidání KNIHOVNY MSAL do aplikace

MSAL (com.microsoft.identity.client) je knihovna, která slouží k přihlašování uživatelů a vyžádání tokenů používaných pro přístup k rozhraní API chráněnému platformou Microsoft Identity Platform. Gradle 3.0+ nainstaluje knihovnu při přidání následujícího příkazu do gradle Scripts>build.gradle (modul: aplikace) v části Závislosti:

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

To dává Gradle pokyn ke stažení a sestavení MSAL z mavenu central.

Musíte také přidat odkazy na maven do části úložiště allprojects>settings.gradle (module: app) v rámci dependencyResolutionManagement:

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

Importy MSAL

Importy, které jsou relevantní pro knihovnu MSAL, jsou com.microsoft.identity.client.*. Uvidíte import com.microsoft.identity.client.PublicClientApplication; například, který obor názvů třídy PublicClientApplication představuje vaši veřejnou klientskou aplikaci.

SingleAccountModeFragment.java

Tento soubor ukazuje, jak vytvořit jednu aplikaci MSAL účtu a volat rozhraní Microsoft Graph API.

Jednoúčelové aplikace používají jenom jeden uživatel. Můžete mít například jenom jeden účet, pomocí kterého se přihlašujete k mapovací aplikaci.

Inicializace MSAL s jedním účtem

onCreateView() V SingleAccountModeFragment.javametodě se vytvoří jeden účet PublicClientApplication pomocí konfiguračních informací uložených auth_config_single_account.json v souboru. Takto inicializujete knihovnu MSAL pro použití v aplikaci MSAL s jedním účtem:

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

V SingleAccountModeFragment.javakódu pro přihlášení uživatele je v initializeUI()obslužné rutině signInButton kliknutí.

Před pokusem o získání tokenů zavolejte signIn() . signIn() chová se, jako by acquireToken() byl volána, což vede k interaktivní výzvě, aby se uživatel přihlásil.

Přihlášení uživatele je asynchronní operace. Zpětné volání se předá volání, které volá rozhraní Microsoft Graph API a aktualizuje uživatelské rozhraní, jakmile se uživatel přihlásí:

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

Odhlášení uživatele

V SingleAccountModeFragment.javakódu pro odhlášení uživatele je v initializeUI()obslužné rutině signOutButton kliknutí. Odhlášení uživatele je asynchronní operace. Odhlášení uživatele také vymaže mezipaměť tokenů pro tento účet. Jakmile se uživatelský účet odhlásí, vytvoří se zpětné volání, které aktualizuje uživatelské rozhraní:

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

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

Interaktivní nebo tiché získání tokenu

Pokud chcete uživateli prezentovat co nejmenší počet výzev, obvykle získáte token bezobslužně. Pokud dojde k chybě, zkuste token získat interaktivně. Při prvním volání signIn()aplikace funguje efektivně jako volání acquireToken(), který vyzve uživatele k zadání přihlašovacích údajů.

V některých situacích, kdy se uživateli může zobrazit výzva k výběru účtu, zadání přihlašovacích údajů nebo vyjádření souhlasu s oprávněními, která vaše aplikace požadovala, jsou:

Při prvním přihlášení uživatele k aplikaci
Pokud uživatel resetuje heslo, bude muset zadat svoje přihlašovací údaje.
Pokud je souhlas odvolán
Pokud vaše aplikace explicitně vyžaduje souhlas
Když aplikace žádá o přístup k prostředku poprvé
Pokud se vyžadují vícefaktorové ověřování nebo jiné zásady podmíněného přístupu

Kód, který získá token interaktivně, což je s uživatelským rozhraním, které bude zahrnovat uživatele, je v SingleAccountModeFragment.java, v initializeUI(), v obslužné rutině callGraphApiInteractiveButton kliknutí:

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

Pokud už je uživatel přihlášený, acquireTokenSilentAsync() umožňuje aplikacím bezobslužně vyžadovat tokeny, jak je znázorněno v initializeUI()obslužné rutině callGraphApiSilentButton kliknutí:

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

Načtení účtu

Kód pro načtení účtu je v SingleAccountModeFragment.java loadAccount(). Načtení účtu uživatele je asynchronní operace, takže zpětná volání, která se mají zpracovat, když se účet načte, změní nebo dojde k chybě, předá knihovně MSAL. Následující kód také zpracovává onAccountChanged(), ke kterému dochází při odebrání účtu, uživatel se změní na jiný účet atd.

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

Volání Microsoft Graphu

Když je uživatel přihlášený, volání Microsoft Graphu se provede prostřednictvím požadavku HTTP, který callGraphAPI() je definován v SingleAccountModeFragment.java. Tato funkce je obálka, která zjednodušuje ukázku tím, že provádí některé úlohy, jako je získání přístupového tokenu z authenticationResult volání a zabalení volání MSGraphRequestWrapper a zobrazení výsledků volání.

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

Toto je konfigurační soubor pro aplikaci MSAL, která používá jeden účet.

Vysvětlení těchto polí najdete v tématu Vysvětlení konfiguračního souboru MSAL pro Android.

Všimněte si přítomnosti "account_mode" : "SINGLE"aplikace, která tuto aplikaci nakonfiguruje tak, aby používala jeden účet.

"client_id" je předem nakonfigurovaný tak, aby používal registraci objektu aplikace, kterou microsoft udržuje. "redirect_uri"je předem nakonfigurovaný tak, aby používal podpisový klíč, který je součástí ukázky kódu.

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

Tento soubor ukazuje, jak vytvořit aplikaci MSAL s více účty a volat rozhraní Microsoft Graph API.

Příkladem aplikace s více účty je poštovní aplikace, která umožňuje pracovat s více uživatelskými účty, jako je pracovní účet a osobní účet.

Inicializace MSAL s více účty

V souboru je v onCreateView()objektu MultipleAccountModeFragment.java aplikace s více účty (IMultipleAccountPublicClientApplication) vytvořen pomocí konfiguračních informací uložených v :auth_config_multiple_account.json file

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

Vytvořený MultipleAccountPublicClientApplication objekt je uložen v členské proměnné třídy, aby bylo možné jej použít k interakci s knihovnou MSAL k získání tokenů a načtení a odebrání uživatelského účtu.

Načtení účtu

K výběru účtu, který se má použít pro operace MSAL, obvykle volá getAccounts() více aplikací účtů. Kód pro načtení účtu je v MultipleAccountModeFragment.java souboru , v loadAccounts(). Načtení účtu uživatele je asynchronní operace. Zpětné volání tedy zpracovává situace, kdy se účet načte, změní nebo dojde k chybě.

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

Interaktivní nebo tiché získání tokenu

Při prvním přihlášení k aplikaci
Pokud uživatel resetuje heslo, bude muset zadat svoje přihlašovací údaje.
Pokud je souhlas odvolán
Pokud vaše aplikace explicitně vyžaduje souhlas
Když aplikace žádá o přístup k prostředku poprvé
Pokud se vyžadují vícefaktorové ověřování nebo jiné zásady podmíněného přístupu

Více aplikací účtů by obvykle mělo interaktivně získávat tokeny, to znamená s uživatelským rozhraním, které zahrnuje uživatele s voláním acquireToken(). Kód pro interaktivní získání tokenu je v souboru initializeUI()v MultipleAccountModeFragment.java obslužné rutině callGraphApiInteractiveButton kliknutí:

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

Aplikace by neměly vyžadovat, aby se uživatel při každém vyžádání tokenu přihlásil. Pokud je uživatel již přihlášený, acquireTokenSilentAsync() umožňuje aplikacím požadovat tokeny bez výzvy uživatele, jak je znázorněno v MultipleAccountModeFragment.java souboru, vinitializeUI() obslužné rutině callGraphApiSilentButton kliknutí:

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

Odebrání účtu

Kód pro odebrání účtu a všechny tokeny uložené v mezipaměti pro tento účet jsou v MultipleAccountModeFragment.java souboru v initializeUI() obslužné rutině tlačítka pro odebrání účtu. Před odebráním účtu potřebujete objekt účtu, který získáte z metod MSAL jako getAccounts() a acquireToken(). Vzhledem k tomu, že odebrání účtu je asynchronní operace, onRemoved zadává se zpětná volání pro aktualizaci uživatelského rozhraní.

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

Toto je konfigurační soubor pro aplikaci MSAL, která používá více účtů.

Vysvětlení různých polí najdete v tématu Vysvětlení konfiguračního souboru MSAL pro Android.

Na rozdíl od konfiguračního souboru auth_config_single_account.json má "account_mode" : "MULTIPLE" tento konfigurační soubor místo "account_mode" : "SINGLE" toho, že se jedná o aplikaci s více účty.

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

Nápověda a podpora

Pokud potřebujete pomoc, chcete nahlásit problém nebo se chcete dozvědět o možnostech podpory, přečtěte si nápovědu a podporu pro vývojáře.

Další kroky

Přejděte k kurzu pro Android, ve kterém vytvoříte aplikaci pro Android, která získá přístupový token z platformy Microsoft Identity Platform a použije ji k volání rozhraní Microsoft Graph API.

Kurz: Přihlášení uživatelů a volání Microsoft Graphu z aplikace pro Android

Sdílet prostřednictvím

Požadavky

Jak ukázka funguje

Získání ukázkové aplikace

Registrace ukázkové aplikace

Konfiguraci ukázkové aplikace

Spuštění ukázkové aplikace

Další informace

Přidání KNIHOVNY MSAL do aplikace

Importy MSAL

SingleAccountModeFragment.java

Inicializace MSAL s jedním účtem

Odhlášení uživatele

Interaktivní nebo tiché získání tokenu

Načtení účtu

Volání Microsoft Graphu

auth_config_single_account.json

MultipleAccountModeFragment.java

Inicializace MSAL s více účty

Načtení účtu

Interaktivní nebo tiché získání tokenu

Odebrání účtu

auth_config_multiple_account.json

Nápověda a podpora

Další kroky

Váš názor

Další materiály