Краткое руководство. Вход пользователей и вызов API Microsoft Graph из мобильного приложения

Из этого краткого руководства вы узнаете, как скачать и выполнить пример кода. В примере кода показано, как в приложении Android реализовать вход пользователей и получение маркера доступа для вызова API Microsoft Graph.

Иллюстрацию см. в разделе Как работает этот пример.

Чтобы приложение получало маркеры от платформы удостоверений Майкрософт, оно должно быть представлено объектом приложения в Azure Active Directory.

Предварительные требования

Шаг 1. Получение примера приложения

Скачайте код.

Шаг 2. Запуск примера приложения

Выберите эмулятор или физическое устройство из раскрывающегося списка доступных устройств Android Studio и запустите приложение.

Пример приложения запускается на экране Single Account Mode (Режим единой учетной записи). Область по умолчанию, user.read, предоставляется по умолчанию и используется при чтении данных собственного профиля во время вызова API Microsoft Graph. URL-адрес для вызова Microsoft Graph API предоставляется по умолчанию. При необходимости их можно изменить.

Пример приложения MSAL с использованием одной и нескольких учетных записей

Используйте меню приложения для переключения между режимами одной и нескольких учетных записей.

В режиме одной учетной записи войдите с помощью рабочей или домашней учетной записи:

  1. Выберите Get graph data interactively (Получить данные графов в интерактивном режиме), чтобы запросить у пользователя учетные данные. Вы увидите выходные данные вызова API Microsoft Graph в нижней части экрана.
  2. После входа в систему выберите Get graph data silently (Получить данные графов без уведомления), чтобы вызвать Microsoft Graph API, не запрашивая у пользователя учетные данные снова. Вы увидите выходные данные вызова API Microsoft Graph в нижней части экрана.

В режиме нескольких учетных записей можно повторить те же действия. Кроме того, можно удалить учетную запись для входа. При этом кэшированные токены для этой учетной записи также удаляются.

Как работает этот пример

Снимок экрана примера приложения

Код разделен на фрагменты, демонстрирующие, как записывать приложение 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, в каждом из них

Добавление MSAL в приложение

MSAL (com.microsoft.identity.client) — это библиотека, используемая для выполнения входа пользователей и запросов маркеров, которые нужны для доступа к API, защищенному платформой удостоверений Майкрософт. Gradle 3.0+ устанавливает библиотеку при добавлении в файл Скрипты Gradle>build.gradle (модуль: app) в разделе Зависимости следующего фрагмента кода:

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

Он указывает Gradle загрузить и создать MSAL из Maven Central.

Также необходимо добавить ссылки на Maven в раздел allprojects>repositories в build.gradle (Module: app) , как показано ниже.

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

Операции импорта MSAL

Операции импорта, относящиеся к библиотеке MSAL: com.microsoft.identity.client.*. Например, вы увидите import com.microsoft.identity.client.PublicClientApplication;, что является пространством имен для класса PublicClientApplication, который представляет общедоступное клиентское приложение.

SingleAccountModeFragment.java

В этом файле показано, как создать приложение MSAL для одной учетной записи и вызвать API Microsoft Graph.

Приложения с одной учетной записью используются только одним пользователем. Например, у вас может быть только одна учетная запись для входа в приложение сопоставления.

Инициализация MSAL одной учетной записи

В файле auth_config_single_account.json в onCreateView() создается одна учетная запись 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" : "0984a7b6-bc13-4141-8b0d-8f767e136bb7",
  "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

В этом файле показано, как создать приложение 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" : "0984a7b6-bc13-4141-8b0d-8f767e136bb7",
  "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"
      }
    }
  ]
}

Справка и поддержка

Если вам нужна помощь, если вы хотите сообщить о проблеме или узнать о доступных вариантах поддержки, воспользуйтесь статьей Возможности получения поддержки и справки для разработчиков.

Дальнейшие действия

Перейдите к учебнику по Android, с помощью которого вы создадите приложение Android, получающее маркер доступа от платформы удостоверений Майкрософт и использующее его для вызова API Microsoft Graph.

Из этого краткого руководства вы узнаете, как скачать и выполнить пример кода. В примере кода показано, как в нативном приложении iOS или macOS реализовать вход пользователей и получение маркера доступа для вызова API Microsoft Graph.

Это краткое руководство распространяется на приложения iOS и macOS. Некоторые действия нужно выполнять только для приложений iOS. Для таких действий будут добавлены соответствующие указания.

Предварительные требования

  • Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.
  • XCode 10 или более поздней версии
  • iOS 10 или более поздней версии
  • macOS 10.12+

