المصادقة

تستخدم جميع واجهات برمجة تطبيقات IDCloud (عقدا Web & SDK و API) OAuth2 مع نوع منح JWT Bearer (RFC 7523). تقوم بإنشاء تأكيد JWT قصير الأجل على الخادم الخلفي الخاص بك، وتبادله برمز Bearer، ثم تستخدم هذا الرمز في كل استدعاء لاحق.

لا تقم بذلك أبدًا على جانب العميل

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

الحصول على بيانات الاعتماد

قبل أن تتمكن من إنشاء الرموز، تحتاج إلى حساب خدمة يتم توفيره بواسطة Unico. تواصل مع دعم Unico وقدّم:

• اسم حساب الخدمة (بحد أقصى 12 حرفًا)
• اسم الشخص المسؤول، بريده الإلكتروني ورقم هاتفه (أرقام البرازيل أو الولايات المتحدة أو المكسيك فقط)

ستحصل على:

• اسم حساب فريد
• معرف المستأجر (Tenant ID)
• حمولة JWT الأساسية
• ملف المفتاح الخاص (بصيغة .pem)

حساب لكل بيئة

احتفظ بحسابات خدمة منفصلة لبيئتي UAT والإنتاج.

بناء تأكيد JWT

التأكيد هو JWT بصيغة JWS المضغوطة: {Base64url(Header)}.{Base64url(Payload)}.{Base64url(Signature)}.

Header

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

Payload

الحقل	القيمة	ملاحظات
iss	<account_name>@<tenant_id>.iam.acesso.io	مُقدَّم مع بيانات الاعتماد الخاصة بك
aud	https://identityhomolog.acesso.io (UAT) أو https://identity.acesso.io (الإنتاج)	يجب أن يتطابق مع مضيف نقطة نهاية الرمز
scope	*	يمنح جميع الأذونات
iat	الطابع الزمني Unix (بالثواني)	وقت إصدار JWT
exp	iat + بحد أقصى 3600	لا يمكن تجاوز ساعة واحدة من iat

{
  "iss": "[email protected]",
  "aud": "https://identity.acesso.io",
  "scope": "*",
  "iat": 1738086000,
  "exp": 1738089600
}

Signature

قم بتوقيع الترويسة والحمولة باستخدام RS256 (RSA + SHA-256) مع المفتاح الخاص .pem المُقدَّم من Unico.

لا تضف حقولًا إضافية

أي حقل غير مُدرج أعلاه (مثل sub أو jti أو nbf) سيُسبب خطأ 1.2.22. استخدم الحقول المُوضحة فقط.

طلب الرمز

نقطة نهاية الرمز هي نفسها لكلا العقدين:

البيئة	نقطة النهاية
الإنتاج	POST https://identity.acesso.io/oauth2/token
UAT	POST https://identityhomolog.acesso.io/oauth2/token

Request

المعامل	القيمة
Content-Type	application/x-www-form-urlencoded
grant_type	urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	JWT الموقَّع الخاص بك

cURL

curl -X POST https://identity.acesso.io/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  -d "assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Node.js

import jwt from 'jsonwebtoken';
import fs from 'fs';
import qs from 'querystring';

const privateKey = fs.readFileSync('./private-key.pem');
const now = Math.floor(Date.now() / 1000);

const assertion = jwt.sign(
  {
    iss: '[email protected]',
    aud: 'https://identity.acesso.io',
    scope: '*',
    iat: now,
    exp: now + 3600,
  },
  privateKey,
  { algorithm: 'RS256' }
);

const res = await fetch('https://identity.acesso.io/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: qs.stringify({
    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
    assertion,
  }),
});

const { access_token, expires_in } = await res.json();

Python

import time
import jwt  # PyJWT
import requests

with open("private-key.pem", "rb") as f:
    private_key = f.read()

now = int(time.time())

assertion = jwt.encode(
    {
        "iss": "[email protected]",
        "aud": "https://identity.acesso.io",
        "scope": "*",
        "iat": now,
        "exp": now + 3600,
    },
    private_key,
    algorithm="RS256",
)

response = requests.post(
    "https://identity.acesso.io/oauth2/token",
    data={
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "assertion": assertion,
    },
)

token_data = response.json()
access_token = token_data["access_token"]

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

الحقل	النوع	الوصف
access_token	string	رمز وصول JWT. استخدمه في Authorization: Bearer <token> في جميع استدعاءات API.
expires_in	integer	وقت انتهاء الصلاحية بالثواني. مثال: 3600.
token_type	string	دائمًا Bearer.

استخدام الرمز

أضف الرمز إلى ترويسة Authorization في كل طلب API. الترويسة متطابقة لكلا العقدين — ما يختلف هو المضيف والمسار لواجهة برمجة التطبيقات التي تستدعيها:

العقد	مضيف الإنتاج	مضيف UAT
Web & SDK	https://api.idcloud.unico.app	https://api.idcloud.uat.unico.app
API	https://api.id.unico.app	https://api.id.uat.unico.app

Web & SDK — Authorization هي ترويسة المصادقة الوحيدة المطلوبة:

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

API — تُستخدم Authorization إلى جانب ترويسة APIKEY:

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

تجديد الرمز

تنتهي صلاحية الرموز بعد 3600 ثانية. طبّق التجديد الاستباقي في الخادم الخلفي الخاص بك:

• تتبع expires_in من استجابة الرمز وقم بتخزين طابع انتهاء الصلاحية.
• اطلب رمزًا جديدًا عندما يتبقى 10 دقائق أو أقل قبل انتهاء الصلاحية.
• لا تنتظر أبدًا حدوث خطأ 401 في الإنتاج لبدء التجديد.

مرجع API

المواصفات الكاملة لـ OpenAPI الخاصة بنقطة نهاية الرمز متاحة في authentication.yaml.

الطريقة	المسار	الوصف
POST	/oauth2/token	تبادل تأكيد JWT موقَّع للحصول على رمز وصول Bearer

رموز الخطأ

الرمز	الوصف	الإجراء
1.0.1	المعرف المُقدَّم في تكوين iss غير صحيح	تحقق من أن حقل iss يطابق معرف المستأجر المُقدَّم عند إنشاء المفتاح الخاص
1.0.14	التطبيق غير نشط	تحقق مع مدير المشروع ما إذا كان التطبيق المستخدم نشطًا
1.1.1	لم يتم توفير معامل scope	أضف "scope": "*" إلى حمولة JWT الخاصة بك
1.2.4	تأكيد JWT غير صالح	تأكيد JWT لم يعد صالحاً. سببان: (أ) الوقت الحالي تجاوز exp (انتهت صلاحية JWT فعلاً — أنشئ تأكيداً جديداً لكل طلب رمز)؛ أو (ب) تتجاوز exp قيمة iat + 3600 (مدة الصلاحية طويلة جداً — حدد exp بـ iat + 3600 كحد أقصى).
1.2.5	فشل التحقق من JWT	لا يمكن التحقق من JWT. تحقق من المعاملات وتأكد من توقيعه بـ RS256 والمفتاح الخاص الصحيح
1.2.6	المفتاح الخاص لم يعد صالحًا	المفتاح الخاص المستخدم لتوقيع JWT لم يعد مقبولًا. اطلب بيانات اعتماد جديدة للحساب
1.2.7	JWT مستخدم بالفعل	JWT لم يعد مقبولًا لأنه استُخدم بالفعل. أنشئ تأكيدًا جديدًا لكل طلب رمز
1.2.11	الحساب غير نشط	الحساب المستخدم غير نشط
1.2.14	الحساب يفتقر إلى الأذونات اللازمة	الحساب المستخدم لا يملك الأذونات اللازمة
1.2.18	الحساب مقفل مؤقتًا	تم قفل الحساب مؤقتًا بسبب تجاوز عدد محاولات المصادقة غير الصالحة
1.2.19	انتحال هوية مستخدم غير مصرح به	يحتوي JWT على حقل sub يُشير إلى حساب غير مصرح له بانتحال الهوية. احذف حقل sub من الحمولة.
1.2.20	فشل فك تشفير JWT	فشل فك تشفير JWT. تحقق من تنسيق الرمز وأنه موقَّع بـ RS256.
1.2.21	مفتاح خاص خاطئ / فشل المصادقة	تعذّر التحقق من توقيع JWT مقابل أي مفتاح معروف لهذا الحساب. تأكد من استخدام ملف .pem الصحيح لحساب الخدمة والبيئة المناسبة.
1.2.22	حقول غير مسموح بها في الحمولة	يحتوي JWT على حقول حمولة إضافية غير مسموح بها. احذف أي حقول غير مُدرجة في هذا الدليل (مثل sub، jti، nbf). ملاحظة: إذا أدرجت حقل sub وظهر لك الخطأ 1.2.19 بدلاً منه، فذلك الخطأ يأخذ الأولوية.
1.3.1	قيود الوصول عبر IP	عنوان IP الخاص بك ليس في القائمة البيضاء لهذا الحساب
1.3.2	قيود الوصول بناءً على الوقت	الطلب خارج نافذة الوقت المسموح بها لهذا الحساب

ما التالي

• البيئات — مضيفو sandbox مقابل الإنتاج
• Web & SDK — إنشاء عملية — أول استدعاء بعد المصادقة
• API — إنشاء عملية — أول استدعاء بعد المصادقة