الگوهای پیشرفته احراز هویت — OAuth 2.0، JWT، چرخش کلید

تسلط بر مکانیزم‌های پیچیده احراز هویت برای ادغام Smart Money API در محیط‌های سازمانی. یادگیری جریان‌های OAuth 2.0، الگوهای توکن JWT، چرخش ایمن کلید و پیاده‌سازی احراز هویت چندعاملی.

منتشر شده در ۲۱ مارس ۲۰۲۶ ۱۸ دقیقه مطالعه پیشرفته

مرور احراز هویت

Smart Money API از چندین روش احراز هویت پشتیبانی می‌کند که برای تطابق با معماری‌های مختلف برنامه، نیازمندی‌های امنیتی و سیاست‌های سازمانی طراحی شده‌اند. درک این الگوها تضمین می‌کند که ادغام شما هم ایمن و هم کارآمد است.

احراز هویت در Smart Money API در سه لایه اصلی عمل می‌کند:

  • کلیدهای API — احراز هویت ساده با توکن Bearer برای توسعه و ادغام‌های مستقیم
  • توکن‌های JWT — توکن‌های بدون حالت و امضا شده رمزنگاری برای سیستم‌های توزیع‌شده و میکروسرویس‌ها
  • OAuth 2.0 — چارچوب مجوزدهی تفویض‌شده برای ادغام‌های شخص ثالث و برنامه‌های SaaS

اصل امنیتی: هرگز اطلاعات احراز هویت را در کد سمت کلاینت، لاگ‌ها، کنترل نسخه یا پیام‌های خطا قرار ندهید. چرخش اعتبار را بر اساس برنامه و بلافاصله پس از نقض امنیتی پیاده‌سازی کنید.

هر روش مزایای متمایزی دارد. کلیدهای API برای ارتباط backend-to-backend که ذخیره اعتبار تحت کنترل است، بهترین کارایی را دارند. توکن‌های JWT در معماری‌های توزیع‌شده که حالت اشتراکی وجود ندارد، عالی عمل می‌کنند. OAuth 2.0 دسترسی تفویض‌شده کاربر را برای برنامه‌های شخص ثالث فراهم می‌کند.

احراز هویت با کلید API

کلیدهای API ساده‌ترین مکانیزم احراز هویت هستند—آن‌ها رشته‌های تصادفی هستند که برای حساب شما تولید می‌شوند و برنامه شما را به Smart Money API معرفی می‌کنند. هر درخواست باید شامل کلید API شما باشد، چه در هدر و چه در پارامتر کوئری.

کلید API مبتنی بر هدر

روش توصیه‌شده، ارسال کلید API در هدر Authorization با استفاده از طرح Bearer است:

مثال curl
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"

کلید API به عنوان پارامتر کوئری

برای اتصالات WebSocket یا زمانی که هدرها قابل تغییر نیستند، کلید API را به عنوان پارامتر کوئری ارسال کنید:

اتصال WebSocket
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// جریان WebSocket احراز هویت شده را برقرار می‌کند

ویژگی‌های کلید API

ویژگی توضیح
فرمت رشته hex ۱۲۸ کاراکتری با پیشوند sk_test_ یا sk_live_
حوزه تمام مجوزهای حساب ایجادکننده را به ارث می‌برد
انقضا به‌صورت خودکار منقضی نمی‌شود؛ باید به‌صورت دستی چرخش یابد
چرخش کلید جدید ایجاد کنید، ترافیک را انتقال دهید، سپس کلید قدیمی را غیرفعال کنید
محدودیت نرخ بین تمام درخواست‌هایی که از همان کلید استفاده می‌کنند، مشترک است

روش‌های امنیتی کلید API

  • متغیرهای محیطی — کلیدها را در فایل‌های .env ذخیره کنید (در کنترل نسخه commit نشود) و در زمان اجرا بارگیری کنید
  • سیستم‌های مخزن — در محیط تولید از HashiCorp Vault، AWS Secrets Manager یا Azure Key Vault استفاده کنید
  • کلیدهای جداگانه — کلیدهای تست و عملیاتی جداگانه نگه دارید؛ کلیدهای تست را به‌طور مکرر چرخش دهید
  • حوزه حداقلی — در صورت امکان، کلیدهای جداگانه برای ادغام‌های مختلف ایجاد کنید
  • ثبت وقایع حسابرسی — تمام رویدادهای ایجاد و استفاده از کلید API را ثبت کنید
