تكوين تسجيل الدخول باستخدام Apple (معاينة) - Azure App Service

مقالة
06/01/2023

توضح لك هذه المقالة كيفية تكوين Azure App Service أو Azure Functions لاستخدام تسجيل الدخول مع Apple كموفر مصادقة.

لإكمال الإجراء في هذه المقالة، يجب أن تكون قد سجلت في برنامج مطور Apple. للتسجيل في برنامج مطور Apple، انتقل إلى developer.apple.com/programs/enroll.

تنبيه

سيؤدي تمكين تسجيل الدخول باستخدام Apple إلى تعطيل إدارة ميزة مصادقة / تخويل خدمة التطبيقات لتطبيقك من خلال بعض العملاء، مثل مدخل Microsoft Azure وAzure CLI وAzure PowerShell. تعتمد الميزة على سطح واجهة برمجة تطبيقات جديد لم يتم حسابه بعد في جميع تجارب الإدارة أثناء المعاينة.

إنشاء تطبيق في مدخل Apple Developer

ستحتاج إلى إنشاء معرف تطبيق ومعرف خدمة في مدخل Apple Developer.

في مدخل مطور Apple، انتقل إلى الشهادات والمعرفات وملفات التعريف.
في علامة التبويب Identifiers، حدد الزر (+).
في صفحة Register a New Identifier، اختر App IDs وحدد Continue. (تتضمن معرفات التطبيقات معرف خدمة واحدا أو أكثر.)
في صفحة Register an App ID، قم بتوفير وصف ومعرف مجموعة، وحدد Sign in with Apple من قائمة الإمكانات. بعد ذلك، حدد متابعة. لاحظ بادئة معرف التطبيق (معرف الفريق) من هذه الخطوة، ستحتاج إليها لاحقاً.
راجع معلومات تسجيل التطبيق وحدد Register.
مرة أخرى، في علامة التبويب Identifiers، حدد الزر (+).
في صفحة Register a New Identifier، اختر Services IDs وحدد Continue.
في صفحة Register a Services ID، قم بتوفير وصف ومعرف. الوصف هو ما سيظهر للمستخدم على شاشة الموافقة. سيكون المعرف هو معرف العميل الخاص بك المستخدم في تكوين موفر Apple مع خدمة التطبيق الخاصة بك. ثم حدد "Configure".
في النافذة المنبثقة، قم بتعيين معرف التطبيق الأساسي إلى معرف التطبيق الذي أنشأته سابقاً. حدد مجال التطبيق الخاص بك في قسم المجال. بالنسبة إلى عنوان URL للإرجاع، استخدم عنوان URL<app-url>/.auth/login/apple/callback. على سبيل المثال، https://contoso.azurewebsites.net/.auth/login/apple/callback ثم حدد Add وSave.
راجع معلومات تسجيل الخدمة وحدد Save.

إنشاء سر العميل

تتطلب Apple من مطوري التطبيقات إنشاء رمز JWT المميز وتوقيعه كقيمة سرية للعميل. لإنشاء هذا السر، قم أولاً بإنشاء وتنزيل مفتاح خاص بمنحنى ناقص من مدخل Apple Developer. ثم استخدم هذا المفتاح لتوقيع JWT مع حمولة معينة.

إنشاء المفتاح الخاص وتنزيله