Как работает этот пример

Схема работы приложения, создаваемого в этом кратком руководстве

Регистрация и скачивание приложения, используемого в этом кратком руководстве

У вас есть два варианта запуска приложения, используемого в этом кратком руководстве:

Вариант 1. Регистрация и автоматическая настройка приложения, а затем скачивание примера кода.

Шаг 1. Регистрация приложения

Регистрация приложения:

  1. Откройте страницу регистрации приложений на портале Azure и приступите к работе.
  2. Введите имя приложения и нажмите кнопку Зарегистрировать.
  3. Следуйте инструкциям, чтобы быстро скачать и автоматически настроить новое приложение.

Вариант 2. Регистрация и настройка приложения и примера кода вручную

Шаг 1. Регистрация приложения

Чтобы зарегистрировать приложение и добавить сведения о его регистрации в решение вручную, сделайте следующее:

  1. Войдите на портал Azure.
  2. Если у вас есть доступ к нескольким арендаторам, в верхнем меню используйте фильтр Directories + subscriptions (Каталоги и подписки) , чтобы выбрать арендатор, в котором следует зарегистрировать приложение.
  3. Найдите и выберите Azure Active Directory.
  4. В разделе Управление выберите Регистрация приложений>Создать регистрацию.
  5. Введите значение Name (Имя) для приложения. Пользователи приложения могут видеть это имя. Вы можете изменить его позже.
  6. Выберите Зарегистрировать.
  7. В разделе Управление выберите Проверка подлинности>Добавить платформу>iOS.
  8. Введите идентификатор пакета вашего приложения. Идентификатор пакета — это уникальная строка, однозначно идентифицирующая ваше приложение, например com.<yourname>.identitysample.MSALMacOS. Запишите значение, которое используете. Обратите внимание, что конфигурация iOS также применима к приложениям macOS.
  9. Щелкните элемент Настройка и сохраните сведения о конфигурации MSAL для последующего использования в рамках этого краткого руководства.
  10. Нажмите кнопку Готово.

Шаг 2. Загрузка примера проекта

Шаг 3. Установка зависимостей

  1. Извлеките ZIP-файл.
  2. В окне терминала перейдите к папке со скачанным примером кода и выполните pod install, чтобы установить последнюю библиотеку MSAL.

Шаг 4. Настройка проекта

Если вы выбрали вариант 1 выше, можно пропустить эти шаги.

  1. Откройте проект в XCode.

  2. Измените ViewController.swift и замените строку, начинающуюся с "let kClientID", следующим фрагментом кода. Не забудьте обновить значение kClientID, указав идентификатор клиента, который вы ранее сохранили при регистрации приложения на портале в этом кратком руководстве:

    let kClientID = "Enter_the_Application_Id_Here"
    
  3. Если вы создаете приложение для национальных облаков Azure AD, замените строку, начинающуюся с let kGraphEndpoint и let kAuthority соответствующими конечными точками. Для предоставления глобального доступа используйте значения по умолчанию:

    let kGraphEndpoint = "https://graph.microsoft.com/"
    let kAuthority = "https://login.microsoftonline.com/common"
    
  4. См. описание других конечных точек. Например, чтобы выполнить процесс для Azure AD Germany, используйте следующее:

    let kGraphEndpoint = "https://graph.microsoft.de/"
    let kAuthority = "https://login.microsoftonline.de/common"
    
  5. Откройте параметры проекта. В разделе Идентификатор введите идентификатор пакета, введенный на портале.

  6. Щелкните Info.plist, а затем выберите Открыть как>Исходный код.

  7. В корневом узле словаря замените Enter_the_bundle_Id_Hereидентификатором пакета, который вы использовали на портале. Обратите внимание на префикс msauth. в строке.

    <key>CFBundleURLTypes</key>
    <array>
       <dict>
          <key>CFBundleURLSchemes</key>
          <array>
             <string>msauth.Enter_the_Bundle_Id_Here</string>
          </array>
       </dict>
    </array>
    
  8. Создайте и запустите приложение!

Дополнительные сведения

Дополнительные сведения о кратком руководстве содержатся в этих разделах.

Получение MSAL

MSAL (MSAL.framework) — это библиотека, используемая для выполнения входа пользователей и запросов маркеров, которые нужны для доступа к API, защищенному платформой удостоверений Майкрософт. MSAL можно добавить в приложение, используя следующее действие.

$ vi Podfile

Добавьте в файл Podfile следующий код (целевую исполняющую среду проекта):

use_frameworks!