کلید API خود را در ۳۰ ثانیه دریافت کنید

آماده ساخت هستید؟ یک کلید API رایگان دریافت کنید (۵۰ درخواست در روز، بدون نیاز به کارت) و شروع به دریافت داده‌های زنده نهنگ‌ها، تأمین مالی و زنجیره‌ای کنید.

دریافت کلید API →

الگوی توکن Bearer

توکن‌های Bearer مفهوم ساده کلید API را با افزودن زمینه، انقضا و مکانیزم‌های تمدید گسترش می‌دهند. آن‌ها برای برنامه‌هایی که نیاز به مدیریت اعتبار برنامه‌نویسی دارند، ایده‌آل هستند.

دریافت توکن‌های Bearer

کلید API و رمز خود را با یک توکن Bearer معتبر برای ۲۴ ساعت تعویض کنید:

GET /auth/token
curl -X POST "https://api.smartmoneyapi.com/v1/auth/token" \
-H "Content-Type: application/json" \
-d '{
"api_key": "sk_live_1234567890",
"api_secret": "secret_abc123xyz"
}'

فرمت پاسخ توکن

این نقطه پایانی یک توکن Bearer با ابرداده برمی‌گرداند:

پاسخ
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}

استفاده از توکن‌های Bearer

توکن را در هدر Authorization برای تمام درخواست‌های بعدی قرار دهید:

درخواست احراز هویت شده
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

جریان تمدید توکن

زمانی که توکن نزدیک به انقضا است، از توکن تمدید برای دریافت توکن جدید بدون نیاز به رمز API استفاده کنید:

POST /auth/refresh
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'

پیاده‌سازی OAuth 2.0

OAuth 2.0 به کاربران اجازه می‌دهد تا به برنامه‌ها دسترسی به حساب‌های Smart Money API خود را بدون اشتراک‌گذاری اعتبارها اعطا کنند. این برای پلتفرم‌های SaaS، ادغام‌های شخص ثالث و برنامه‌های چندمستاجری ضروری است.

جریان کد مجوز OAuth 2.0

جریان استاندارد برای برنامه‌های وب:

  1. کارگر ورود را آغاز می‌کند — کاربر روی "اتصال با Smart Money API" کلیک می‌کند
  2. تغییر مسیر به سرور مجوز — برنامه شما کاربر را به نقطه پایانی مجوز Smart Money تغییر مسیر می‌دهد
  3. کارگر مجوز می‌دهد — کاربر محدوده‌های درخواست‌شده را بررسی و دسترسی را اعطا می‌کند
  4. کد مجوز برگردانده می‌شود — کاربر با کد مجوز به عقب تغییر مسیر داده می‌شود
  5. تبدیل کد به توکن — backend کد را با توکن دسترسی تعویض می‌کند (کد هرگز در frontend نمایش داده نمی‌شود)
  6. ذخیره توکن — توکن رفرش را به صورت امن ذخیره کنید؛ از توکن دسترسی برای فراخوانی‌های API استفاده کنید

مرحله ۱: هدایت کاربر به نقطه پایان احراز هویت

هدایت فرانت‌اند
// آدرس برای هدایت کاربر
const authUrl = new URL('https://api.smartmoneyapi.com/oauth/authorize');
authUrl.searchParams.append('client_id', 'your_client_id');
authUrl.searchParams.append('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.append('response_type', 'code');
authUrl.searchParams.append('scope', 'whales derivatives onchain');
authUrl.searchParams.append('state', generateRandomState());
window.location.href = authUrl.toString();

مرحله ۲: مدیریت پاسخ و تبادل کد

تبادل کد بک‌اند
// بک‌اند مسیر /callback را مدیریت می‌کند
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// بررسی پارامتر state
if (storedState !== receivedState) {
throw new Error('State mismatch - CSRF attack detected');
}
// تبادل کد برای توکن
const tokenResponse = await fetch('https://api.smartmoneyapi.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
grant_type: 'authorization_code',
code: code,
client_id: process.env.OAUTH_CLIENT_ID,
client_secret: process.env.OAUTH_CLIENT_SECRET,
redirect_uri: 'https://yourapp.com/callback'
})
});
const tokens = await tokenResponse.json();
// ذخیره امن توکن‌ها

