Szybki start: logowanie użytkowników i wywoływanie interfejsu API programu Microsoft Graph z poziomu aplikacji dla systemu Android

W tym przewodniku szybkiego startu pobierzesz i uruchomisz przykładowy fragment kodu, który pokazuje, jak aplikacja systemu Android może logować się jako użytkownik i uzyskiwać token dostępu, aby wykonać wywołanie Microsoft Graph API.

Zobacz Jak działa przykład na ilustracji.

Aplikacje muszą być reprezentowane przez obiekt aplikacji w identyfikatorze Entra firmy Microsoft, aby platforma tożsamości firmy Microsoft mogła udostępniać tokeny aplikacji.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Android Studio
• Android 16+

Krok 1. Konfigurowanie aplikacji w witrynie Azure Portal

Aby przykładowy kod w tym przewodniku tworzenia działał, dodaj URI przekierowania zgodny z brokerem uwierzytelniania.

Krok 2. Pobieranie projektu

Uruchom projekt przy użyciu programu Android Studio.

Krok 3. Aplikacja jest skonfigurowana i gotowa do uruchomienia

Skonfigurowaliśmy projekt z wartościami właściwości aplikacji i wszystko jest gotowe do uruchomienia. Przykładowa aplikacja zostanie uruchomiona na ekranie trybu pojedynczego konta. Domyślny zakres, user.read, jest domyślnie udostępniany podczas odczytywania własnych danych profilu podczas wywołania interfejsu API programu Microsoft Graph. Adres URL wywołania interfejsu API programu Microsoft Graph jest domyślnie udostępniany. Możesz zmienić oba te elementy, jeśli chcesz.

Użyj menu aplikacji, aby zmienić tryby pojedynczego i wielu kont.

W trybie pojedynczego konta zaloguj się przy użyciu konta służbowego lub domowego:

1. Wybierz pozycję Pobierz dane grafu interaktywnie, aby wyświetlić monit o podanie poświadczeń użytkownika. Dane wyjściowe wywołania interfejsu API programu Microsoft Graph zostaną wyświetlone w dolnej części ekranu.
2. Po zalogowaniu wybierz pozycję Pobierz dane grafu w trybie dyskretnym, aby wykonać wywołanie interfejsu API programu Microsoft Graph bez ponownego proszenia użytkownika o podanie poświadczeń. Dane wyjściowe wywołania interfejsu API programu Microsoft Graph zostaną wyświetlone w dolnej części ekranu.

W trybie wielu kont można powtórzyć te same kroki. Ponadto możesz usunąć konto zalogowane, co spowoduje również usunięcie buforowanych tokenów dla tego konta.

Jak działa przykład

Kod jest podzielony na fragmenty, które pokazują, jak napisać aplikację MSAL dla jednego konta oraz dla wielu kont. Pliki kodu są zorganizowane w następujący sposób:

Teraz przyjrzymy się tym plikom bardziej szczegółowo i wywołamy kod specyficzny dla biblioteki MSAL w każdym z nich.

Dodawanie biblioteki MSAL do aplikacji

BIBLIOTEKA MSAL (com.microsoft.identity.client) to biblioteka używana do logowania użytkowników i żądania tokenów używanych do uzyskiwania dostępu do interfejsu API chronionego przez Platforma tożsamości Microsoft. Program Gradle 3.0 lub nowszy instaluje bibliotekę podczas dodawania następujących elementów do pliku Gradle Scripts>build.gradle (Module: app) w obszarze Zależności:

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

Spowoduje to, że narzędzie Gradle pobierze i skompiluje bibliotekę MSAL z centralnego repozytorium Maven.

Należy również dodać odwołania do narzędzia maven do części repozytoriów allprojects>w pliku build.gradle (Module: app) w następujący sposób:

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

Importowanie biblioteki MSAL

Importy istotne dla biblioteki MSAL to com.microsoft.identity.client.*. Na przykład zobaczysz import > com.microsoft.identity.client.PublicClientApplication;, która jest przestrzenią nazw klasy PublicClientApplication, a klasa ta reprezentuje publiczną aplikację kliencką.

SingleAccountModeFragment.java

Ten plik przedstawia sposób tworzenia pojedynczego konta aplikacji MSAL i wywoływania interfejsu API programu Microsoft Graph.

Aplikacje z jednym kontem są używane tylko przez jednego użytkownika. Na przykład możesz mieć tylko jedno konto, za pomocą którego logujesz się do aplikacji mapowania.

Inicjowanie MSAL w kontekście pojedynczego konta

W auth_config_single_account.json w onCreateView() tworzone jest jedno konto PublicClientApplication przy użyciu informacji o konfiguracji przechowywanych w pliku auth_config_single_account.json. W ten sposób zainicjujesz bibliotekę MSAL do użycia w aplikacji MSAL z jednym kontem:

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