في علامة التبويب Keys في مدخل Apple Developer، اختر Create a key أو حدد الزر (+).
في صفحة Register a New Key، حدد اسماً للمفتاح، وحدد المربع الموجود بجانب تسجيل الدخول باستخدام Apple وحدد Configure.
في صفحة Configure Key، اربط المفتاح بمعرف التطبيق الأساسي الذي قمت بإنشائه مسبقاً وحدد Save.
قم بإنهاء إنشاء المفتاح عن طريق تأكيد المعلومات وتحديد Continue ثم مراجعة المعلومات وتحديد Register.
في صفحة Download Your Key، قم بتنزيل المفتاح. سيتم تنزيله كملف .p8 (PKCS#8) - ستستخدم محتويات الملف لتوقيع JWT السري للعميل.

هيكلة سر العميل JWT

تتطلب Apple أن يكون سر العميل هو ترميز base64 للرمز المميز JWT. يجب أن يحتوي رمز JWT المميز الذي تم فك ترميزه على حمولة منظمة مثل هذا المثال:

{
  "alg": "ES256",
  "kid": "URKEYID001",
}.{
  "sub": "com.yourcompany.app1",
  "nbf": 1560203207,
  "exp": 1560289607,
  "iss": "ABC123DEFG",
  "aud": "https://appleid.apple.com"
}.[Signature]

sub: معرف عميل Apple (أيضاً معرف الخدمة)
appleTeamId: معرف فريق Apple Developer الخاص بك
aud: تتلقى Apple الرمز المميز، لذا فهي الجمهور
exp: لا يزيد عن ستة أشهر بعد nbf

يبدو الإصدار المشفر باستخدام base64 من الحمولة أعلاه كما يلي: eyJhbGciOiJFUzI1NiIsImtpZCI6IlVSS0VZSUQwMDEifQ.eyJzdWIiOiJjb20ueW91cmNvbXBhbnkuYXBwMSIsIm5iZiI6MTU2MDIwMzIwNywiZXhwIjoxNTYwMjg5NjA3LCJpc3MiOiJBQkMxMjNERUZHIiwiYXVkIjoiaHR0cHM6Ly9hcHBsZWlkLmFwcGxlLmNvbSJ9.ABSXELWuTbgqfrIUz7bLi6nXvkXAz5O8vt0jB2dSHTQTib1x1DSP4__4UrlKI-pdzNg1sgeocolPNTmDKazO8-BHAZCsdeeTNlgFEzBytIpMKFfVEQbEtGRkam5IeclUK7S9oOva4EK4jV4VmgDrr-LGWWO3TaAxAvy3_ZoKohvFFkVG

ملاحظة: لا تقبل Apple JWTs السرية للعميل بتاريخ انتهاء صلاحية بعد أكثر من ستة أشهر من تاريخ الإنشاء (أو nbf). وهذا يعني أنك ستحتاج إلى تدوير سر العميل الخاص بك، على الأقل، كل ستة أشهر.

يمكن العثور على مزيدٍ من المعلومات حول إنشاء الرموز المميزة والتحقق من صحتها في وثائق مطور Apple.

توقيع سر العميل JWT

ستستخدم ملف .p8 الذي قمت بتنزيله مسبقاً للتوقيع على سر العميل JWT. هذا الملف هو ملف PCKS#8 الذي يحتوي على مفتاح التوقيع الخاص بتنسيق PEM. هناك العديد من المكتبات التي يمكن إنشاء وتوقيع JWT بالنسبة لك.

هناك أنواع مختلفة من المكتبات مفتوحة المصدر المتوفرة عبر الإنترنت لإنشاء رموز JWT المميزة وتوقيعها. لمزيدٍ من المعلومات حول إنشاء رموز JWT المميزة، راجع JSON Web Token (JWT). على سبيل المثال، تتمثل إحدى طرق إنشاء سر العميل في استيراد حزمة Microsoft.IdentityModel.Tokens NuGet وتشغيل كمية صغيرة من التعليمة البرمجية C# الموضح أدناه.

using Microsoft.IdentityModel.Tokens;

public static string GetAppleClientSecret(string teamId, string clientId, string keyId, string p8key)
{
    string audience = "https://appleid.apple.com";

    string issuer = teamId;
    string subject = clientId;
    string kid = keyId;

    IList<Claim> claims = new List<Claim> {
        new Claim ("sub", subject)
    };

    CngKey cngKey = CngKey.Import(Convert.FromBase64String(p8key), CngKeyBlobFormat.Pkcs8PrivateBlob);

    SigningCredentials signingCred = new SigningCredentials(
        new ECDsaSecurityKey(new ECDsaCng(cngKey)),
        SecurityAlgorithms.EcdsaSha256
    );

    JwtSecurityToken token = new JwtSecurityToken(
        issuer,
        audience,
        claims,
        DateTime.Now,
        DateTime.Now.AddDays(180),
        signingCred
    );
    token.Header.Add("kid", kid);
    token.Header.Remove("typ");

    JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler();

    return tokenHandler.WriteToken(token);
}

teamId: معرف فريق Apple Developer الخاص بك
clientId: معرف عميل Apple (أيضاً معرف الخدمة)
p8key: مفتاح تنسيق PEM - يمكنك الحصول على المفتاح بفتح الملف .p8 في محرر نصي، ونسخ كل شيء بين -----BEGIN PRIVATE KEY----- و-----END PRIVATE KEY----- بدون فواصل أسطر
keyId: معرف المفتاح الذي تم تنزيله

هذا الرمز المميز الذي تم إرجاعه هو القيمة السرية للعميل التي ستستخدمها لتكوين موفر Apple.

هام

تُعد البيانات السرية للعميل بيانات اعتماد أمان هامة. لا تُشارك هذا السر مع أي شخص أو توزعه ضمن تطبيق عميل.

أضف سر العميل باعتباره إعداد تطبيق للتطبيق، باستخدام اسم إعداد من اختيارك. دون هذا الاسم لاحقاً.

أضف معلومات الموفر إلى التطبيق الخاص بك

إشعار

التكوين المطلوب بتنسيق واجهة برمجة تطبيقات جديد، مدعوم حالياً فقط بواسطة التكوين المستند إلى الملف (معاينة). ستحتاج إلى اتباع الخطوات التالية باستخدام مثل هذا الملف.

سيرشدك هذا القسم خلال تحديث التكوين لتضمين IDP الجديد. وفيما يلي مثال للتكوين.

داخل الكائن identityProviders، أضف كائن apple إذا لم يكن موجوداً بالفعل.
قم بتعيين كائن لهذا المفتاح مع كائن registration بداخله، واختيارياً كائن login:
```
"apple" : {
   "registration" : {
        "clientId": "<client ID>",
        "clientSecretSettingName": "APP_SETTING_CONTAINING_APPLE_CLIENT_SECRET" 
    },
   "login": {
         "scopes": []
   }
}
```
أ. داخل الكائن registration، عيّن clientId على معرّف العميل الذي جمعته.

ب. داخل الكائن registration، قم بتعيين clientSecretSettingName على اسم إعداد التطبيق حيث قمت بتخزين سر العميل.

جـ. داخل كائن login، يمكنك اختيار تعيين المصفوفة scopes لتضمين قائمة بالنطاقات المستخدمة عند المصادقة مع Apple، مثل "الاسم" و"البريد الإلكتروني". إذا تم تكوين النطاقات، فسيتم طلبها بشكلٍ صريح على شاشة الموافقة عندما يقوم المستخدمون بتسجيل الدخول للمرة الأولى.

بمجرد تعيين هذا التكوين، تكون جاهزاً لاستخدام موفر Apple للمصادقة في تطبيقك.

قد يبدو التكوين الكامل مثل المثال التالي (حيث يشير إعداد APPLE_GENERATED_CLIENT_SECRET إلى إعداد تطبيق يحتوي على JWT تم إنشاؤه):

{
    "platform": {
        "enabled": true
    },
    "globalValidation": {
        "redirectToProvider": "apple",
        "unauthenticatedClientAction": "RedirectToLoginPage"
    },
    "identityProviders": {
        "apple": {
            "registration": {
                "clientId": "com.contoso.example.client",
                "clientSecretSettingName": "APPLE_GENERATED_CLIENT_SECRET"
            },
            "login": {
                "scopes": []
            }
        }
    },
    "login": {
        "tokenStore": {
            "enabled": true
        }
    }     
}

تكوين App Service أو تطبيق Azure Functions لتسجيل الدخول باستخدام تسجيل الدخول باستخدام موفر Apple (معاينة)