---
title: التحضير لإجراء طلب مصادق عليه إلى واجهة برمجة التطبيقات
description: كيفية بناء وتوقيع JWT، وطلب رمز وصول من منصة OAuth2، والتعامل مع استجابة الرمز وانتهاء صلاحيته.
canonical: https://developer.unico.io/ar/dual-api/developers/regional-solutions/card-not-present-verification/integration/authentication/preparing-authenticated-request
locale: ar
generated_by: markdown-export
---

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

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 للترويسة كما يلي:

```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 هو كما يلي:

```json
{
  "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](https://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 يحتوي على رمز وصول:

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

رمز الوصول المُعاد في حقل `access_token` من كائن JSON هو أيضًا رمز JWT ويجب استخدامه في واجهات برمجة تطبيقات منتجات Unico. إذا حدث خطأ في الطلب، تحقق من نوع الخطأ في [أخطاء المصادقة](./additional-resources/authentication-errors).

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

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

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

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

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

:::note
بشكل افتراضي، يدوم الرمز المُرسل إلى الشركة لمدة ساعة واحدة، ولكن يمكن تغيير ذلك. التوصية هي استخدام `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)
```

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

---

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