Logowanie użytkownika

W SingleAccountModeFragment.java, kod logowania użytkownika znajduje się w initializeUI(), w procedurze obsługi kliknięć signInButton.

Zadzwoń na signIn() przed próbą uzyskania tokenów. signIn() zachowuje się tak, jakby był wywoływany acquireToken(), co powoduje monit interaktywny do zalogowania się.

Logowanie użytkownika jest operacją asynchroniczną. Przekazywanie wywołania zwrotnego powoduje wywołanie interfejsu API programu Microsoft Graph i zaktualizowanie interfejsu użytkownika po zalogowaniu się użytkownika:

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

Wylogowywanie użytkownika

W SingleAccountModeFragment.java znajduje się kod wylogowania użytkownika, jest w initializeUI(), w obsłudze kliknięć signOutButton. Wylogowywanie użytkownika jest operacją asynchroniczną. Wylogowanie użytkownika umożliwia również wyczyszczenie pamięci podręcznej tokenu dla tego konta. Wywołanie zwrotne jest tworzone w celu zaktualizowania interfejsu użytkownika po wylogowaniu konta użytkownika:

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

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

Interakcyjne lub dyskretne pobieranie tokenu

Aby przedstawić użytkownikowi najmniejszą liczbę monitów, zazwyczaj token będzie uzyskiwany w trybie dyskretnym. Następnie, jeśli wystąpi błąd, spróbuj przejść do tokenu interaktywnie. Gdy aplikacja po raz pierwszy wywołuje signIn(), działa to skutecznie jako wywołanie acquireToken(), co spowoduje, że użytkownik zostanie poproszony o podanie poświadczeń.

Niektóre sytuacje, w których użytkownik może zostać poproszony o wybranie swojego konta, wprowadzenie poświadczeń lub wyrażenie zgody na żądane uprawnienia aplikacji:

• Przy pierwszym zalogowaniu się użytkownika do aplikacji
• Jeśli użytkownik zresetuje swoje hasło, będzie musiał wprowadzić swoje poświadczenia do systemu.
• Jeśli zgoda zostanie odwołana
• Jeśli aplikacja jawnie wymaga zgody
• Gdy aplikacja żąda dostępu do zasobu po raz pierwszy
• Gdy wymagane są uwierzytelnianie wieloskładnikowe lub inne zasady dostępu warunkowego

Kod umożliwiający interaktywne uzyskanie tokenu z interfejsem użytkownika, który angażuje użytkownika, znajduje się w SingleAccountModeFragment.java, w initializeUI(), w procedurze obsługi kliknięć callGraphApiInteractiveButton.

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

Jeśli użytkownik już się zalogował, acquireTokenSilentAsync() umożliwia aplikacjom żądanie tokenów dyskretnie, jak pokazano w >initializeUI()programie , w procedurze callGraphApiSilentButton obsługi kliknięć:

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

Ładowanie konta

Kod ładowania konta znajduje się w SingleAccountModeFragment.java w loadAccount(). Ładowanie konta użytkownika jest operacją asynchroniczną, więc wywołania zwrotne do obsługi w przypadku załadowania, zmiany czy wystąpienia błędu konta są przekazywane do biblioteki MSAL. Poniższy kod obsługuje również onAccountChanged(), która występuje, gdy konto zostanie usunięte, użytkownik zmieni konto na inne itd.

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

Wywoływanie programu Microsoft Graph

Po zalogowaniu użytkownika wywołanie programu Microsoft Graph jest wykonywane za pośrednictwem żądania callGraphAPI() HTTP zdefiniowanego w pliku SingleAccountModeFragment.java. Ta funkcja jest osłoną, która upraszcza przykład, wykonując zadania, takie jak pobieranie tokenu dostępu z elementu authenticationResult, przygotowywanie wywołania za pomocą MSGraphRequestWrapper i zaprezentowanie wyników wywołania.

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

Jest to plik konfiguracji aplikacji MSAL, która używa pojedynczego konta.

Aby uzyskać wyjaśnienie tych pól, zobacz Zrozumienie pliku konfiguracyjnego MSAL dla systemu Android.

Zwróć uwagę na obecność elementu "account_mode" : "SINGLE", który konfiguruje tę aplikację do korzystania z pojedynczego konta.

"client_id" Program jest wstępnie skonfigurowany do używania rejestracji obiektu aplikacji, którą utrzymuje firma Microsoft. "redirect_uri"jest wstępnie skonfigurowany do używania klucza podpisywania dostarczonego z przykładowym kodem.

