Краткое руководство. Вход пользователей и вызов Microsoft Graph из приложения Android
Из этого краткого руководства вы узнаете, как скачать и выполнить пример кода. В примере кода показано, как в приложении Android реализовать вход пользователей и получение маркера доступа для вызова API Microsoft Graph.
Приложения должны быть представлены объектом приложения в идентификаторе Microsoft Entra, чтобы платформа удостоверений Майкрософт могли предоставлять маркеры приложению.
Необходимые компоненты
- Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
- Android Studio
- Android 16+
Как работает этот пример
Код разделен на фрагменты, демонстрирующие, как записывать приложение MSAL для одной и нескольких учетных записей. Файлы кода организованы следующим образом:
| Файлы | Что демонстрирует |
|---|---|
| MainActivity | Управляет пользовательским интерфейсом |
| MSGraphRequestWrapper | Вызывает API Microsoft Graph, используя токен, предоставленный MSAL |
| MultipleAccountModeFragment | Инициализирует приложение с несколькими учетными записями, загружает учетную запись пользователя и получает токен для вызова API Microsoft Graph |
| SingleAccountModeFragment | Инициализирует приложение с одной учетной записью, загружает учетную запись пользователя и получает токен для вызова API Microsoft Graph |
| res/auth_config_multiple_account.json | Файл конфигурации нескольких учетных записей |
| res/auth_config_single_account.json | Файл конфигурации одной учетной записи |
| Скрипты Gradle/build.grade (модуль: app) | Здесь добавляются зависимости библиотеки MSAL |
Теперь мы рассмотрим эти файлы подробнее и вызовем код, относящийся к MSAL, в каждом из них
Получение примера приложения
- Java: скачайте код.
- Kotlin: скачайте код.
Регистрация примера приложения
Совет
Действия, описанные в этой статье, могут немного отличаться на портале, с который вы начинаете работу.
Войдите в Центр администрирования Microsoft Entra как минимум разработчик приложений.
Если у вас есть доступ к нескольким клиентам, используйте значок
"Параметры" в верхнем меню, чтобы переключиться на клиент, в котором вы хотите зарегистрировать приложение из меню каталогов и подписок.Перейдите к приложениям> удостоверений>Регистрация приложений.
Выберите Создать регистрацию.
Введите значение Name (Имя) для приложения. Пользователи приложения могут видеть это имя. Вы можете изменить его позже.
Для поддерживаемых типов учетных записей выберите учетные записи в любом каталоге организации (любой каталог Microsoft Entra — Multitenant) и личных учетных записей Майкрософт (например, Skype, Xbox). Для получения сведений о различных типах учетных записей выберите параметр "Справка ".
Выберите Зарегистрировать.
В разделе Управление выберите Проверка подлинности>Добавить платформу>Android.
Введите имя пакета проекта в зависимости от типа, скачанного выше.
- Пример Java —
com.azuresamples.msalandroidapp - Пример Kotlin —
com.azuresamples.msalandroidkotlinapp
- Пример Java —
В разделе хэша подписи в области "Настройка приложения Android" выберите "Создать хэш подписи разработки" и скопируйте команду KeyTool в командную строку.
- KeyTool. exe устанавливается как часть пакета средств разработки Java (JDK). Необходимо также установить средство OpenSSL для выполнения команды KeyTool. Дополнительные сведения см . в документации по Android по созданию ключа для получения дополнительных сведений.
Введите хэш подписи, созданный с помощью KeyTool.
Выберите "Настроить и сохранить конфигурацию MSAL", которая отображается в области конфигурации Android, чтобы можно было ввести ее при последующей настройке приложения.
Нажмите кнопку Готово.
Настройка примера приложения
На панели проекта Android Studio перейдите к app\src\main\res.
Щелкните правой кнопкой мыши res и выберите New (Создать) >Directory (Каталог). Введите
rawимя нового каталога и нажмите кнопку "ОК".В приложении>src>main>res>raw перейдите в JSON-файл с именем
auth_config_single_account.jsonи вставьте сохраненную ранее конфигурацию MSAL.Поместите следующие данные под URI перенаправления:
"account_mode" : "SINGLE",Теперь файл конфигурации должен выглядеть примерно так:
{ "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" } } ] }Как показано только в этом руководстве, как настроить приложение в режиме одной учетной записи, см . раздел "Один и несколько учетных записей " и настройка приложения для получения дополнительных сведений
Запуск примера приложения
Выберите эмулятор или физическое устройство из раскрывающегося списка доступных устройств Android Studio и запустите приложение.
Пример приложения запускается на экране Single Account Mode (Режим единой учетной записи). Область по умолчанию, user.read, предоставляется по умолчанию и используется при чтении данных собственного профиля во время вызова API Microsoft Graph. URL-адрес для вызова Microsoft Graph API предоставляется по умолчанию. При необходимости их можно изменить.
Используйте меню приложения для переключения между режимами одной и нескольких учетных записей.
В режиме одной учетной записи войдите с помощью рабочей или домашней учетной записи:
- Выберите Get graph data interactively (Получить данные графов в интерактивном режиме ), чтобы запросить у пользователя учетные данные. Вы увидите выходные данные вызова API Microsoft Graph в нижней части экрана.
- После входа в систему выберите Get graph data silently (Получить данные графов без уведомления), чтобы вызвать Microsoft Graph API, не запрашивая у пользователя учетные данные снова. Вы увидите выходные данные вызова API Microsoft Graph в нижней части экрана.
В режиме нескольких учетных записей можно повторить те же действия. Кроме того, можно удалить учетную запись для входа. При этом кэшированные токены для этой учетной записи также удаляются.
Дополнительные сведения
Дополнительные сведения о кратком руководстве содержатся в этих разделах.
Добавление MSAL в приложение
MSAL (com.microsoft.identity.client) — это библиотека, используемая для выполнения входа пользователей и запросов маркеров, которые нужны для доступа к API, защищенному платформой удостоверений Майкрософт. Gradle 3.0+ устанавливает библиотеку при добавлении в файл Скрипты Gradle>build.gradle (модуль: app) в разделе Зависимости следующего фрагмента кода:
dependencies {
...
implementation 'com.microsoft.identity.client:msal:5.1.0'
implementation 'com.android.volley:volley:1.2.1'
...
}
Он указывает Gradle загрузить и создать MSAL из Maven Central.
Также необходимо добавить ссылки на maven в часть репозиториев allprojects>в разделе settings.gradle (module: app) в разделе dependencyResolutionManagement:
dependencyResolutionManagement {
...
maven
{
url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
}
...
}
Операции импорта MSAL
Операции импорта, относящиеся к библиотеке MSAL: com.microsoft.identity.client.*. Например, вы увидите import com.microsoft.identity.client.PublicClientApplication;, что является пространством имен для класса PublicClientApplication, который представляет общедоступное клиентское приложение.
SingleAccountModeFragment.java
В этом файле показано, как создать приложение MSAL для одной учетной записи и вызвать API Microsoft Graph.
Приложения с одной учетной записью используются только одним пользователем. Например, у вас может быть только одна учетная запись для входа в приложение сопоставления.
Инициализация MSAL одной учетной записи
onCreateView() В SingleAccountModeFragment.javaметоде создается отдельная учетная запись PublicClientApplication с помощью сведений конфигурации, хранящихся в auth_config_single_account.json файле. Таким образом вы инициализируете библиотеку MSAL для использования в приложении MSAL с одной учетной записью:
...
// 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);
}
});
Вход пользователя
В файле SingleAccountModeFragment.java код для входа пользователя находится в initializeUI() в обработчике щелчков signInButton.
Прежде чем пытаться получить токены, вызовите signIn(). signIn() ведет себя так, как будто вызывается acquireToken(), в результате чего пользователь получает интерактивный запрос на вход.
Вход пользователя является асинхронной операцией. Передается метод для обратного вызова, который вызывает API Microsoft Graph и обновляет пользовательский интерфейс после входа пользователя:
mSingleAccountApp.signIn(getActivity(), null, getScopes(), getAuthInteractiveCallback());
Выход пользователя
В файле SingleAccountModeFragment.java код для выхода пользователя находится в initializeUI() в обработчике щелчков signOutButton. Выход пользователя является асинхронной операцией. При выходе пользователя также очищается кеш токена для этой учетной записи. Для обновления пользовательского интерфейса после выхода из учетной записи пользователя создается обратный вызов:
mSingleAccountApp.signOut(new ISingleAccountPublicClientApplication.SignOutCallback() {
@Override
public void onSignOut() {
updateUI(null);
performOperationOnSignOut();
}
@Override
public void onError(@NonNull MsalException exception) {
displayError(exception);
}
});
Получение токена в интерактивном режиме или автоматически
Чтобы пользователь получил минимальное количество запросов, токен обычно получается автоматически. Затем, если возникла ошибка, попытайтесь получить маркер в интерактивном режиме. Когда приложение вызывает signIn() впервые, оно фактически действует как вызов acquireToken(), который запрашивает учетные данные пользователя.
Ниже представлены некоторые ситуации, когда пользователю может быть предложено выбрать учетную запись, ввести учетные данные или дать согласие на разрешения, запрошенные вашим приложением:
- Первый вход пользователя в приложение.
- Если пользователь сбрасывает пароль, то потребуется вводить свои учетные данные.
- Если отменяется согласие.
- Приложение явно требует согласия.
- Когда ваше приложение впервые запрашивает доступ к ресурсу.
- Когда требуются политики условного доступа или MFA.
Код для интерактивного получения токена (то есть с помощью пользовательского интерфейса) находится в файле SingleAccountModeFragment.java в initializeUI() в обработчике щелчков 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());
Если пользователь уже выполнил вход, acquireTokenSilentAsync() позволяет приложениям запрашивать маркеры автоматически, как показано в initializeUI(), в обработчике щелчков callGraphApiSilentButton:
/**
* Once you've signed the user in,
* you can perform acquireTokenSilent to obtain resources without interrupting the user.
**/
mSingleAccountApp.acquireTokenSilentAsync(getScopes(), AUTHORITY, getAuthSilentCallback());
Загрузка учетной записи
Код для загрузки учетной записи находится в файле SingleAccountModeFragment.java в loadAccount(). Загрузка учетной записи пользователя является асинхронной операцией, поэтому обратные вызовы для обработки при загрузке учетной записи, изменении или возникновении ошибки передаются в MSAL. Следующий код также обрабатывает onAccountChanged(), что происходит при удалении учетной записи, переходе пользователя на другую учетную запись и т. д.
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);
}
});
Вызов Microsoft Graph
Когда пользователь выполнил вход, вызов Microsoft Graph выполняется через HTTP-запрос с помощью callGraphAPI(), определенного в файле SingleAccountModeFragment.java. Эта функция представляет собой программу-оболочку, которая упрощает пример, выполняя некоторые задачи, такие как получение маркера доступа из authenticationResult, упаковка вызова MSGraphRequestWrapper и отображение результатов вызова.
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
Это файл конфигурации для приложения MSAL, использующего одну учетную запись.
Описание этих полей см. в статье Understand the Android MSAL configuration file (Файл конфигурации библиотеки проверки подлинности Microsoft для Android (MSAL)).
Обратите внимание на присутствие "account_mode" : "SINGLE", который настраивает это приложение для использования одной учетной записи.
Параметр "client_id" предварительно настроен для использования регистрации объекта приложения, которую обслуживает корпорация Майкрософт.
Параметр "redirect_uri" предварительно настроен для использования ключа подписывания, предоставленного в примере кода.
{
"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
В этом файле показано, как создать приложение MSAL с несколькими учетными записями и вызвать API Microsoft Graph.
Примером приложения с несколькими учетными записями является почтовое приложение, которое позволяет работать с несколькими учетными записями пользователей, такими как рабочая и личная учетная запись.
Инициализация MSAL нескольких учетных записей
В файле MultipleAccountModeFragment.java в onCreateView() объект приложения с несколькими учетными записями (IMultipleAccountPublicClientApplication) создается с использованием сведений о конфигурации, хранящихся в 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) {
...
}
});
Созданный объект MultipleAccountPublicClientApplication хранится в переменной члена класса, чтобы его можно было использовать для взаимодействия с библиотекой MSAL для получения токенов, загрузки и удаления учетной записи пользователя.
Загрузка учетной записи
Приложения с несколькими учетными записями обычно вызывают getAccounts(), чтобы выбрать учетную запись для использования в операциях MSAL. Код для загрузки учетной записи находится в файле MultipleAccountModeFragment.java в loadAccounts(). Загрузка учетной записи пользователя является асинхронной операцией. Поэтому обратный вызов обрабатывает ситуации, когда учетная запись загружается, изменяется или возникает ошибка.
/**
* 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);
}
});
}
Получение токена в интерактивном режиме или автоматически
Ниже представлены некоторые ситуации, когда пользователю может быть предложено выбрать учетную запись, ввести учетные данные или дать согласие на разрешения, запрошенные вашим приложением:
- первый вход пользователей в приложение;
- Если пользователь сбрасывает пароль, то потребуется вводить свои учетные данные.
- Если отменяется согласие.
- Приложение явно требует согласия.
- Когда ваше приложение впервые запрашивает доступ к ресурсу.
- Когда требуются политики условного доступа или MFA.
Приложения с несколькими учетными записями обычно должны получать токены в интерактивном режиме, то есть в пользовательском интерфейсе, с вызовом acquireToken(). Код для интерактивного получения токена находится в файле MultipleAccountModeFragment.java в initializeUI() в обработчике щелчков callGraphApiInteractiveButton:
/**
* 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());
Приложения не требуют, чтобы пользователи выполняли вход каждый раз при запросе токена. Если пользователь уже выполнил вход, acquireTokenSilentAsync() позволяет приложениям запрашивать токены без запроса к пользователю, как показано в файле MultipleAccountModeFragment.java в initializeUI() в обработчике щелчков callGraphApiSilentButton:
/**
* 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());
Удаление учетной записи
Код для удаления учетной записи и всех кэшированных токенов для учетной записи находится в файле MultipleAccountModeFragment.java в initializeUI() в обработчике кнопки удаления учетной записи. Прежде чем вы сможете удалить учетную запись, вам нужен объект учетной записи, который вы получаете из методов MSAL, таких как getAccounts() и acquireToken(). Так как удаление учетной записи является асинхронной операцией, обратный вызов onRemoved предоставляется для обновления пользовательского интерфейса.
/**
* 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
Это файл конфигурации для приложения MSAL, которое использует несколько учетных записей.
Описание различных полей см. в статье Understand the Android MSAL configuration file (Файл конфигурации библиотеки проверки подлинности Microsoft для Android (MSAL)).
В отличие от файла конфигурации auth_config_single_account.json, в этом файле конфигурации указано "account_mode" : "MULTIPLE" вместо "account_mode" : "SINGLE", так как это приложение с несколькими учетными записями.
Параметр "client_id" предварительно настроен для использования регистрации объекта приложения, которую обслуживает корпорация Майкрософт.
Параметр "redirect_uri" предварительно настроен для использования ключа подписывания, предоставленного в примере кода.
{
"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"
}
}
]
}
Справка и поддержка
Если вам нужна помощь, если вы хотите сообщить о проблеме или узнать о доступных вариантах поддержки, воспользуйтесь статьей Возможности получения поддержки и справки для разработчиков.
Следующие шаги
Перейдите к учебнику по Android, с помощью которого вы создадите приложение Android, получающее маркер доступа от платформы удостоверений Майкрософт и использующее его для вызова API Microsoft Graph.