حوزه‌های OAuth

فقط حوزه‌هایی که برنامه شما نیاز دارد را درخواست کنید. Smart Money API این حوزه‌ها را تعریف می‌کند:

حوزه توضیح
whales دسترسی به ردیابی کیف‌پول نهنگ‌ها و معیارهای تجمیع
derivatives دسترسی به داده‌های فیوچرز، پرپچوال‌ها و نرخ تأمین مالی
onchain دسترسی به جریان‌های تراکنش و تحلیل‌های زنجیره‌ای
alerts ایجاد و مدیریت هشدارهای وب‌هوک
offline دسترسی به توکن‌های رفرش برای دریافت توکن‌های دسترسی آفلاین

مدیریت توکن JWT

JWT (توکن‌های وب JSON) احراز هویت بدون حالت را فراهم می‌کنند—سرور نیازی به ذخیره داده‌های جلسه ندارد. Smart Money API از RS256 (امضای RSA با SHA-256) برای امضای توکن استفاده می‌کند که امکان تأیید بدون تماس با API را فراهم می‌کند.

ساختار JWT

توکن‌های JWT از سه بخش جدا شده با نقطه تشکیل شده‌اند:

فرمت JWT
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// HEADER.PAYLOAD.SIGNATURE

هدر JWT

هدر الگوریتم و نوع توکن را مشخص می‌کند:

هدر رمزگشایی شده
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}

ادعاهای محموله JWT

محموله شامل ادعاها (اظهارات درباره کاربر/برنامه) است:

محموله رمزگشایی شده
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}

تأیید امضاهای JWT

کلید عمومی Smart Money را دانلود کنید و توکن‌ها را قبل از پذیرش تأیید کنید:

تأیید در Node.js
const jwt = require('jsonwebtoken');
const fs = require('fs');
// دریافت کلید عمومی از Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// تأیید توکن
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// توکن معتبر است، از ادعاهای رمزگشایی شده استفاده کنید
} catch (err) {
// توکن نامعتبر یا منقضی شده است
}

استراتژی چرخش کلید

چرخش منظم کلید برای حفظ امنیت حیاتی است. حتی با بهترین روش‌های امنیتی، فرض کنید کلیدها ممکن است به خطر بیفتند و چرخش سیستماتیک را پیاده‌سازی کنید.

فرکانس چرخش

Smart Money برنامه‌های چرخش مختلفی را بر اساس نوع کلید و استفاده توصیه می‌کند:

نوع کلید چرخش توصیه شده حداقل چرخش
کلیدهای API آزمایشی ماهانه سه‌ماهه
کلیدهای API تولیدی سه‌ماهه سالانه
توکن‌های رفرش OAuth خودکار (پس از ۹۰ روز) دستی (پس از ۱۸۰ روز)
کلیدهای حساب سرویس نیم‌سالانه سالانه

فرآیند چرخش بدون وقفه

کلیدها را بدون وقفه در سرویس بچرخانید:

  1. ایجاد کلید جدید — ایجاد کلید API جدید از طریق داشبورد یا API
  2. استقرار کلید جدید — به‌روزرسانی رمزهای برنامه در محیط آزمایشی، تست کامل
  3. رول‌آوت تدریجی — استقرار روی ۱۰٪ سرورها، نظارت بر خطاها
  4. راه‌اندازی کامل — استقرار در سرورهای باقی‌مانده
  5. تأیید ترافیک — تأیید استفاده از کلید جدید برای تمام درخواست‌ها
  6. غیرفعال کردن کلید قدیمی — علامت‌گذاری کلید قدیمی به عنوان غیرفعال اما عدم حذف فوری
  7. حذف کلید قدیمی — پس از 48 ساعت بدون خطا، حذف دائمی

چرخش اضطراری کلید

اگر مشکوک به افشای کلید هستید:

چرخش اضطراری
// اقدام فوری: غیرفعال کردن کلید افشا شده
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// ایجاد کلید جایگزین فوری
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "کلید جایگزین اضطراری"
}'

چرخش خودکار در Kubernetes

