قم بتمكين خيارات المصادقة في تطبيق iOS Swift باستخدام Azure AD B2C

توضح هذه المقالة الطرق التي يمكنك من خلالها تمكين تجربة مصادقة Azure Active Directory B2C (Azure AD B2C) وتخصيصها وتحسينها لتطبيق iOS Swift لديك.

قبل البدء، تعرف على المقالات التالية:

• تكوين المصادقة في نموذج تطبيق iOS Swift باستخدام Azure AD B2C
• تمكين المصادقة في تطبيق iOS Swift لديك باستخدام Azure AD B2C

استخدام مجال مخصص

باستخدام custom domain، يمكنك وضع علامة تجارية كاملة على عنوان URL للمصادقة. من منظور المستخدم، يظل المستخدمون في المجال الخاص بك أثناء عملية المصادقة، بدلاً من إعادة توجيههم إلى اسم مجال Microsoft Azure Active Directory B2C b2clogin.com.

لإزالة كافة الإشارات إلى "b2c" في عنوان URL، يمكنك أيضاً استبدال اسم مستأجر B2C الخاص بك، contoso.onmicrosoft.com، في عنوان URL لطلب المصادقة مع معرف المستأجر GUID. على سبيل المثال، يمكنك تغيير https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ إلى https://account.contosobank.co.uk/<tenant ID GUID>/.

لاستخدام مجال مخصص ومعرف المستأجر لديك في عنوان URL للمصادقة، قم بما يلي:

1. اتبع التوجيهات الواردة في تمكين المجالات المخصصة.
2. قم بتحديث عضو الفئة kAuthorityHostName بمجالك الخاص.
3. قم بتحديث عضو الفئة 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 في طلب التفويض باسم تسجيل دخول المستخدم. يملأ Microsoft Azure Active Directory B2C اسم تسجيل الدخول تلقائياً، ويحتاج المستخدم إلى توفير كلمة المرور فقط.

لملء اسم تسجيل الدخول مسبقاً، قم بما يلي:

1. لو كنت تستخدم نهجًا مخصصًا، فأضف مطالبة الإدخال المطلوبة، كما هو موضح في إعداد تسجيل الدخول المباشر.
2. ابحث عن عنصر تكوين Microsoft Authentication Library (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
...

حدد موفر الهوية مسبقًا

إذا قمت بتكوين رحلة «sign-in» لتطبيقك من أجل تضمين الحسابات الاجتماعية، مثل Facebook أو LinkedIn أو Google، يمكنك تحديد المعلمة domain_hint. توفر معلمة الاستعلام تلميح إلى Azure AD B2C حول موفر الهوية الاجتماعية التي يجب استخدامها لـ «sign-in». على سبيل المثال، إذا حدد التطبيق domain_hint=facebook.com، ينتقل تدفق تسجيل الدخول مباشرة إلى صفحة تسجيل الدخول إلى Facebook.

لإعادة توجيه المستخدمين إلى موفر هوية خارجي، قم بما يلي:

1. تحقق من اسم المجال لموفر الهوية الخارجي الخاص بك. لمزيد من المعلومات، راجع إعادة توجيه تسجيل الدخول إلى موفر خدمة اجتماعية.
2. إنشاء أو استخدام كائن قائمة موجود لتخزين معلمات الاستعلام الإضافية.
3. أضف المعلمة domain_hint مع اسم المجال المقابل إلى القائمة (على سبيل المثال، facebook.com).
4. مرّر قائمة معلمات الاستعلام الإضافية إلى السمة 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
...

تحديد لغة واجهة المستخدم

يتيح تخصيص اللغة في Microsoft Azure Active Directory B2C تدفق المستخدم لاستيعاب مجموعة متنوعة من اللغات لتناسب احتياجات عملائك. لمزيد من المعلومات، راجع تخصيص اللغة.

لتعيين اللغة المفضلة، قم بما يلي:

1. تكوين تخصيص اللغة.
2. إنشاء أو استخدام كائن قائمة موجود لتخزين معلمات الاستعلام الإضافية.
3. أضف المعلمة ui_locales باستخدام التعليمات البرمجية للغة المقابلة إلى القائمة (على سبيل المثال، en-us).
4. مرّر قائمة معلمات الاستعلام الإضافية إلى السمة 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
...

تمرير معلمة سلسلة استعلام مخصصة

باستخدام النُهج المخصصة، يمكنك تمرير معلمة سلسلة طلب بحث مخصصة. من الأمثلة الجيدة على حالة الاستخدام عندما تريد تغيير محتوى الصفحة ديناميكياً.

لتمرير معلمة سلسلة طلب بحث مخصصة، قم بما يلي:

1. تكوينعنصر ContentDefinitionParameters.
2. إنشاء أو استخدام كائن قائمة موجود لتخزين معلمات الاستعلام الإضافية.
3. أضف معلمة سلسلة الاستعلام المخصصة، مثل campaignId. قم بتعيين قيمة المعلمة (على سبيل المثال، germany-promotion).
4. مرّر قائمة معلمات الاستعلام الإضافية إلى السمة 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 وارد (JWT) كجزء من طلب تفويض OAuth2. الرمز المميز الوارد هو تلميح حول المستخدم أو طلب التفويض. يتحقق Microsoft Azure Active Directory B2C من صحة الرمز المميز ثم يستخرج المطالبة.

لتضمين تلميح رمز مميز للمعرف في طلب المصادقة، قم بما يلي:

1. في سياستك المخصصة، حدد ملف تعريف تقني تلميح رمز مميز للمعرف.
2. في التعليمات البرمجية الخاصة بك، قم بإنشاء أو الحصول على رمز مميز للمعرف، ثم قم بتعيين الرمز المميز إلى متغير (على سبيل المثال، idToken).
3. إنشاء أو استخدام كائن قائمة موجود لتخزين معلمات الاستعلام الإضافية.
4. أضف المعلمة id_token_hint مع المتغير المقابل الذي يخزن الرمز المميز للمعرف.
5. مرّر قائمة معلمات الاستعلام الإضافية إلى السمة 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.swift.application

يوضح القصاصات البرمجية التالية كيفية تكوين تسجيل 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.

لمزيد من المعلومات، راجع مقالة تخصيص المستعرضات وعروض WebView لنظامي التشغيل iOS/macOS.

بناءً على متطلباتك، يمكنك استخدام عرض الويب المضمن. توجد اختلافات في سلوك تسجيل الدخول المرئي والمفرد بين عرض الويب المضمن وعرض ويب النظام في MSAL.

هام

نوصي باستخدام النظام الأساسي الافتراضي، وهو عادةً متصفح النظام. متصفح النظام أفضل في تذكر المستخدمين الذين قاموا بتسجيل الدخول من قبل. لا يدعم بعض موفري الهوية، مثل Google، تجربة العرض المضمنة.

لتغيير هذا السلوك، قم بتغيير السمة webviewType لـ MSALWebviewParameters إلى wkWebView. يوضح المثال التالي كيفية تغيير نوع عرض الويب إلى طريقة العرض المضمنة:

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

الخطوات التالية

• لمعرفة المزيد، راجع MSAL لخيارات تكوين Swift لنظام iOS.