Device Code | سکان آکادمی

یکی دیگر از Grant‌های OAuth 2.0، Device Code می‌باشد. جریان device برای کلاینت‌هایی مناسب است که روی دستگاه هایی قرار دارند که مرورگری ندارند یا این که روش ورود اطلاعات در آن‌ها آسان نیست. (به عنوان مثال کنسول‌های بازی، تلویزیون‌ها، قاب های عکس ‌و...)، اما کاربر نهایی دسترسی جداگانه ای به user-agent بر روی کامپیوتر یا دستگاه دیگر دارد (به عنوان مثال، کامپیوتر رومیزی، لپ‌تاپ، تلفن هوشمند، تبلت یا موارد دیگر).

به جای آنکه کاربر با user-agent برای دریافت دسترسی، تعاملی داشته باشد، کلاینت به کاربر نهایی اعلام می‌کند تا از کامپیوتر یا دستگاه دیگری استفاده کند و برای تایید درخواست دسترسی، به Authorization Server متصل شود. از آنجا که کلاینت نمی‌تواند درخواست‌های ورودی را دریافت کند، Authorization Server را بارها و بارها بررسی می‌کند تا این که کاربر نهایی فرایند تایید را در Authorization Server کامل کند. توجه داشته باشید که جریان Device Code از client secret استفاده نمی‌کند.

شکل زیر روند این روش را نشان می‌دهد که در ادامه به توضیح جزییات آن می‌پردازیم

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

1- در مرحله اول کلاینت درخواست دسترسی از Authorization Server را می‌دهد و client identifier یا همان Client ID خود را در درخواست درج می‌کند. همان‌طور که در کد زیر دیده می‌شود مقدر response_type برابر device_code می‌باشد. به این معنی که به Authorization Server اعلام می‌کند که کلاینت می‌خواهد از روش Device Code روند گرفتن مجوز را طی کند.

POST /token HTTP/1.1
Host: authorization-server.com
Content-Type: application/x-www-form-urlencoded
    
response_type=device_code
&client_id=s6BhdRkqt3

2- Autorization Server، طبق کد زیر، پارامترهای زیر را برای کلاینت ارسال می‌کند:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "verification_uri": "https://authorization-server.com/authorize",
    "user_code": "94248",
    "device_code": "74tq5miHKB",
    "interval": 5
}

3- کلاینت بایدverification_uri و user_code را به کاربر ارائه دهد و به او راهنمایی کند از طریق یک دستگاه دیگر و یا با استفاده از یک مرورگر، به URL ی که در verification_uri مشخص شده مراجعه کرده و user_code را در محلی که اختصاص داده شده است وارد کند.

نتیجه همچنین ممکن است حاوی یک کد QR باشد که دستگاه می‌تواند به کاربر ارائه دهد. این کد QR شامل URL برای بازدید و user_code برای وارد کردن است.

این راهنمایی در دستگاههای مختلف، متفاوت است و ممکن است در بعضی از دستگاهها با محدودیت نمایش داده شود مثالا، در یک تلویزیون هوشمند، نمایش هر دو مورد و متن آموزشی در صفحه نمایش نسبتا آسان است ولی در دستگاهی مانند شکل زیر این محدودیت وجود دارد.

همچنین در پاسخی که از Authorization Server می‌آید ، device_code نیز ارسال می‌شود تا در مراحل بعدی دستگاه از آن استفاده کند ولی عموما این کد به کاربر نمایش داده نمی‌شود.

4- کاربر به آدرسی که به او نمایش داده شده است مراجعه می‌کند و بعد از وارد کردن کد به او اعلام می‌شود که این مرحله ی احراز هویت به پایان رسیده و می‌تواند مرورگر خود را ببندد.

5- در حالی که کاربر نهایی درخواست کلاینت (مرحله 4) را تایید می‌کند (یا آن را رد می‌کند)، کلاینت مرتبا Authorization Server را بررسی می‌کند تا ببیند کاربر نهایی، مرحله تایید کاربر نهایی را انجام داده است یا خیر. فاصله ی هر باربررسی کردن کلاینت برابر است با پارامتر interval که در مرحله ی قبل از Authorization Server دریافت کرده است. کلاینت در این بررسی کردن ها device_code و client identifier خود را در بر دارد.

POST /token HTTP/1.1
Host: authorization-server.com
Content-type: application/x-www-form-urlencoded
 
grant_type=urn:ietf:params:oauth:grant-type:device_code
&client_id= s6BhdRkqt3
&device_code=74tq5miHKB

6- با فرض دسترسی اعطا شده به کاربر نهایی، Authorization Server، Device Code ارائه شده توسط کلاینت را تایید می‌کند و با یک Access Token پاسخ می‌دهد:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "2YotnFZFEjr1zCsicMWpAA",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

اکنون دستگاه می‌تواند از این Access Token برای ایجاد درخواست‌های API از طرف کاربر استفاده کند.

ممکن است قبل از اتمام ورود به سیستم و تایید درخواست، Authorization Server وضعیتی را برگرداند که نشان می‌دهد مجوز هنوز در انتظار است به صورت زیر:

HTTP/1.1 400 Bad Request

{
  "error": "authorization_pending"
}

ناگفته نماند ممکن است بر اساس شرایط مختلف، شاهد خطا‌های دیگری نیز باشیم:

- slow_down : اگر دستگاه خیلی زیاد از حد یا با بازه های کوتاه‌تر، Authorization Server را بررسی کند.

- access_denied : اگر کاربر نهایی درخواست دسترسی را رد کند.

- expired_token : اگر device code منقضی شده باشد. هرچند کلاینت می‌تواند درخواست دهد تا کد جدیدی را دریافت کند.

همچنین در نظر داشته باشید در درخواست هایی که از Authorization Server می‌شود و یا در پاسخ‌هایی که این سرور می‌دهد همانند سایر روش ها، می‌تواند پارامتر scope هم وجود داشته باشد که میزان دسترسی را مشخص می‌کند که در بخش‌های آینده به صورت مجزا به این موضوع می‌پردازیم.