ورود یکپارچه (SSO)

سوپر اپلیکیشن مهراد

این سند نحوهٔ ورود کاربران مهراد به سایت یا اپلیکیشن پذیرنده و دریافت اطلاعات پایهٔ آن‌ها را توضیح می‌دهد. ساختار بر پایهٔ OAuth2 و OpenID Connect است و تبادل token به صورت سرور-به-سرور و با امضای HMAC-SHA256 انجام می‌شود.

نحوهٔ عملکرد ورود یکپارچهCopy Anchor Link

نقطهٔ شروع این جریان اپلیکیشن مهراد است، نه سایت پذیرنده:

1. کاربر در اپلیکیشن مهراد وارد حساب خود می‌شود و سرویس و فروشگاه پذیرنده را انتخاب می‌کند.
2. مهراد یک کد موقت (Authorization Code) می‌سازد و کاربر را به آدرس بازگشتی که هنگام راه‌اندازی ثبت شده است هدایت می‌کند. کد داخل همین آدرس قرار می‌گیرد.
3. سرور پذیرنده کد را دریافت می‌کند و آن را در endpoint دریافت token با Access Token و ID Token تعویض می‌کند.
4. با Access Token، اطلاعات مجاز کاربر (پروفایل، آدرس، موجودی) قابل دریافت است و کاربر در سایت پذیرنده وارد می‌شود.

بنابراین آنچه پذیرنده پیاده‌سازی می‌کند، مرحلهٔ ۲ به بعد است: مسیری در سایت پذیرنده که کد را دریافت و پردازش می‌کند.

نکات کلیدیCopy Anchor Link

• آدرس بازگشت پذیرنده یک الگو است که هنگام راه‌اندازی ثبت می‌شود و مهراد کد را داخل آن قرار می‌دهد. شکل نهایی آدرس را مهراد می‌سازد و کاربر را به همان هدایت می‌کند.
• کد موقت ۳۰۰ ثانیه (۵ دقیقه) اعتبار دارد.
• در نسخهٔ فعلی API، parameter state وجود ندارد و مهراد هیچ parameter دیگری به آدرس بازگشت پذیرنده اضافه نمی‌کند. آنچه به سایت پذیرنده می‌رسد، همان الگوی ثبت‌شده به همراه کد است.
• کاربر با یک ناوبری معمولی در همان صفحه به سایت پذیرنده منتقل می‌شود؛ این صفحه یک صفحهٔ وب عادی است و محدودیت خاصی ندارد. مسیر بازگشت خودکار به اپلیکیشن وجود ندارد.

پیش‌نیازهاCopy Anchor Link

پیش از شروع، این موارد باید برای پذیرنده تنظیم شده باشد:

این مقادیر هنگام راه‌اندازی در اختیار پذیرنده قرار می‌گیرد. برای هر ترکیب پذیرنده و سرویس، تنظیمات جداگانه‌ای وجود دارد.

فهرست endpoint‌هاCopy Anchor Link

مرحله ۱ — دریافت کد موقتCopy Anchor Link

کاربر از اپلیکیشن مهراد به آدرس بازگشت پذیرنده هدایت می‌شود و کد موقت در همان آدرس قرار دارد. اقداماتی که سایت پذیرنده باید انجام دهد:

1. کد از آدرس خوانده می‌شود.
2. کد باید بلافاصله از سمت سرور به endpoint دریافت token ارسال شود (مرحلهٔ ۲). کد فقط ۵ دقیقه اعتبار دارد.
3. تا پیش از دریافت موفق token، کاربر نباید وارد شده در نظر گرفته شود.

مرحله ۲ — تبدیل کد به tokenCopy Anchor Link

Authentication: این request به authentication از طریق header نیاز ندارد؛ اصالت آن با client_signature بررسی می‌شود.

ساخت client_signatureCopy Anchor Link

امضا یک HMAC-SHA256 است که روی خودِ کد موقت و با کلید client_secret پذیرنده محاسبه و به صورت hex ارسال می‌شود.

const crypto = require("crypto");

function clientSignature(clientSecret, authorizationCode) {
  return crypto
    .createHmac("sha256", clientSecret)
    .update(authorizationCode)
    .digest("hex");
}

import hashlib
import hmac


def client_signature(client_secret: str, authorization_code: str) -> str:
    return hmac.new(
        key=client_secret.encode("utf-8"),
        msg=authorization_code.encode("utf-8"),
        digestmod=hashlib.sha256,
    ).hexdigest()

اگر بیش از یک کلید فعال برای پذیرنده ثبت شده باشد، امضای تولیدشده با هر کدام از آن‌ها پذیرفته می‌شود. این ویژگی برای تعویض کلید بدون قطعی سرویس در نظر گرفته شده است: ابتدا کلید جدید فعال می‌شود، سرویس به آن منتقل می‌شود و سپس کلید قدیمی غیرفعال می‌شود.

