دليل OAuth معاينة

نظرة عامة

• OAuth 2.0 بتدفق رمز التفويض مع PKCE (S256 فقط).
• الرموز معتمة (ليست JWT) ومُخزّنة مُجزّأة لدينا، فالإلغاء يسري فوراً. لا تحاول تحليلها.
• رمز الوصول مرتبط بثلاثة: تطبيقك، والشركة، والصلاحيات الممنوحة.
• تقبل /v1 الترويسة Authorization: Bearer <token> إلى جانب مفاتيح ah_.

1. سجّل تطبيقك

في لوحة المطوّر تنشئ تطبيقاً داخل مؤسسة المطوّر الخاصة بك وتحصل على client_id وclient_secret. السرّ يظهر مرة واحدة ويمكنك تدويره. سجّل روابط إعادة التوجيه بدقة — المطابقة حرفية — واختر الصلاحيات التي يطلبها التطبيق. التطبيق الجديد في وضع التطوير ويتصل فقط بشركات التجربة الخاصة بمؤسستك.

2. أرسل المستخدم إلى رابط التفويض

أنشئ code_verifier عشوائياً لكل محاولة واحتفظ به في خادمك، واحسب منه code_challenge، وأرسل state عشوائياً وتحقق منه عند العودة.

import crypto from "node:crypto";

// 1. A fresh verifier per authorization attempt; keep it server-side.
const codeVerifier = crypto.randomBytes(32).toString("base64url");
const codeChallenge = crypto
  .createHash("sha256")
  .update(codeVerifier)
  .digest("base64url");
const state = crypto.randomBytes(16).toString("base64url");

// 2. Send the user's browser here.
const url = new URL("/oauth/authorize", process.env.AH_AUTH_HOST);
url.search = new URLSearchParams({
  response_type: "code",
  client_id: process.env.AH_CLIENT_ID,
  redirect_uri: "https://yourapp.example/callback/ahlan-hamad",
  scope: "employees:read payroll:read",
  state,
  code_challenge: codeChallenge,
  code_challenge_method: "S256",
}).toString();

يسجّل المستخدم الدخول إلى أهلاً حمد. مستخدم لديه صلاحية integrations.manage يختار الشركة، ويرى اسم تطبيقك والصلاحيات المطلوبة، ثم يوافق أو يرفض. نعيده إلى رابطك:

https://yourapp.example/callback/ahlan-hamad?code=…&state=…
https://yourapp.example/callback/ahlan-hamad?error=access_denied&state=…

3. استبدل الرمز برموز

رمز التفويض صالح لاستخدام واحد ولمدة 60 ثانية. استبدله من خادمك مع نفس redirect_uri وcode_verifier.

curl -X POST "$AH_AUTH_HOST/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://yourapp.example/callback/ahlan-hamad" \
  -d code_verifier="$CODE_VERIFIER" \
  -d client_id="$AH_CLIENT_ID" \
  -d client_secret="$AH_CLIENT_SECRET"

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "employees:read payroll:read"
}

قيمة expires_in في المثال توضيحية؛ مدد الصلاحية تُحدَّد عند الإطلاق.

4. استدعِ الـ API

curl https://actions.ahlanhamad.com/v1/company \
  -H "Authorization: Bearer $ACCESS_TOKEN"

نفس نقاط النهاية ونفس فحص الصلاحيات ونفس حدّ الطلبات ونفس أخطاء problem+json كما مع مفاتيح API. رمز ملغى أو منتهي يُرجع 401 unauthenticated.

5. حدّث الرموز

curl -X POST "$AH_AUTH_HOST/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN" \
  -d client_id="$AH_CLIENT_ID" \
  -d client_secret="$AH_CLIENT_SECRET"

• رموز التحديث تتجدد: كل تحديث يُرجع رمز تحديث جديداً ويُبطل القديم. احفظ الجديد قبل استخدام رمز الوصول.
• كشف إعادة الاستخدام: تقديم رمز تحديث سبق استخدامه يُلغي سلسلة الرموز كلها لهذا الاتصال، ويجب أن يوافق العميل من جديد. احرص على أن يحدّث عامل واحد فقط في كل مرة.
• يمكن طلب صلاحيات أقل مما مُنح عند التحديث، ولا يمكن طلب أكثر.

6. الإلغاء

curl -X POST "$AH_AUTH_HOST/oauth/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d token="$REFRESH_TOKEN" \
  -d client_id="$AH_CLIENT_ID" \
  -d client_secret="$AH_CLIENT_SECRET"

ألغِ الرموز عندما يفصل العميل حسابه من منتجك. يستطيع العميل أيضاً إلغاء تطبيقك من صفحة التطبيقات المتصلة؛ عندها تتوقف الرموز فوراً ويُعطَّل الويب هوك الخاص بهذا الاتصال.

الصلاحيات

نفس صلاحيات مفاتيح API. GET /v1/company لا يحتاج صلاحية. اطلب أقل ما يحتاجه تكاملك — العميل يرى القائمة قبل الموافقة.

لا يوجد أي مسار — مفتاح أو OAuth — يُرجع رواتب أو بدلات الموظفين الفردية.

الأخطاء

أخطاء /oauth/token و/oauth/revoke تتبع صيغة OAuth القياسية (RFC 6749 §5.2): error وerror_description. أخطاء رابط التفويض تُعاد إلى redirect_uri كمعاملات استعلام، إلا إذا كان الرابط نفسه أو client_id غير صالح، فتظهر للمستخدم ولا يُعاد توجيهه.

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired or was already used"
}