التحضير لإجراء طلب مصادق عليه إلى واجهة برمجة التطبيقات

بعد إنشاء وتهيئة حساب خدمة، يحتاج تطبيقك إلى إكمال الخطوات التالية:

1. إنشاء JSON Web Token (JWT)، والذي يتضمن الترويسة (header) والحمولة (payload) والتوقيع (signature)؛
2. طلب رمز وصول (AccessToken) من منصة مصادقة OAuth2؛
3. التعامل مع استجابة JSON التي ستعيدها منصة المصادقة.

إذا تضمنت الاستجابة رمز وصول، يمكنك استخدامه لإجراء طلبات إلى واجهات برمجة تطبيقات منتجات Unico التي يملك حساب الخدمة صلاحية الوصول إليها. (إذا لم تتضمن الاستجابة رمز وصول، فقد يكون JWT وطلب الرمز الخاصين بك غير صحيحين، أو قد لا يمتلك حساب الخدمة الصلاحيات اللازمة للوصول إلى الموارد المطلوبة.)

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

1 — إنشاء JWT

يتكون JWT من ثلاثة أجزاء: ترويسة (header)، وحمولة (payload)، وتوقيع (signature). الترويسة والحمولة هما كائنا JSON. يتم تسلسل (serialize) كائنا JSON هذين بترميز UTF-8 ثم ترميزهما باستخدام ترميز Base64url¹. يوفر هذا الترميز مقاومة للتغيرات في الترميز في حالات عمليات الترميز المتكررة. يتم ربط الترويسة والحمولة والتوقيع بحرف نقطة (.).

يتكون JWT على النحو التالي:

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

يتكون النص الأساسي للتوقيع على النحو التالي:

{Header in Base64url}.{Payload in Base64url}

1.1 — تكوين ترويسة JWT

تتكون الترويسة من حقلين يحددان خوارزمية التوقيع وتنسيق الرمز (token). كلا الحقلين إلزاميان، ولكل حقل قيمة واحدة فقط. تعتمد حسابات الخدمة على خوارزمية RSA SHA-256 وتنسيق رمز JWT. ونتيجة لذلك، يكون تمثيل JSON للترويسة كما يلي:

{"alg":"RS256","typ":"JWT"}

تمثيل Base64url هو كما يلي:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

1.2 — تكوين حمولة JWT

تحتوي حمولة JWT على معلومات حول JWT، بما في ذلك الصلاحيات المطلوبة (scopes)، والحساب الذي يطلب الوصول، والجهة المُصدرة، ووقت إصدار الرمز، ومدة صلاحية الرمز. معظم الحقول إلزامية. تمامًا مثل ترويسة JWT، فإن الحمولة هي كائن JSON وتُستخدم في تكوين التوقيع.

1.3 — الحقول الإلزامية

الحقول الإلزامية في JWT موضحة في الجدول أدناه. يمكن أن تظهر بأي ترتيب داخل الحمولة.

الاسم	الوصف
iss	معرّف حساب الخدمة داخل الشركة.
scope	قائمة مفصولة بمسافات أو بعلامة الجمع (+) للصلاحيات التي يطلبها التطبيق. إذا كانت جميع صلاحيات الحساب مطلوبة، استخدم رمز النجمة (*) لذلك.
aud	عنوان منصة المصادقة التي تصدر رموز الوصول. يجب أن تكون هذه القيمة دائمًا بالضبط https://identityhomolog.acesso.io. المشكلات الشائعة التي لا تعمل: إضافة شرطة مائلة زائدة في النهاية (https://identityhomolog.acesso.io/)، أو استخدام HTTP بدلاً من HTTPS.
exp	وقت انتهاء صلاحية الرمز، محدد بالثواني منذ الساعة 00:00:00 بتوقيت UTC، 1 يناير 1970. تبلغ المدة القصوى لهذه القيمة ساعة واحدة بعد وقت إصدار JWT. يجب أن تكون رقمية — القيمة الموضوعة بين علامتي اقتباس مثل "1524161193" هي سلسلة نصية ولن تعمل؛ 1524161193 هي رقم وستعمل.
iat	وقت إصدار JWT، محدد بالثواني منذ الساعة 00:00:00 بتوقيت UTC، 1 يناير 1970. يجب أن تكون هذه القيمة رقمية، بنفس قاعدة exp.

يجب أن يمثل حقل iat الوقت الحالي بالتنسيق المطلوب، ويجب أن يحترم حقل exp الحساب التالي:

exp = iat + 3600

