در این بخش می‌خواهیم چگونگی استفاده از Refresh Token را توضیح دهیم. نوع مجوز Refresh Token زمانی توسط کلاینت استفاده میشود که یک Access Token، منقضی شده باشد.
یک Refresh Token قسمت اصلی OAuth می‌باشد و نوعی Token است که می‌توان از آن برای دریافت Access Token های اضافی استفاده کرد. Refresh Token را می‌توان مانند یک نوع رمز عبور در نظر گرفت. وقتی به یک وب‌سایت دسترسی پیدا می‌کنید و هنوز Session ای ندارید، با نوعی اعتبارنامه یا Token مانند یک رمز عبور وارد سیستم می شوید. این Token با یک Session Token مبادله میشود که می‌توانید برای دسترسی مکرر به منابع موجود در آن وب‌سایت و بدون نیاز به ورود مجدد به سیستم، از آن استفاده کنید. به همین ترتیب می‌توان از یک Refresh Token برای به دست آوردن Token های دیگر که Access Token های با عمر کوتاه نامیده می‌شوند، استفاده کرد. این مهم است زیرا یک برنامه کلاینت اغلب می‌خواهد دوره دسترسی کاربر را بدون نیاز به دوباره وارد شدن به سیستم، افزایش دهد. با استفاده از یک Refresh Token، کلاینت می‌تواند بدون درگیر کردن کاربر، Access Token جدیدی به دست آورد و در نتیجه تجربه کاربر را بهبود بخشد.
اگر سرویس شما Refresh Token ها را به همراه Access Token صادر می‌کند، شما نیاز دارید نوع مجوز را که در این بخش شرح داده شده است پیاده سازی کنید. شکل زیر روند Refresh Token را نشان می‌دهد.
بر اساس شکل، خواهیم داشت:
1- کلاینت به وسیله احراز هویت با Authorization Server و طی کردن یکی از روش های Authorization Grant، Access Token را درخواست می‌کند.
2- Authorization Server، کلاینت را احراز هویت و Authorization Grant را تایید می‌کند و در صورت معتبر بودن، یک Access Token و یک Refresh Token صادر می‌کند.
3- کلاینت با ارائه Access Token یک درخواست محافظت شده را به Resource Server می‌دهد.
4- Resource Server، با ررسی Access Token و معتبر بودن آن، درخواست را پاسخ می‌دهد.
5- مراحل 3 و 4 تا زمان منقضی نشدن Access Token تکرار می‌شوند. ولی در یکی از این درخواست ها متوجه منقضی شدن Access Token خود میشود.
6- از آنجا که Access Token نامعتبر است، Authorization Server خطای نامعتبر بودن Token را برمی‌گرداند.
7- کلاینت به Authorization Server Refresh Token را ارائه می‌دهد و یک Access Token جدید را درخواست می‌کند.
8- Authorization Server، کلاینت را احراز هویت کرده و Refresh Token را بررسی می‌کند و در صورت معتبر بودن، یک Access Token جدید (و به صورت اختیاری ، یک Refresh Token جدید) صادر می‌کند.
به بیان ساده‌تر، مراحل 1 و 2 مشابه قسمت‌های قبلی مستند می‌باشد که یک Access Token صاده شده است. بخش‌های 3و 4 در حقیقت نشان دهنده استفاده از Resource Server با Access Token اولیه می‌باشد. در مراحل 5 و 6، معتبر بودن یا بهتر است بگوییم expire نشدن Access Token بررسی میشود که ممکن است یا با خطا همراه باشد یا نباشد. زمانی که Refresh Token وجود داشته باشد، امکان این فراهم میشود که یک درخواست از نوع Refresh Grant Token ایجاد شود و این دقیقا همان مرحله 7 خواهد بود.
در ادامه مستند، فقط مراحلی که مختص Refresh Token Grant بوده و با دیگر Grant ها تفاوت دارد را ذکر خواهیم کرد. لازم به ذکر است در این مستند از تشریح بخش‌هایی مانند Invalid Token Error اجتناب کرده و صرفا مبحث اصلی را شرح خواهیم داد.
1- پارامترهای درخواست
درخواست Access Token شامل پارامترهای زیر خواهد بود:
· grant_type (پارامتر اجباری): در این روش، این پارامتر باید روی "refresh_token" تنظیم شود.
· refresh_token (پارامتر اجباری): این پارامتر همان Refresh Token ای است که قبلا برای کلاینت صادر شده است.
· scope (پارامتر اجباری): همان میزان دسترسی هست که به کلاینت داده میشود. و در بخش‌های بعد به آن می‌پردازیم . تنها نکته‌ای که وجود دارد این است که مقدار Scope درخواستی نباید شامل scopeهای اضافی باشد که در Access Token اصلی صادر نشده‌اند. به طور معمول، این پارامتر در درخواست قید نمی‌شود. در این صورت سرویس باید Access Token را با همان scope ای که قبلا صادر شده بود، صادر کند.
· Client Authentication (اگر رمز برای کلاینت صادر شده باشد، اجباری است): به طور معمول،Refresh Tokenها فقط با کلاینت های محرمانه استفاده می‌شوند. (در بخش‌های قبلی ذکر شده بود که کلاینت‌های محرمانه برنامه‌هایی هستند که قادر به تایید صحت هویت با Authorization Server هستند و توانایی حفظ محرمانه بودنclient_secret را دارند.)
با این حال، از آنجا که امکان استفاده از Authorization Code بدون Client Secret نیز وجود دارد، ممکن است Grant Refresh Token توسط کلاینت‌هایی که رمز را ندارند نیز استفاده شود. پس اگر یک رمز برای کلاینت صادر شده بود، کلاینت باید این درخواست را تایید کند. (به طور معمول، این سرویس، وجود پارامترهای client_id و client_secret را در درخواست و یا هدر HTTP Basic می‌پذیرد.)
حال اگر رمزی برای کلاینت صادر نشده باشد، هیچ گونه تایید اعتبار کلاینت در این درخواست انجام نمی‌شود.
در زیر یک مثال از درخواست Refresh Grant برای می‌باشد که به Authorization Server ارسال میشود :
POST /oauth/token HTTP/1.1
Host: authorization-server.com
grant_type=refresh_token
&refresh_token=xxxxxxxxxxx
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx
2- تایید Refresh Token Grant
پس از بررسی همه پارامترهای مورد نیاز و تایید اعتبار کلاینت توسط Authorization Server، همان‌طور که پیش‌تر ذکر شد، اگر رمز (secret) برای کلاینت صادر شده باشد، Authorization Server می‌تواند مراحل دیگر درخواست را بررسی کند.
سپس سرور بررسی می‌کند که آیا Refresh Token معتبر است یا منقضی شده است. اگر Refresh Token برای یک کلاینت محرمانه صادر شده بود، این سرویس باید اطمینان حاصل کند که Refresh Token موجود در درخواست، برای کلاینت معتبر یا نایید شده، صادر شده است.
اگر همه چیز تایید شود، این سرویس می‌تواند یک Access Token ایجاد کند و پاسخ دهد. ممکن است سرور در جواب، پاسخ جدیدی را صادر کند، اما اگر پاسخ شامل Refresh Token جدید نشود، آن گاه کلاینت فرض می‌کند که Refresh Token موجود هنوز معتبر است.
پاسخ به Refresh Token Grant همان پاسخی است که در هنگام صدور یک Access Token دارید. شما می‌توانید به صورت اختیاری یک Refresh Token در پاسخ صادر کنید، یا اگر Refresh Token جدیدی را درج نکردید، کلاینت فرض می‌کند که Refresh Token فعلی همچنان معتبر است . به عنوان مثال، یک پاسخ رمز موفقیت آمیز به صورت زیر می‌باشد:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
"token_type":"bearer",
"expires_in":3600,
"refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
"scope":"create"
}
همان‌طور که مشاهده میشود، این پاسخ همانند پاسخ های دیگر Grant ها می‌باشد و در حقیقت در Refresh Token Grant، بر اساس Refresh Token ای که صادر شده بود، در صورت منقضی شدن Access Token، یک درخواست جدید داده شده و Access Token جدید صادر خواهد شد.