target 'MSALiOS' do
   pod 'MSAL'
end

Выполните команду установки CocoaPods:

pod install

Инициализация MSAL

Добавив следующий код, вы можете добавить ссылку на MSAL.

import MSAL

Затем выполните инициализацию MSAL с помощью следующего кода.

let authority = try MSALAADAuthority(url: URL(string: kAuthority)!)

let msalConfiguration = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: nil, authority: authority)
self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
Где: Описание
clientId Идентификатор зарегистрированного приложения на portal.azure.com
authority Платформа удостоверений Майкрософт. Как правило, это https://login.microsoftonline.com/common.
redirectUri URI перенаправления приложения. Можете передать нуль, чтобы использовать значение по умолчанию, или ваш пользовательский URI перенаправления.

(Только для iOS) Дополнительные требования для приложения

Ваше приложение также должно содержать следующий код в объекте AppDelegate. Это позволит пакету SDK MSAL обрабатывать ответ токена из приложения брокера авторизации при выполнении проверки подлинности.

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

    return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

Примечание

(В iOS 13+) Если вы принимаете UISceneDelegate вместо UIApplicationDelegate, поместите этот код в обратный вызов scene:openURLContexts: (см. Документацию Apple). Если UISceneDelegate и UIApplicationDelegate поддерживаются для совместимости с более старыми версиями iOS, то обратный вызов MSAL потребуется поместить в оба места.

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {

   guard let urlContext = URLContexts.first else {
      return
   }

   let url = urlContext.url
   let sourceApp = urlContext.options.sourceApplication

   MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApp)
}

Наконец, ваше приложение должно содержать запись LSApplicationQueriesSchemes в файле Info.plist вместе с элементом CFBundleURLTypes. Пример уже содержит эту запись.

<key>LSApplicationQueriesSchemes</key>
<array>
   <string>msauthv2</string>
   <string>msauthv3</string>
</array>

Выполнение входа пользователей и запрос токенов

MSAL имеет два метода получения маркеров безопасности: acquireToken и acquireTokenSilent.

acquireToken. Интерактивное получение маркера

Иногда требуется взаимодействие пользователей с платформой удостоверений Майкрософт. В таких случаях пользователю может потребоваться выбрать свою учетную запись, ввести учетные данные или предоставить согласие на разрешения приложения. Например,

  • первый вход пользователей в приложение;
  • Если пользователь сбрасывает пароль, то потребуется вводить свои учетные данные.
  • Когда ваше приложение впервые запрашивает доступ к ресурсу.
  • Когда требуются политики условного доступа или MFA.
let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
self.applicationContext!.acquireToken(with: parameters) { (result, error) in /* Add your handling logic */}
Где: Описание
scopes Содержит запрашиваемые области, то есть [ "user.read" ] для Microsoft Graph или [ "<Application ID URL>/scope" ] для пользовательских веб-API (api://<Application ID>/access_as_user).

acquireTokenSilent. Автоматическое получение маркера доступа

Приложения не требуют, чтобы пользователи выполняли вход каждый раз при запросе маркера. Если пользователь уже вошел, этот метод позволяет приложениям запрашивать маркеры автоматически.

self.applicationContext!.getCurrentAccount(with: nil) { (currentAccount, previousAccount, error) in

   guard let account = currentAccount else {
      return
   }

   let silentParams = MSALSilentTokenParameters(scopes: self.kScopes, account: account)
   self.applicationContext!.acquireTokenSilent(with: silentParams) { (result, error) in /* Add your handling logic */}
}
Где: Описание
scopes Содержит запрашиваемые области, то есть [ "user.read" ] для Microsoft Graph или [ "<Application ID URL>/scope" ] для пользовательских веб-API (api://<Application ID>/access_as_user).
account Учетная запись, для которой запрашивается токен. В этом кратком руководстве рассматривается приложение с одной учетной записью. Если вы хотите создать приложение с несколькими учетными записями, нужно определить логику для выбора учетной записи, которая будет использоваться для запросов токенов, с помощью accountsFromDeviceForParameters:completionBlock: и правильного идентификатора accountIdentifier.

Справка и поддержка

Если вам нужна помощь, если вы хотите сообщить о проблеме или узнать о доступных вариантах поддержки, воспользуйтесь статьей Возможности получения поддержки и справки для разработчиков.

Дальнейшие действия

Перейдите к пошаговому учебнику, с помощью которого вы создадите приложение iOS или macOS, получающее маркер доступа от платформы удостоверений Майкрософт и использующее его для вызова API Microsoft Graph.