Включение способов проверки подлинности в приложении iOS Swift с помощью Azure AD B2C

Статья
01/11/2024

В этой статье рассказывается о способах включения, настройки и расширения возможностей проверки подлинности в Azure Active Directory B2C (Azure AD B2C) для приложений iOS Swift.

Прежде чем приступить к работе, ознакомьтесь с указанными ниже статьями.

Использование личного домена

С помощью личного домена можно полностью брендировать URL-адрес проверки подлинности. С точки зрения пользователя, пользователи остаются в вашем домене во время процесса аутентификации, а не перенаправляются на доменное имя b2clogin.com в Azure AD B2C.

Чтобы удалить все ссылки на b2c в URL-адресе, вы также можете заменить свое имя клиента B2C, contoso.onmicrosoft.com, в URL-адресе запроса проверки подлинности на свой GUID идентификатора клиента. Например, можно изменить https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ на https://account.contosobank.co.uk/<tenant ID GUID>/.

Чтобы использовать личный домен и ваш идентификатор клиента в URL-адресе проверки подлинности, выполните указанные ниже действия.

Следуйте инструкциям в статье Подключение личных доменов в Azure Active Directory B2C.
Обновите элемент класса kAuthorityHostName, используя личный домен.
Обновите элемент класса kTenantName, используя ваш идентификатор клиента.

В приведенном ниже коде на языке Swift показаны параметры приложения перед внесением изменений.

let kTenantName = "contoso.onmicrosoft.com" 
let kAuthorityHostName = "contoso.b2clogin.com"

В приведенном ниже коде на языке Swift показаны параметры приложения после внесения изменений.

let kTenantName = "00000000-0000-0000-0000-000000000000" 
let kAuthorityHostName = "login.contoso.com"

Во время входа пользователя в систему ваше приложение может предложить определенное имя пользователя. При этом приложение может указать параметр запроса login_hint с именем пользователя в запросе на авторизацию. Azure AD B2C автоматически заполняет имя для входа в систему — пользователю нужно ввести только пароль.

Чтобы предварительно заполнить имя для входа, выполните следующие действия.

Если вы используете настраиваемую политику, добавьте обязательное входящее утверждение, как описано в статье Настройка прямого входа в систему.
Найдите объект конфигурации Библиотеки проверки подлинности Майкрософт (MSAL), а затем добавьте метод withLoginHint() с указанием имени для входа.

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.loginHint = "bob@contoso.com"
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Предварительный выбор поставщика удостоверений

Если вы настроили для приложения возможность входа с использованием учетных записей социальных сетей, таких как Facebook, LinkedIn или Google, вы можете указать параметр domain_hint. Этот параметр запроса сообщает Azure AD B2C о поставщике удостоверений социальных сетей, который должен использоваться для входа в систему. Например, если приложение указывает domain_hint=facebook.com, вход в систему выполняется непосредственно на странице входа в Facebook.

Чтобы перенаправить пользователей к внешнему поставщику удостоверений, выполните следующие действия.

Проверьте доменное имя внешнего поставщика удостоверений. Дополнительные сведения см. в статье Перенаправление входа в поставщика социальных сетей.
Создайте объект list или используйте существующий объект list для хранения дополнительных параметров запроса.
Добавьте параметр domain_hint с соответствующим доменным именем в список (например, facebook.com).
Передайте список дополнительных параметров запроса в атрибут extraQueryParameters объекта конфигурации MSAL.