از Kubernetes Secrets و اپراتورها برای چرخش خودکار استفاده کنید:

CronJob برای چرخش کلید
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # هفتگی در روز یکشنبه
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest

احراز هویت چندعاملی (MFA)

برای حساب‌های دسترسی به داده‌های تولید، MFA با نیاز به عامل دوم علاوه بر اعتبارنامه‌ها، لایه امنیتی اضافه فراهم می‌کند.

روش‌های پشتیبانی شده MFA

  • TOTP (رمز یکبار مصرف زمان‌بندی شده) — برنامه‌هایی مانند Google Authenticator, Authy
  • WebAuthn/FIDO2 — کلیدهای امنیتی سخت‌افزاری، بیومتریک
  • کدهای یکبار مصرف SMS — امنیت کمتر اما پشتیبانی جهانی
  • تأیید ایمیل — کدهای تأیید ارسال شده به ایمیل ثبت‌شده

فعال‌سازی TOTP برای دسترسی به حساب

فعال‌سازی MFA
// مرحله 1: درخواست تنظیم MFA
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// پاسخ شامل URL کد QR است
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}

MFA در عملیات API

برخی عملیات ممکن است نیاز به تأیید MFA حتی پس از احراز هویت داشته باشند:

چالش MFA
// تلاش برای عملیات حساس (چرخش کلید)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// پاسخ: نیاز به MFA
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// تلاش مجدد با کد TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"

بهترین روش‌های امنیتی

احراز هویت تنها به اندازه پیاده‌سازی آن قوی است. این روش‌ها را برای حفظ امنیت دنبال کنید:

مدیریت اسرار

  • هرگز اسرار را در کنترل نسخه ثبت نکنید — استفاده از فایل‌های .env با .gitignore
  • استفاده از متغیرهای محیطی — بارگیری از سیستم‌های مدیریت اسرار امن
  • اسکن مخازن — استفاده از ابزارهایی مانند TruffleHog, detect-secrets برای یافتن کلیدهای افشا شده
  • بررسی لاگ‌های دسترسی — نظارت بر اینکه چه کسی و چه زمانی به اسرار دسترسی داشته است

امنیت انتقال

  • همیشه از HTTPS استفاده کنید — هرگز اعتبارنامه‌ها را روی اتصالات رمزنگاری نشده ارسال نکنید
  • تأیید گواهی‌های SSL — غیرفعال کردن تأیید گواهی در محیط تولید ممنوع
  • استفاده از certificate pinning — برای برنامه‌های موبایل، جلوگیری از حملات MITM
  • اجبار به TLS 1.2+ — غیرفعال کردن پروتکل‌های قدیمی

مدیریت اعتبارنامه

  • هش کردن اسرار — ذخیره هش‌های bcrypt یا Argon2، هرگز متن ساده
  • کاهش طول عمر — نگه‌داری اعتبارنامه‌ها در حافظه تنها به مدت نیاز
  • پاک‌سازی داده‌های حساس — بازنویسی صریح اعتبارنامه‌ها پس از استفاده
  • استفاده از کتابخانه‌های امن — پیاده‌سازی رمزنگاری خودتان انجام ندهید

ثبت و نظارت

  • هرگز اعتبارنامه‌ها را ثبت نکنید — حذف کلیدها در لاگ‌ها، استفاده از ماسک لاگ
  • ثبت رویدادهای احراز هویت — ردیابی تلاش‌های ورود موفق و ناموفق
  • نظارت بر ناهنجاری‌ها — هشدار در مورد الگوهای دسترسی غیرمعمول
  • بررسی استفاده از کلید — ردیابی اینکه کدام کلیدها به چه داده‌هایی دسترسی داشته‌اند

الگوهای احراز هویت سازمانی

سازمان‌های بزرگ اغلب به کنترل‌های امنیتی اضافی و قابلیت‌های انطباق نیاز دارند.

ادغام SAML 2.0

برای مشتریان سازمانی، Smart Money API از ادغام SAML 2.0 با ارائه‌دهنده هویت سازمان شما (Okta, Azure AD و غیره) پشتیبانی می‌کند:

  • ورود یک‌باره (SSO) — کاربران از طریق IdP سازمانی شما احراز هویت می‌کنند
  • تهیه خودکار — ایجاد/غیرفعال کردن حساب‌ها بر اساس عضویت گروه
  • اجبار — نیاز به SAML برای تمام دسترسی‌های کاربر

