Szybki start: logowanie użytkowników i wywoływanie programu Microsoft Graph z poziomu aplikacji systemu Android
W tym przewodniku Szybki start pobierzesz i uruchomisz przykładowy kod, który pokazuje, jak aplikacja systemu Android może logować użytkowników i uzyskiwać token dostępu w celu wywołania interfejsu API programu Microsoft Graph.
Aplikacje muszą być reprezentowane przez obiekt aplikacji w identyfikatorze Entra firmy Microsoft, aby Platforma tożsamości Microsoft mógł udostępniać tokeny aplikacji.
Wymagania wstępne
- Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
- Android Studio
- Android 16+
Jak działa przykład
Kod jest podzielony na fragmenty, które pokazują, jak napisać pojedynczą i wiele kont aplikacji MSAL. Pliki kodu są zorganizowane w następujący sposób:
Plik | Demonstracje |
---|---|
MainActivity | Zarządza interfejsem użytkownika |
MSGraphRequestWrapper | Wywołuje interfejs API programu Microsoft Graph przy użyciu tokenu dostarczonego przez bibliotekę MSAL |
MultipleAccountModeFragment | Inicjuje aplikację z wieloma kontami, ładuje konto użytkownika i pobiera token w celu wywołania interfejsu API programu Microsoft Graph |
SingleAccountModeFragment | Inicjuje aplikację z pojedynczym kontem, ładuje konto użytkownika i pobiera token w celu wywołania interfejsu API programu Microsoft Graph |
res/auth_config_multiple_account.json | Plik konfiguracji wielu kont |
res/auth_config_single_account.json | Plik konfiguracji pojedynczego konta |
Gradle Scripts/build.grade (Module:app) | Zależności biblioteki MSAL są dodawane tutaj |
Teraz przyjrzymy się tym plikom bardziej szczegółowo i wywołamy kod specyficzny dla biblioteki MSAL w każdym z nich.
Pobieranie przykładowej aplikacji
- Java: pobierz kod.
- Kotlin: pobierz kod.
Rejestrowanie przykładowej aplikacji
Napiwek
Kroki opisane w tym artykule mogą się nieznacznie różnić w zależności od portalu, od którego zaczynasz.
Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako deweloper aplikacji.
Jeśli masz dostęp do wielu dzierżaw, użyj ikonyUstawienia w górnym menu, aby przełączyć się do dzierżawy, w której chcesz zarejestrować aplikację z menu Katalogi i subskrypcje.
Przejdź do aplikacji tożsamości>> Rejestracje aplikacji.
Wybierz opcjęNowa rejestracja.
Wprowadź nazwę aplikacji. Użytkownicy aplikacji mogą zobaczyć tę nazwę i możesz ją zmienić później.
W obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnym katalogu organizacyjnym (dowolny katalog Microsoft Entra — multitenant) i osobiste konta Microsoft (np. Skype, Xbox). Aby uzyskać informacje o różnych typach kont, wybierz opcję Pomoc dla mnie .
Wybierz pozycję Zarejestruj.
W obszarze Zarządzanie wybierz pozycję Uwierzytelnianie>Dodaj platformę>Android.
Wprowadź nazwę pakietu projektu na podstawie przykładowego typu pobranego powyżej.
- Przykład w języku Java —
com.azuresamples.msalandroidapp
- Przykład Kotlin —
com.azuresamples.msalandroidkotlinapp
- Przykład w języku Java —
W sekcji Skrót podpisu w okienku Konfigurowanie aplikacji systemu Android wybierz pozycję Generowanie skrótu sygnatury programistycznej i skopiuj polecenie KeyTool do wiersza polecenia.
- KeyTool.exe jest instalowany w ramach zestawu Java Development Kit (JDK). Należy również zainstalować narzędzie OpenSSL, aby wykonać polecenie KeyTool. Aby uzyskać więcej informacji, zobacz dokumentację systemu Android dotyczącą generowania klucza , aby uzyskać więcej informacji.
Wprowadź skrót sygnatury wygenerowany przez element KeyTool.
Wybierz pozycję Konfiguruj i zapisz konfigurację biblioteki MSAL wyświetlaną w okienku konfiguracji systemu Android, aby można było wprowadzić ją podczas konfigurowania aplikacji później.
Wybierz pozycję Gotowe.
Konfigurowanie przykładowej aplikacji
W okienku projektu programu Android Studio przejdź do pozycji app\src\main\res.
Kliknij prawym przyciskiem myszy pozycję res i wybierz polecenie Nowy>katalog. Wprowadź
raw
jako nazwę nowego katalogu i wybierz przycisk OK.W pliku>src>main>res>raw przejdź do pliku JSON o nazwie
auth_config_single_account.json
i wklej zapisaną wcześniej konfigurację biblioteki MSAL.Poniżej identyfikatora URI przekierowania wklej:
"account_mode" : "SINGLE",
Plik konfiguracji powinien wyglądać podobnie do tego przykładu:
{ "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" } } ] }
W tym samouczku pokazano tylko, jak skonfigurować aplikację w trybie pojedynczego konta, zobacz tryb pojedynczego konta i wiele kont oraz konfigurowanie aplikacji , aby uzyskać więcej informacji
Uruchamianie przykładowej aplikacji
Wybierz emulator lub urządzenie fizyczne z listy rozwijanej Dostępne urządzenia z programem Android Studio i uruchom aplikację.
Przykładowa aplikacja zostanie uruchomiona na ekranie Tryb 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:
- Wybierz pozycję Pobierz dane grafu interaktywnie , aby monitować użytkownika o podanie poświadczeń. Dane wyjściowe wywołania interfejsu API programu Microsoft Graph zostaną wyświetlone w dolnej części ekranu.
- Po zalogowaniu wybierz pozycję Pobierz dane grafu dyskretnie, aby wykonać wywołanie interfejsu API programu Microsoft Graph bez monitowania użytkownika o poświadczenia. 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.
Więcej informacji
Zapoznaj się z następującymi sekcjami, aby dowiedzieć się więcej na temat tego przewodnika Szybki start.
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:5.1.0'
implementation 'com.android.volley:volley:1.2.1'
...
}
Spowoduje to, że narzędzie Gradle pobierze i skompiluje bibliotekę MSAL z centralnej biblioteki maven.
Należy również dodać odwołania do narzędzia maven do części repozytoriów allprojects>w obszarze settings.gradle (Module: app) w obszarze dependencyResolutionManagement:
dependencyResolutionManagement {
...
maven
{
url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
}
...
}
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
, która reprezentuje publiczną aplikację kliencą.
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 biblioteki MSAL dla pojedynczego konta
W SingleAccountModeFragment.java
metodzie w onCreateView()
metodzie pojedyncze konto PublicClientApplication
jest tworzone przy użyciu informacji o konfiguracji przechowywanych auth_config_single_account.json
w pliku. 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
pliku kod logowania użytkownika znajduje się w initializeUI()
programie , w procedurze signInButton
obsługi kliknięć.
Wywołaj metodę signIn()
przed próbą uzyskania tokenów. signIn()
zachowuje się tak, acquireToken()
jakby jest wywoływany, co powoduje interakcyjny monit o zalogowanie się użytkownika.
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
pliku kod w celu wylogowania użytkownika znajduje się w initializeUI()
programie , w procedurze signOutButton
obsługi kliknięć. 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 pobrać token interaktywnie. Gdy aplikacja po raz pierwszy wywołuje signIn()
metodę , skutecznie działa jako wywołanie acquireToken()
metody , co spowoduje wyświetlenie monitu użytkownika 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 resetuje swoje hasło, musi wprowadzić swoje poświadczenia
- 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 interakcyjne uzyskanie tokenu, czyli interfejs użytkownika, który będzie obejmował użytkownika, znajduje się w SingleAccountModeFragment.java
pliku w programie w initializeUI()
programie , w procedurze callGraphApiInteractiveButton
obsługi kliknięć:
/**
* 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
pliku loadAccount()
. Ładowanie konta użytkownika jest operacją asynchroniczną, więc wywołania zwrotne do obsługi podczas ładowania, zmiany lub błędu konta jest przekazywany do biblioteki MSAL. Poniższy kod obsługuje również metodę onAccountChanged()
, która występuje po usunięciu konta, użytkownik zmieni się na inne konto 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 otoką, która upraszcza przykład, wykonując niektóre zadania, takie jak pobieranie tokenu dostępu z elementu authenticationResult
i pakowanie wywołania do narzędzia MSGraphRequestWrapper i wyświetlanie 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 Opis pliku konfiguracji biblioteki MSAL 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": "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
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.
Inicjowanie biblioteki MSAL dla wielu kont
MultipleAccountModeFragment.java
W pliku w onCreateView()
pliku w obiekcie jest tworzony obiekt aplikacji z wieloma kontami (IMultipleAccountPublicClientApplication
) przy użyciu informacji o konfiguracji przechowywanych w pliku 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 konta zwykle wywołuje metodę getAccounts()
, aby wybrać konto do użycia na potrzeby operacji biblioteki MSAL. Kod ładowania konta znajduje się w pliku w loadAccounts()
pliku MultipleAccountModeFragment.java
. Ładowanie konta użytkownika jest operacją asynchroniczną. Wywołanie zwrotne obsługuje sytuacje, gdy konto jest ładowane, zmienia się 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:
- Gdy nowi użytkownicy logują się do aplikacji po raz pierwszy.
- Jeśli użytkownik resetuje swoje hasło, musi wprowadzić swoje poświadczenia
- 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 kont powinno zwykle uzyskiwać tokeny interaktywnie, czyli za pomocą interfejsu użytkownika, który obejmuje 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 jest dostarczane w celu zaktualizowania 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 Opis pliku konfiguracji BIBLIOTEKi MSAL systemu Android.
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": "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"
}
}
]
}
Pomoc i obsługa techniczna
Jeśli potrzebujesz pomocy, chcesz zgłosić problem lub poznać opcje pomocy technicznej, zobacz Pomoc i obsługa techniczna dla deweloperów.
Następne kroki
Przejdź do samouczka systemu Android, w którym tworzysz aplikację systemu Android, która pobiera token dostępu z Platforma tożsamości Microsoft i używa jej do wywoływania interfejsu API programu Microsoft Graph.