{
  "client_id" : "00001111-aaaa-2222-bbbb-3333cccc4444",
  "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

Ten plik pokazuje, jak utworzyć aplikację MSAL dla wielu kont i wywołać interfejs API programu Microsoft Graph.

Przykładem wielu aplikacji kont jest aplikacja poczty, która umożliwia pracę z wieloma kontami użytkowników, takimi jak konto służbowe i konto osobiste.

Inicjalizacja MSAL dla wielu kont

MultipleAccountModeFragment.java W pliku onCreateView() tworzony jest obiekt aplikacji z wieloma kontami (IMultipleAccountPublicClientApplication) przy użyciu informacji o konfiguracji przechowywanych w 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) {
                ...
            }
        });

Utworzony MultipleAccountPublicClientApplication obiekt jest przechowywany w zmiennej składowej klasy, dzięki czemu może służyć do interakcji z biblioteką MSAL w celu uzyskania tokenów i załadowania i usunięcia konta użytkownika.

Ładowanie konta

Wiele aplikacji umożliwiających obsługę kont zwykle wywołuje getAccounts(), aby wybrać konto do użycia do operacji w ramach MSAL. Kod do ładowania konta znajduje się w pliku MultipleAccountModeFragment.java, w loadAccounts(). Ładowanie konta użytkownika jest operacją asynchroniczną. Wywołanie zwrotne obsługuje sytuacje, gdy konto zostaje załadowane, ulega zmianie lub występuje błąd.

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

Interakcyjne lub dyskretne pobieranie tokenu

Niektóre sytuacje, w których użytkownik może zostać poproszony o wybranie swojego konta, wprowadzenie poświadczeń lub wyrażenie zgody na żądane uprawnienia aplikacji:

• Przy pierwszym logowaniu użytkowników do aplikacji
• Jeśli użytkownik zresetuje swoje hasło, będzie musiał wprowadzić swoje poświadczenia do systemu.
• Jeśli zgoda zostanie odwołana
• Jeśli aplikacja jawnie wymaga zgody
• Gdy aplikacja żąda dostępu do zasobu po raz pierwszy
• Gdy wymagane są uwierzytelnianie wieloskładnikowe lub inne zasady dostępu warunkowego

Wiele aplikacji do zarządzania kontami powinno zwykle uzyskiwać tokeny interaktywnie, czyli za pomocą interfejsu użytkownika angażującego użytkownika, z wywołaniem metody acquireToken(). Kod umożliwiający interakcyjne pobranie tokenu MultipleAccountModeFragment.java znajduje się w pliku w pliku w initializeUI> ()programie , w procedurze callGraphApiInteractiveButton obsługi kliknięć:

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

Aplikacje nie powinny wymagać od użytkownika logowania za każdym razem, gdy żądają tokenu. Jeśli użytkownik już się zalogował, acquireTokenSilentAsync() umożliwia aplikacjom żądanie tokenów bez monitowania użytkownika, jak pokazano w MultipleAccountModeFragment.java pliku, winitializeUI()callGraphApiSilentButton programie obsługi kliknięć:

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

Usuwanie konta

Kod służący do usuwania konta i wszystkich buforowanych tokenów dla konta znajduje się w MultipleAccountModeFragment.java pliku w initializeUI() programie obsługi dla przycisku usuń konto. Aby można było usunąć konto, potrzebny jest obiekt konta, który można uzyskać z metod MSAL, takich jak getAccounts() i acquireToken(). Ponieważ usunięcie konta jest operacją asynchroniczną, onRemoved wywołanie zwrotne zapewnia aktualizację interfejsu użytkownika.

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

Jest to plik konfiguracji aplikacji MSAL, która używa wielu kont.

Aby uzyskać wyjaśnienie różnych pól, zobacz Zrozumienie pliku konfiguracji systemu Android MSAL.

W przeciwieństwie do pliku konfiguracji auth_config_single_account.json ten plik konfiguracji ma "account_mode" : "MULTIPLE" zamiast"account_mode" : "SINGLE", ponieważ jest to wiele aplikacji kont.

"client_id" Program jest wstępnie skonfigurowany do używania rejestracji obiektu aplikacji, którą utrzymuje firma Microsoft. "redirect_uri"jest wstępnie skonfigurowany do używania klucza podpisywania dostarczonego z przykładowym kodem.

{
  "client_id" : "00001111-aaaa-2222-bbbb-3333cccc4444",
  "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"
      }
    }
  ]
}

Pomoc i wsparcie

Jeśli potrzebujesz pomocy, chcesz zgłosić problem lub poznać opcje pomocy technicznej, zobacz Pomoc i obsługa techniczna dla deweloperów.

Dalsze kroki

Przejdź do samouczka systemu Android, w którym tworzysz aplikację dla systemu Android, która pobiera token dostępu z platformy tożsamości firmy Microsoft i używa jej do wywoływania interfejsu API programu Microsoft Graph.