تمثيل حقول JSON الإلزامية في حمولة JWT هو كما يلي:

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976,
  "iat": 1626293376
}

1.4 — حساب التوقيع

مواصفة **JSON Web Signature (JWS)**² هي الآلية التي توجّه حساب التوقيع الخاص بـ JWT. محتوى الإدخال لحساب التوقيع هو مصفوفة البايتات للمحتوى التالي:

{Header in Base64url}.{Payload in Base64url}

يجب استخدام نفس الخوارزمية المحددة في ترويسة JWT عند حساب التوقيع. خوارزمية التوقيع الوحيدة المدعومة من منصة مصادقة OAuth2 هي RSA باستخدام SHA-256، ويُعبَّر عنها بـ RS256 في حقل alg من ترويسة JWT.

قم بتوقيع تمثيل UTF-8 لمحتوى الإدخال باستخدام SHA256withRSA (المعروفة أيضًا باسم RSASSA-PKCS1-V1_5-SIGN مع تجزئة SHA-256) باستخدام المفتاح الخاص الذي تم إنشاؤه وربطه بحساب الخدمة (ملف .key.pem الذي تم إنشاؤه من الطلب المستلم عبر البريد الإلكتروني). سيكون المحتوى الناتج مصفوفة بايتات.

بعد ذلك، يجب ترميز التوقيع بترميز Base64url. يجب ربط الترويسة والحمولة والتوقيع بحرف نقطة. النتيجة هي JWT.

من الممكن أيضًا استخدام مكتبات جاهزة لإنشاء JWT. كمرجع، يمكنك العثور على قائمة بالمكتبات على موقع jwt.io.

2 — إجراء طلب للحصول على رمز وصول

بعد إنشاء JWT الموقّع، يمكن للتطبيق استخدامه لطلب رمز وصول. طلب رمز الوصول هو طلب POST عبر HTTPS، ويجب أن يكون الجسم (body) مُرمّزًا بصيغة URL. يظهر عنوان URL أدناه:

https://identityhomolog.acesso.io/oauth2/token

المعلمات التالية إلزامية في طلب POST عبر HTTPS:

الاسم	الوصف
grant_type	استخدم النص التالي، مُرمّزًا بصيغة URL إذا لزم الأمر: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	JWT، متضمنًا التوقيع.

POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=<jwt>

3 — التعامل مع استجابة منصة المصادقة

إذا كان JWT وطلب رمز الوصول مُشكَّلين بشكل صحيح، وكان حساب الخدمة يمتلك الصلاحيات اللازمة، فستعيد منصة المصادقة كائن JSON يحتوي على رمز وصول:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600"
}

رمز الوصول المُعاد في حقل access_token من كائن JSON هو أيضًا رمز JWT ويجب استخدامه في واجهات برمجة تطبيقات منتجات Unico. إذا حدث خطأ في الطلب، تحقق من نوع الخطأ في أخطاء المصادقة.

4 — مدة صلاحية رمز الوصول

مدة صلاحية رمز الوصول متغيرة. يتم تحديد مدته في حقل expires_in، الذي يُعاد مع رمز الوصول. يجب استخدام نفس رمز الوصول طوال مدة صلاحيته لجميع استدعاءات API الخاصة بالمنتجات.

لا تطلب رمز وصول جديدًا حتى تقترب صلاحية الرمز الحالي من الانتهاء. نوصي بهامش قدره 600 ثانية (10 دقائق):

new Date((token.exp - 600) * 1000)

حيث token.exp هو الطابع الزمني (timestamp) لانتهاء صلاحية الرمز.

ملاحظة

بشكل افتراضي، يدوم الرمز المُرسل إلى الشركة لمدة ساعة واحدة، ولكن يمكن تغيير ذلك. التوصية هي استخدام expires_in دائمًا كأساس وطرح 600 ثانية منه لطلب رمز جديد.

أمثلة:

Standard scenario:
expires_in: 3600 (1h) - Token generated at 14:42
Request a new token only at 15:32, that is, 14:42 + (3600 - 600)

Scenario with modified duration:
expires_in: 7200 (2h) - Token generated at 14:42
Request a new token only at 16:32, that is, 14:42 + (7200 - 600)

تحذير

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

---

¹ وفقًا لـ RFC 4648 لترميز BaseN، فإن تنسيق Base64url مشابه لـ Base64، باستثناء أن حرف = محذوف، وأن الحرفين + و/ يُستبدلان بـ - و_ على التوالي. ² JSON Web Signature: https://tools.ietf.org/html/rfc7515.