ورودیCopy Anchor Link

{
  "grant_type": "authorization_code",
  "merchant_id": "6c6a2d61-63f1-44a9-9a5e-2b2d9a51f0c7",
  "code": "kGf3t0Zq2m9N1sVb7pXcQwErTyUiOpAsDfGhJkLzXcV",
  "client_signature": "9f1c2d3e4b5a60718293a4b5c6d7e8f90112233445566778899aabbccddeeff0"
}

ResponseCopy Anchor Link

response این endpoint بدون پوشش استاندارد بازگردانده می‌شود:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 43200,
  "scope": "openid profile address balance",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

پردازش responseCopy Anchor Link

• access_token باید روی سرور نگهداری و در مرحلهٔ ۳ استفاده شود. اعتبار آن ۴۳۲۰۰ ثانیه (۱۲ ساعت) است و Refresh Token صادر نمی‌شود؛ پس از انقضا کاربر باید دوباره از اپلیکیشن مهراد وارد شود.
• scope باید بررسی شود و فقط endpoint‌هایی فراخوانی شوند که دسترسی‌شان اعطا شده است.
• id_token هویت کاربر است؛ پیش از اعتماد به آن، باید امضایش بررسی شود (مرحلهٔ ۴).

نکتهٔ زمان‌بندی: مدت اعتبار این token با token اپلیکیشن پذیرنده (۲ ساعت) متفاوت است. جزئیات آن در مستندات ارتباط پذیرندگان آمده است.

مرحله ۳ — دریافت اطلاعات کاربرCopy Anchor Link

هر سه endpoint زیر با Access Token در header Authorization فراخوانی می‌شوند و هرکدام به scope مخصوص خود نیاز دارند. اگر token scope لازم را نداشته باشد، response آن با کد ۴۰۳ و خطای SSO_INSUFFICIENT_SCOPE برگردانده می‌شود.

Authorization: Bearer <access_token>

پروفایل کاربرCopy Anchor Link

scope لازم: profile

{
  "sub": "3f1a9c22-58b4-4f6e-9d77-1b2c3d4e5f60",
  "name": "زهرا محمدی",
  "first_name": "زهرا",
  "last_name": "محمدی",
  "national_code": "0012345678",
  "mobile": "09121234567",
  "birth_date": "1990-05-14"
}

مقدار sub، ID کاربر در مهراد است و در تمام endpoint‌ها ثابت می‌ماند؛ برای اتصال حساب مهراد به حساب کاربر در سیستم پذیرنده باید از همین مقدار استفاده شود، نه از شمارهٔ موبایل یا کد ملی.

birth_date به قالب YYYY-MM-DD (تاریخ میلادی) برگردانده می‌شود. به جز sub، بقیهٔ فیلدها ممکن است null باشند؛ پیاده‌سازی باید این حالت را بپذیرد.

آدرس کاربرCopy Anchor Link

scope لازم: address

{
  "sub": "3f1a9c22-58b4-4f6e-9d77-1b2c3d4e5f60",
  "address": "تهران، خیابان ولیعصر، کوچهٔ بهار، پلاک ۱۲",
  "province": "تهران",
  "city": "تهران",
  "postal_code": "1234567890"
}

اگر آدرسی برای کاربر ثبت نشده باشد، فیلدها null برمی‌گردند.

موجودی کاربرCopy Anchor Link

scope لازم: balance

{
  "sub": "3f1a9c22-58b4-4f6e-9d77-1b2c3d4e5f60",
  "available_balance": 12500000
}

available_balance مجموع دارایی قابل استفادهٔ کاربر برای همان سرویسی است که token برای آن صادر شده و به ریال است. این عدد لحظه‌ای است؛ نباید ذخیره و دوباره استفاده شود و پیش از نمایش سبد خرید باید مجدداً دریافت شود.

مرحله ۴ — اعتبارسنجی ID TokenCopy Anchor Link

id_token با الگوریتم RS256 امضا می‌شود و کلید عمومی آن از JWKS قابل دریافت است:

نمونهٔ محتوای ID Token:

{
  "iss": "https://api.mehrad.app",
  "sub": "3f1a9c22-58b4-4f6e-9d77-1b2c3d4e5f60",
  "aud": "6c6a2d61-63f1-44a9-9a5e-2b2d9a51f0c7",
  "token_type": "sso_id",
  "name": "زهرا محمدی",
  "first_name": "زهرا",
  "last_name": "محمدی",
  "address": "تهران، خیابان ولیعصر، کوچهٔ بهار، پلاک ۱۲",
  "mobile": "09121234567",
  "exp": 1790000000,
  "iat": 1789992800,
  "jti": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9"
}