let extraQueryParameters: [String: String] = ["domain_hint": "facebook.com"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Указание языка пользовательского интерфейса

Настройка языка в Azure AD B2C позволяет поддерживать в потоке разные языки в соответствии с требованиями пользователей. Дополнительные сведения см. в статье Настройка языка.

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

Настройте язык.
Создайте объект list или используйте существующий объект list для хранения дополнительных параметров запроса.
Добавьте параметр ui_locales с соответствующим кодом языка в список (например, en-us).
Передайте список дополнительных параметров запроса в атрибут extraQueryParameters объекта конфигурации MSAL.

let extraQueryParameters: [String: String] = ["ui_locales": "en-us"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Передача настраиваемого параметра строки запроса

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

Чтобы передать настраиваемый параметр строки запроса, выполните следующие действия.

Настройка элемента ContentDefinitionParameters.
Создайте объект list или используйте существующий объект list для хранения дополнительных параметров запроса.
Добавьте параметр строки пользовательского запроса, например campaignId. Задайте значение параметра (например, germany-promotion).
Передайте список дополнительных параметров запроса в атрибут extraQueryParameters объекта конфигурации MSAL.

let extraQueryParameters: [String: String] = ["campaignId": "germany-promotion"]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Передача указания к маркеру идентификатора

Приложения проверяющей стороны могут передавать входящие маркеры JSON Web Token (JWT) в рамках запроса авторизации OAuth2. Входящий маркер представляет собой указание о пользователе или запросе на авторизацию. Azure AD B2C проверяет маркер и извлекает утверждение.

Чтобы включить указание маркера идентификатора в запрос проверки подлинности, сделайте следующее:

В пользовательской политике определите технический профиль указания для маркера идентификатора.
В коде создайте или получите маркер идентификации и задайте для него переменную (например, idToken).
Создайте объект list или используйте существующий объект list для хранения дополнительных параметров запроса.
Добавьте параметр id_token_hint с соответствующей переменной, в которой хранится маркер идентификатора.
Передайте список дополнительных параметров запроса в атрибут extraQueryParameters объекта конфигурации MSAL.

let extraQueryParameters: [String: String] = ["id_token_hint": idToken]

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount
parameters.authority = authority
parameters.extraQueryParameters = extraQueryParameters
// More settings here

applicationContext.acquireToken(with: parameters) { (result, error) in
...

Настройка журнала

Библиотека MSAL создает сообщения журнала, способные помочь при диагностике проблем. Приложение может настроить ведение журнала. Приложение также может предоставить пользовательский элемент управления уровнем детализации и установить, нужно ли регистрировать в журнале личные и корпоративные данные.

Рекомендуется создать обратный вызов при ведении журнала MSAL и предоставить пользователям возможность оправлять журналы при возникновении проблем с проверкой подлинности. MSAL предоставляет следующие уровни детализации при ведении журнала.

Ошибка. Означает, что возникла проблема и сгенерирована ошибка. Этот уровень используется для отладки и выявления проблем.
Предупреждение. Не обязательно указывает на ошибку или сбой, но эта информация предназначена для диагностики и выявления проблем.
Информация. MSAL записывает в журнал сведения о событиях в информационных целях (не обязательно для отладки).
Подробно. Этот уровень задан по умолчанию. MSAL записывает в журнал все сведения о поведении библиотеки.

По умолчанию средство ведения журналов MSAL не регистрирует персональные данные или данные организации. Библиотека позволяет при необходимости включить ведение журналов персональных и корпоративных данных.

В процессе запуска приложения следует как можно раньше настроить средство ведения журнала MSAL (прежде чем совершать какие-либо запросы MSAL). Настройте функцию ведения журналов MSAL в методе AppDelegate.swiftapplication.

В следующем фрагменте кода показано, как настроить ведение журнала MSAL:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        MSALGlobalConfig.loggerConfig.logLevel = .verbose
        MSALGlobalConfig.loggerConfig.setLogCallback { (logLevel, message, containsPII) in
            
            // If PiiLoggingEnabled is set YES, this block will potentially contain sensitive information (Personally Identifiable Information), but not all messages will contain it.
            // containsPII == YES indicates if a particular message contains PII.
            // You might want to capture PII only in debug builds, or only if you take necessary actions to handle PII properly according to legal requirements of the region
            if let displayableMessage = message {
                if (!containsPII) {
                    #if DEBUG
                    // NB! This sample uses print just for testing purposes
                    // You should only ever log to NSLog in debug mode to prevent leaking potentially sensitive information
                    print(displayableMessage)
                    #endif
                }
            }
        }
        return true
    }

Встроенный интерфейс веб-представления

Для интерактивной проверки подлинности нужны веб-браузеры. По умолчанию в библиотеке MSAL используется системное веб-представление. В процессе входа в систему библиотека MSAL отображает системное веб-представление iOS с помощью пользовательского интерфейса Azure AD B2C.

Дополнительные сведения см. в статье Настройка браузеров и веб-представлений для iOS/macOS.

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

Снимок экрана, на котором показана разница между интерфейсами системного и встроенного веб-представлений.

Важно!

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

Чтобы изменить это, в атрибуте webviewType измените значение MSALWebviewParameters на wkWebView. В приведенном ниже примере показано, как изменить тип веб-представления на внедренное представление.

func initWebViewParams() {
    self.webViewParameters = MSALWebviewParameters(authPresentationViewController: self)
    
    // Use embedded view experience
    self.webViewParameters?.webviewType = .wkWebView
}

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

Дополнительные сведения см. в статье Параметры конфигурации MSAL для iOS Swift.

Поделиться через

Включение способов проверки подлинности в приложении iOS Swift с помощью Azure AD B2C

Использование личного домена

Предварительный выбор поставщика удостоверений

Указание языка пользовательского интерфейса

Передача настраиваемого параметра строки запроса

Передача указания к маркеру идентификатора

Настройка журнала

Встроенный интерфейс веб-представления

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

Обратная связь

Дополнительные ресурсы

Поделиться через

Включение способов проверки подлинности в приложении iOS Swift с помощью Azure AD B2C

Использование личного домена

Предварительное заполнение имени входа в систему

Предварительный выбор поставщика удостоверений

Указание языка пользовательского интерфейса

Передача настраиваемого параметра строки запроса

Передача указания к маркеру идентификатора

Настройка журнала

Встроенный интерфейс веб-представления

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

Обратная связь

Дополнительные ресурсы