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

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

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

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

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

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

Шаг 1. Настройка приложения

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

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

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

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

Шаг 4. Приложение настроено и готово к выполнению

Мы уже настроили для проекта нужные значения свойств приложения, и его можно запускать.

1. Если вы создаете приложение для национальных облаков Microsoft Entra, замените строку, начиная с "let kGraphEndpoint" и "Let kAuthority" с правильными конечными точками. Для предоставления глобального доступа используйте значения по умолчанию:

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

2. См. описание других конечных точек. Например, чтобы запустить краткое руководство по Microsoft Entra Germany, используйте следующее:

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

3. Откройте параметры проекта. В разделе Идентификатор введите идентификатор пакета, введенный на портале.

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

5. В корневом узле словаря замените 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>
   

6. Создайте и запустите приложение!

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

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

Получение 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)
}

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.