سرویس «تمدید توکن» در دسته OAuth و توکن، با گرفتن رفرش توکن یک access token تازه صادر میکند؛ این سرویس برای توکنهای نوع CLIENT-CREDENTIAL و نوع CODE کار میکند. با آن میتوانید پیش از پایان عمر توکن، دسترسی سامانه خود را بدون تکرار مراحل صدور اولیه ادامه دهید.
تمدید توکن چه مشکلی را حل میکند؟
عمر توکن محدود است و این محدودیت بخشی از امنیت دسترسی محسوب میشود، اما در عمل همان محدودیت میتواند جریان کاری را قطع کند: اگر توکن در میانه یک دوره تسویه، یک کار دستهای شبانه یا یک پرونده نیمهتمام اعتبارسنجی منقضی شود، فراخوانیها با خطا برمیگردند و تیم فنی ناچار میشود مسیر صدور توکن را از ابتدا اجرا کند. در جریان توکن پیامکی این هزینه بیشتر هم میشود، چون صدور اولیه به حضور کاربر و وارد کردن کد یکبار مصرف او نیاز داشته است و تکرار آن یعنی مزاحمت دوباره برای مشتری.
تمدید توکن این وابستگی را حذف میکند: سرور شما رفرش توکنی را که در زمان صدور دریافت کرده بود میفرستد و بهجای آن access token تازه، فهرست اسکوپهای مجاز، زمان ساخت و عمر توکن جدید و یک رفرش توکن نو میگیرد. خروجی این سرویس مستقیم به منطق زمانبندی سامانه شما وصل میشود تا توکن همیشه پیش از انقضا جایگزین شود و کاربر یا اپراتور متوجه هیچ وقفهای نشود.
کاربردهای تمدید توکن
- سرویسهای همیشهروشن سمت سرور — سامانهای که بهطور پیوسته استعلام میگیرد، توکن خود را پیش از انقضا تازه میکند و بیوقفه کار میکند.
- جریانهای اعتبارسنجی چندروزه — پروندهای که طی چند مرحله و چند روز تکمیل میشود، با تمدید توکن ادامه پیدا میکند بدون آنکه مشتری دوباره تایید کند.
- کارهای دستهای و گزارشهای دورهای — قبل از شروع پردازش انبوه، اعتبار توکن تازه میشود تا نیمهراه با خطای انقضا متوقف نشود.
- مدیریت دسترسی در جریان توکن پیامکی — توکنهای نوع
CODEکه با رضایت کاربر صادر شدهاند، بدون ارسال پیامک دوباره تمدید میشوند. - سرویسهای حسابمحور بانکی — در تمدید توکن بانک کشاورزی، اطلاعات حساب و بانک همراه درخواست میرود و محدودیتهای مبلغ و تعداد تراکنش در پاسخ بازمیگردد.
مزایای تمدید توکن
- تداوم دسترسی بدون دخالت کاربر — تمدید در سمت سرور انجام میشود و به تایید پیامکی تازه نیازی ندارد.
- پوشش هر دو نوع توکن — هم توکن
CLIENT-CREDENTIALو هم توکنCODEبا همین سرویس تمدید میشوند. - بازگشت کامل مشخصات توکن جدید — اسکوپهای مجاز، کد ملی کاربر، نوع توکن، زمان ساخت و عمر توکن در پاسخ میآید و میتوانید وضعیت دسترسی را دقیق ثبت کنید.
- همراستا با پروتکل OAuth 2.0 — هر تمدید یک رفرش توکن تازه میدهد و چرخه اعتبار را میبندد.
- کاهش خطای زمان اجرا — بهجای مواجه شدن با خطای توکن منقضی، زمانبندی تمدید را از پیش تعیین میکنید.
چه چیزی از تمدید توکن دریافت میکنید؟
جزئیات ورودی، خروجی و نمونه پاسخ در مستندات فنی آمده است.
جریان کار تمدید توکن
- ۱. نگهداری رفرش توکن در زمان صدور — رفرش توکن بازگشتی از توکن Client Credential یا مرحله درخواست توکن پیامکی را در سمت سرور ذخیره کنید.
- ۲. پایش زمان انقضا — با زمان ساخت و عمر توکن، لحظه تمدید را پیش از انقضا مشخص کنید.
- ۳. فراخوانی تمدید — نوع توکن و رفرش توکن را همراه اطلاعات هویتی کلاینت بفرستید.
- ۴. جایگزینی مقادیر ذخیرهشده — توکن و رفرش توکن قدیمی را با مقادیر جدید پاسخ جابهجا کنید.
- ۵. ادامه فراخوانی سرویسها — با توکن تازه، همان سرویسهای مجاز اسکوپ قبلی را فراخوانی کنید.
نحوه شروع تمدید توکن
این سرویس با رویکرد refresh_token و با احراز هویت اطلاعات کلاینت فراخوانی میشود. برای تمدید، اسکوپ جداگانهای درخواست نمیشود؛ اسکوپهای توکن جدید همان اسکوپهای توکن قبلی است و در پاسخ بازگردانده میشود. ابتدا کلاینت بسازید و توکن بگیرید: راهنمای شروع. سپس از مستندات فنی برای پیادهسازی استفاده کنید.
محدودیتها و نکات تمدید توکن
- با توجه به لزوم رعایت دقیق پروتکلهای OAuth 2.0، پس از دریافت access token و رفرش توکن جدید، حتماً از رفرش توکن جدید استفاده کنید؛ نگه داشتن مقدار قبلی باعث میشود تمدید بعدی انجام نشود.
- فرستادن تمام پارامترهای بدنه درخواست الزامی است و نوع توکن باید با نوع توکن اولیه (
CLIENT-CREDENTIALیاCODE) یکسان باشد. - برای توکنهای نوع
CODE، اگر احراز هویت از نوع کد یکبار مصرف پیامکی بوده است، فرستادن نوع احراز هویت اجباری است و نیازی به فرستادن بانک نیست؛ در غیر این صورت فرستادن بانک اجباری است و نوع احراز هویت لازم نمیشود. - در تمدید توکن بانک کشاورزی، فرستادن بانک و شماره حساب الزامی است.
- محدودیت مبلغ هر تراکنش، سقف تعداد تراکنش ماهانه و فهرست حسابهای مجاز تنها برای بانک کشاورزی در پاسخ بازگردانده میشود؛ در سایر موارد به این مقادیر تکیه نکنید.
- تمدید را پیش از انقضای توکن انجام دهید؛ عمر توکن به میلیثانیه و زمان ساخت آن به تاریخ شمسی برمیگردد.
- رفرش توکن اعتبار دسترسی است؛ آن را رمزنگاریشده و فقط سمت سرور نگه دارید و دسترسی به آن را محدود کنید.
سوالات متداول تمدید توکن
تمدید توکن چیست؟
سرویسی است که با دریافت رفرش توکن، یک access token تازه همراه با اسکوپهای مجاز، زمان ساخت، عمر توکن و رفرش توکن جدید صادر میکند تا دسترسی سامانه شما بدون وقفه ادامه یابد.
تفاوت تمدید توکن با گرفتن توکن جدید چیست؟
در گرفتن توکن Client Credential مسیر صدور از ابتدا اجرا میشود، در حالی که تمدید فقط با رفرش توکن موجود انجام میشود و در جریان پیامکی، کاربر را درگیر تایید دوباره نمیکند.
آیا رفرش توکن قدیمی بعد از تمدید هنوز کار میکند؟
برای تمدید بعدی باید از رفرش توکن جدیدی که در پاسخ آمده استفاده کنید؛ مقدار قبلی را جایگزین کنید و نگه ندارید.
توکن پیامکی را هم میتوان تمدید کرد؟
بله. توکنهای نوع CODE که از مرحله درخواست توکن گرفته شدهاند با همین سرویس تمدید میشوند؛ در حالت احراز هویت پیامکی، فرستادن نوع احراز هویت اجباری است.
مستندات فنی این سرویس کجاست؟
صفحه مشخصات API شامل endpoint، پارامترها و نمونه پاسخ است.
چه نوع احراز هویتی لازم است؟
Grant type: refresh_token و احراز هویت درخواست با اطلاعات هویتی کلاینت. جزئیات در راهنمای توکن.
آیا رضایت پیامکی کاربر لازم است؟
خیر. تمدید در سمت سرور و با رفرش توکن انجام میشود؛ رضایت پیامکی تنها در صدور اولیه توکن پیامکی لازم است.
مستندات فنی تمدید توکن
مشاهده مستندات فنی «تمدید توکن» — endpoint، پارامترها، نمونه درخواست و پاسخ.