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

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

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

Необходимые компоненты

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

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

Регистрация приложения быстрого запуска

Совет

Действия, описанные в этой статье, могут немного отличаться на портале, с который вы начинаете работу.

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

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

Шаг 2. Скачивание примера проекта

• Загрузка примера кода для iOS
• Загрузка примера кода для macOS

Шаг 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. Если вы создаете приложение для национальных облаков Microsoft Entra, замените строку, начиная с "let kGraphEndpoint" и "Let kAuthority" с правильными конечными точками. Для предоставления глобального доступа используйте значения по умолчанию:

   let kGraphEndpoint = "https://graph.microsoft.com/"
   let kAuthority = "https://login.microsoftonline.com/common"
   

4. См. описание других конечных точек. Например, чтобы запустить краткое руководство по Microsoft Entra 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)

Где:	Description
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 */}

Где:	Description
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 */}
}

Где:	Description
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.

Руководство. Вход пользователей и вызов Microsoft Graph из приложения iOS или macOS