Краткое руководство: Вход в систему пользователями и вызов 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. В корневом узле dict замените 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)

Где:	Описание
clientId	Идентификатор приложения из приложения, зарегистрированного в portal.azure.com
authority	Платформа удостоверений Майкрософт. Как правило, это https://login.microsoftonline.com/common>.
redirectUri	URI перенаправления приложения. Вы можете передать термин 'nil', чтобы использовать значение по умолчанию, или указать собственный URI перенаправления.

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

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

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: Интерактивное получение токена

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

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

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
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.