لیست سفید IP

محدود کردن دسترسی API به آدرس‌های IP یا محدوده‌های CIDR خاص

مدیریت لیست سفید IP
// افزودن IP به لیست سفید
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "سرورهای تولید"
}'

ثبت وقایع و انطباق

طرح‌های سازمانی شامل گزارش‌های جامع ثبت وقایع برای انطباق هستند:

رویداد داده‌های ثبت شده
احراز هویت کاربر، زمان، موفقیت/شکست، IP، وضعیت MFA
عملیات کلیدی شناسه کلید، اقدام، آغازگر، زمان
تغییرات حساب چه چیزی تغییر کرده، چه کسی آن را تغییر داده، زمان، مقادیر قبل/بعد
دسترسی به داده‌ها کاربر، نقطه پایانی، محدوده‌ها، زمان، تعداد رکوردها

رفع مشکلات احراز هویت

خطای کلید API نامعتبر

مشکل: دریافت "401 Unauthorized - Invalid API Key"

راه‌حل‌ها:

  • بررسی فرمت کلید (باید با sk_test_ یا sk_live_ شروع شود)
  • بررسی وجود فاصله خالی در ابتدا یا انتهای کلید
  • تأیید اینکه کلید غیرفعال یا چرخش نشده است
  • تأیید اینکه از محیط صحیح استفاده می‌کنید (کلید تست برای محیط تست، کلید زنده برای تولید)
  • بررسی تطابق مجوزهای کلید API با نیازهای نقطه پایانی

خطای منقضی شدن توکن

مشکل: توکن Bearer منقضی شده است، درخواست‌ها با شکست مواجه می‌شوند

راه‌حل‌ها:

  • استفاده از توکن بازنشانی برای دریافت توکن دسترسی جدید
  • پیاده‌سازی بازنشانی خودکار توکن 5 دقیقه قبل از انقضا
  • ذخیره ایمن توکن بازنشانی (نه در localStorage برای برنامه‌های تک صفحه‌ای)
  • مدیریت پاسخ‌های 401 با تلاش برای جریان بازنشانی توکن

خطاهای CORS/Preflight

مشکل: مرورگر درخواست‌ها را با خطای CORS مسدود می‌کند

راه‌حل‌ها:

  • تماس‌های API از مرورگر باید از منابع مجاز باشند
  • افزودن دامنه خود از طریق داشبورد: تنظیمات → منابع CORS
  • مرورگر به طور خودکار درخواست OPTIONS preflight را ارسال می‌کند
  • برای توسعه، از localhost:3000 یا مشابه استفاده کنید

عدم تکمیل چالش MFA

مشکل: عملیات‌هایی که نیاز به MFA دارند حتی با کد صحیح با شکست مواجه می‌شوند

راه‌حل‌ها:

  • اطمینان از همگام‌سازی ساعت سرور (TOTP به زمان وابسته است)
  • کد فقط برای 30 ثانیه معتبر است، کد جدید ایجاد کنید
  • در صورت عدم دسترسی به برنامه احراز هویت، از کدهای پشتیبان استفاده کنید
  • بازیابی حساب از طریق ایمیل ثبت‌شده امکان‌پذیر است

امروز احراز هویت ایمن را پیاده‌سازی کنید

Smart Money API از احراز هویت در سطح سازمانی با OAuth 2.0، JWT، MFA و ادغام SAML پشتیبانی می‌کند. ادغام API خود را با بهترین روش‌های صنعت ایمن کنید.

مشاهده طرح‌های سازمانی
به SAML، لیست سفید IP یا پشتیبانی اختصاصی نیاز دارید؟ با تیم فروش ما تماس بگیرید.

منابع مرتبط

شروع رایگان — 100 تماس/روز، بدون کارت

جریان نهنگ، تأمین مالی، علاقه باز و داده‌های زنجیره‌ای را در 3 صرافی از یک API دریافت کنید. سطح رایگان، بدون نیاز به کارت اعتباری، هر زمان ارتقا دهید.

شروع رایگان →
آزمایش کنسول API زنده → (بدون نیاز به حساب)