المصادقة

تستخدم جميع واجهات برمجة تطبيقات 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
Node.js
Python

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..."

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();

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 — إنشاء عملية — أول استدعاء بعد المصادقة
SSO / SAML — مصادقة مستخدميك في بوابات منتجات Unico باستخدام مزوّد الهوية الخاص بشركتك، بدلاً من تدفق الخادم إلى الخادم أعلاه

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

بناء تأكيد JWT​

طلب الرمز​

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

تجديد الرمز​

مرجع API​

رموز الخطأ​

ما التالي​