پیش از اعتماد به محتوای آن باید بررسی شود که: امضا با کلید عمومی معتبر است، iss برابر آدرس سرویس است، aud برابر merchant_id پذیرنده است و exp نگذشته باشد. مدت اعتبار ID Token کوتاه‌تر از Access Token است و برای authentication کاربر در لحظهٔ ورود در نظر گرفته شده، نه برای نگهداری بلندمدت.

بررسی وضعیت token (Introspection)Copy Anchor Link

در نسخهٔ فعلی، برای این endpoint هیچ header مربوط به authentication یا امضایی لازم نیست و request تنها شامل دو فیلد زیر است:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "merchant_id": "6c6a2d61-63f1-44a9-9a5e-2b2d9a51f0c7"
}

response برای token معتبر:

{
  "active": true,
  "scope": "openid profile address balance",
  "merchant_id": "6c6a2d61-63f1-44a9-9a5e-2b2d9a51f0c7",
  "service_id": "2f1b7d6e-2f4e-4a1a-9c22-6f0c0a1d5b31",
  "sub": "3f1a9c22-58b4-4f6e-9d77-1b2c3d4e5f60",
  "exp": 1790000000,
  "iat": 1789956800
}

برای token نامعتبر یا منقضی:

{
  "active": false
}

اگر token برای پذیرندهٔ دیگری صادر شده باشد، response آن با کد ۴۰۱ و خطای SSO_UNAUTHORIZED_CLIENT برگردانده می‌شود.

این endpoint برای بررسی اعتبار tokenهای در اختیار پذیرنده به کار می‌رود.

سند DiscoveryCopy Anchor Link

این سند آدرس endpoint‌ها، الگوریتم امضای ID Token و فهرست scopeهای اعلام‌شده را برمی‌گرداند و عمومی است.

ScopeهاCopy Anchor Link

فهرست scopeهایی که سند Discovery اعلام می‌کند:

نکات مهم:

• scopeها هنگام راه‌اندازی برای ترکیب پذیرنده و سرویس تنظیم می‌شوند؛ در request دریافت token، مقداری برای انتخاب scope ارسال نمی‌شود.
• scopeهای اعطاشده در فیلد scope از response دریافت token برگردانده می‌شوند و همین مقدار مبنای تصمیم‌گیری است.

فهرست خطاهاCopy Anchor Link

اگر request با خطا مواجه شود، response آن کدی غیر از ۲xx دارد و success در آن false است. کد خطا در فیلد error.code و متن قابل نمایش در error.message برگردانده می‌شود. ساختار کامل خطا در بخش مقدمه آمده است. endpoint‌های Discovery و JWKS خطای اختصاصی ندارند.

تبدیل کد به tokenCopy Anchor Link

{
  "success": false,
  "error": {
    "code": "SSO_INVALID_GRANT",
    "message": "این کد موقت دیگر معتبر نیست یا زمانش تمام شده است.",
    "details": null
  }
}

بررسی وضعیت tokenCopy Anchor Link

{
  "success": false,
  "error": {
    "code": "SSO_UNAUTHORIZED_CLIENT",
    "message": "امضای امنیتی درخواست با هیچ‌یک از کلیدهای ثبت‌شده برای این پذیرنده همخوانی ندارد.",
    "details": null
  }
}

اطلاعات کاربرCopy Anchor Link

{
  "success": false,
  "error": {
    "code": "SSO_INSUFFICIENT_SCOPE",
    "message": "شما به این بخش دسترسی ندارید.",
    "details": {
      "required_scope": "balance"
    }
  }
}

نکات امنیتی و عملیاتیCopy Anchor Link

• client_secret و token‌ها فقط باید روی سرور نگهداری شوند؛ نباید در کد سمت مرورگر یا اپلیکیشن موبایل قرار گیرند.
• تبادل کد با token باید سرور-به-سرور انجام شود.
• کد موقت عمر کوتاهی دارد؛ نباید لاگ شود و باید بلافاصله مصرف شود.
• مقادیر exp و iat token‌ها باید همواره بررسی شوند.
• کاربر باید با sub به حساب داخلی پذیرنده متصل شود.

چک‌لیست پیاده‌سازیCopy Anchor Link

• دریافت merchant_id، client_secret و ثبت آدرس بازگشت
• پیاده‌سازی مسیر دریافت کد موقت در سایت
• ساخت client_signature به روش HMAC-SHA256 روی کد موقت
• فراخوانی POST /gateway/sso/token از سمت سرور و مدیریت خطاهای آن
• اعتبارسنجی امضا، iss، aud و exp در id_token
• اتصال کاربر به حساب داخلی بر اساس sub
• خواندن scope response و فراخوانی endpoint‌های مجاز
• مدیریت انقضای Access Token پس از ۱۲ ساعت و نبود Refresh Token
• نگهداری امن کلید و token‌ها روی سرور