OAuth for Data Plan Agent API

مدارک مربوطه

OAuth 2.0 به عنوان RFC 6749 استاندارد شده است. یک سند دقیق در https://oauth.net/2 موجود است. احراز هویت پایه HTTP در بخش 2 RFC 2617 تعریف شده است.

بررسی اجمالی

معمولاً برای دسترسی برنامه های شخص ثالث به منابع محدود شده مانند طرح داده و جزئیات کیف پول، کاربر نهایی (مالک منبع) باید اعتبار خود را با شخص ثالث به اشتراک بگذارد. این امر مشکلات و محدودیت‌های متعددی مانند ذخیره‌سازی اعتبار، تأیید اعتبار رمز عبور، دسترسی گسترده به منابع کاربر نهایی و نشت رمز عبور و غیره را ایجاد می‌کند. OAuth2.0 با معرفی یک لایه مجوز و در نتیجه ایمن کردن و محدود کردن دسترسی به محافظت شده، این مشکلات را برطرف می‌کند. منابع کاربر نهایی

به جای استفاده از اعتبار کاربر نهایی برای دسترسی به منابع محافظت شده مانند جزئیات طرح داده، GTAF یک نشانه دسترسی به دست می آورد. توکن های دسترسی از طرف اعتبارنامه GTAF برای GTAF صادر می شوند. سپس GTAF از رمز دسترسی برای دسترسی به جزئیات طرح داده که توسط DPA میزبانی می شود استفاده می کند.

شکل زیر جریان سطح بالایی از اطلاعات را نشان می دهد:

شکل 1. چکیده جریان OAuth.

دسترسی به توکن ها

توکن های دسترسی، اعتبارنامه هایی هستند که توسط GTAF برای دسترسی به جزئیات طرح داده از DPA حامل استفاده می شود. یک نشانه دسترسی رشته ای است که نشان دهنده مجوز صادر شده برای GTAF است. رشته معمولاً نسبت به GTAF مات است. توکن‌ها محدوده‌ها و مدت زمان دسترسی خاصی را نشان می‌دهند که توسط کاربر نهایی به شرکت مخابراتی اعطا شده و توسط DPA و سرور OAuth حامل اعمال می‌شوند.

توکن دسترسی یک لایه انتزاعی را فراهم می کند و ساختارهای مختلف مجوز (مثلاً نام کاربری و رمز عبور) را با یک نشانه واحد که توسط DPA قابل درک است جایگزین می کند. این انتزاع، صدور توکن های دسترسی محدودتر از مجوز استفاده شده برای به دست آوردن آنها را امکان پذیر می کند، و همچنین نیاز DPA به درک طیف گسترده ای از روش های احراز هویت را حذف می کند.

توکن‌های دسترسی می‌توانند فرمت‌ها، ساختارها و روش‌های مختلف استفاده (مثلاً ویژگی‌های رمزنگاری) بر اساس الزامات امنیتی حامل داشته باشند. GTAF فقط توکن های دسترسی نوع حامل تعریف شده در [ RFC6750 ] را پشتیبانی می کند.

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

GTAF به عنوان یک "کلینت محرمانه" کار می کند و می تواند رمزهای عبور را ایمن نگه دارد. GTAF در حال حاضر فقط از احراز هویت پایه HTTP برای احراز هویت با DPA پشتیبانی می کند. شناسه مشتری با استفاده از الگوریتم رمزگذاری "application/x-www-form-urlencoded" کدگذاری می شود و مقدار کدگذاری شده به عنوان نام کاربری استفاده می شود. رمز عبور با استفاده از همان الگوریتم رمزگذاری شده و به عنوان رمز عبور استفاده می شود.

کلاینت‌های محرمانه مانند GTAF که اعتبار کلاینت‌ها صادر می‌شوند، با سرور OAuth شرکت مخابراتی در حین ارسال درخواست به نقطه پایانی توکن، احراز هویت می‌شوند. احراز هویت مشتری برای: \

• بازیابی از یک کلاینت در معرض خطر با غیرفعال کردن مشتری یا تغییر اعتبار آن، بنابراین مانع از سوء استفاده مهاجم از توکن‌های به‌روزرسانی سرقت شده می‌شود. تغییر یک مجموعه از اعتبار مشتری به طور قابل توجهی سریعتر از باطل کردن کل مجموعه ای از نشانه های به روز رسانی است.
• اجرای بهترین شیوه های مدیریت احراز هویت، که نیاز به چرخش دوره ای اعتبار دارد.

GTAF از پارامتر درخواست "client_id" برای شناسایی خود هنگام ارسال درخواست به نقطه پایانی نشانه استفاده می کند.

قابلیت چرخش اعتبار مشتری از اهمیت ویژه ای برخوردار است. سرور OAuth باید بتواند از دو جفت اعتبار به طور همزمان در حین چرخش پشتیبانی کند و باید قابلیت غیرفعال کردن اعتبارنامه ها را داشته باشد. در یک چرخش اعتبار معمولی:

1. شرکت مخابراتی اعتبارنامه های جدیدی را در سرور OAuth ایجاد می کند و اعتبارنامه ها را به شیوه ای امن به مدیر حساب فنی خود تحویل می دهد.
2. گوگل اعتبار جدید را آزمایش می کند و پیکربندی GTAF را برای استفاده از اعتبار جدید تغییر می دهد.
3. Google به شرکت مخابراتی اطلاع می‌دهد که ممکن است اطلاعات کاربری قدیمی غیرفعال باشد.
4. شرکت مخابراتی اعتبارنامه ها را غیرفعال می کند و به گوگل اطلاع می دهد
5. Google تأیید می کند که اعتبارنامه های قدیمی دیگر عملیاتی نیستند

سرور OAuth باید بتواند از فرآیند چرخش فوق پشتیبانی کند.

نقطه پایان نشانه

نقطه پایانی توکن توسط GTAF برای به دست آوردن یک نشانه دسترسی با ارائه مجوز مجوز یا رمز تجدید استفاده می شود. نقطه پایانی نشانه با هر مجوز مجوز استفاده می شود، به جز نوع اعطای ضمنی (از آنجایی که یک نشانه دسترسی مستقیماً صادر می شود).

در زیر نکاتی وجود دارد که باید هنگام پیکربندی نقطه پایانی توکن در نظر گرفته شوند:

• مکان نقطه پایانی نشانه باید در اسناد سرویس ارائه شود.
• URI نقطه پایانی ممکن است شامل یک مؤلفه پرس و جو قالب‌بندی شده «application/x-www-form-urlencoded» باشد که باید هنگام افزودن پارامترهای پرس و جوی اضافی حفظ شود. URI نقطه پایانی نباید شامل یک جزء قطعه باشد.
• از آنجایی که درخواست‌ها به نقطه پایانی نشانه منجر به انتقال اعتبارنامه‌های متن واضح (در درخواست و پاسخ HTTP) می‌شود، سرور OAuth حامل باید از TLS برای ارسال درخواست‌ها به نقطه پایانی نشانه استفاده کند.
• GTAF هنگام درخواست توکن دسترسی از روش HTTP "POST" استفاده می کند.
• پارامترهای ارسال شده بدون مقدار باید به عنوان حذف شده از درخواست تلقی شوند. سرور OAuth باید پارامترهای درخواست ناشناخته را نادیده بگیرد. پارامترهای درخواست و پاسخ نباید بیش از یک بار درج شوند.
• GTAF فقط توکن های دسترسی نوع حامل را پشتیبانی می کند.

دسترسی به محدوده رمز

نقاط پایانی مجوز و نشانه به مشتری اجازه می دهد تا محدوده درخواست دسترسی را با استفاده از پارامتر درخواست "scope" مشخص کند. به نوبه خود، سرور مجوز از پارامتر پاسخ "scope" استفاده می کند تا مشتری را از محدوده توکن دسترسی صادر شده مطلع کند.

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

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF نیازی به پیاده سازی دامنه ندارد، اما از این ویژگی پشتیبانی می کند. برای اطلاعات بیشتر، به بخش 3.3 RFC 6749 مراجعه کنید.

صدور رمز دسترسی

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

پاسخ موفق

هنگامی که GTAF درخواستی را ارسال می کند، سرور OAuth یک نشانه دسترسی و نشانه بازخوانی اختیاری صادر می کند و با افزودن پارامترهای زیر به نهاد پاسخ HTTP با کد وضعیت 200 (OK) پاسخ را می سازد: \

• access_token: ضروری است. رمز دسترسی صادر شده توسط سرور OAuth. GTAF انتظار دارد نقطه پایانی توکن یک توکن حامل را برگرداند.
• expires_in: الزامی است. طول عمر رمز دسترسی در ثانیه. به عنوان مثال، مقدار "3600" نشان می دهد که رمز دسترسی در یک ساعت از زمان ایجاد پاسخ منقضی می شود. در صورت حذف، سرور OAuth باید زمان انقضا را از طریق روش های دیگر ارائه کند یا مقدار پیش فرض را مستند کند.
• token_type: ضروری است. نوع توکن صادر شده برای اطلاعات بیشتر در مورد انواع مختلف توکن ها، به بخش 7.1 RFC 6749 مراجعه کنید. مقدار به حروف بزرگ و کوچک حساس است. GTAF در زمان نگارش این مقاله فقط از توکن های حامل پشتیبانی می کند.
• refresh_token: اختیاری. نشانه رفرش، که می تواند برای به دست آوردن نشانه های دسترسی جدید با استفاده از همان مجوز مجوز استفاده شود.
• محدوده: اختیاری، در صورت پیاده سازی و یکسان با محدوده درخواست شده توسط GTAF. در غیر این صورت، لازم است.

پارامترها با استفاده از "application/json" در entity-body پاسخ HTTP گنجانده شده اند. پارامترها با افزودن هر پارامتر در بالاترین سطح ساختار، به یک ساختار نشانه گذاری شی جاوا اسکریپت (JSON) سریال تبدیل می شوند. نام پارامترها و مقادیر رشته به عنوان رشته های JSON گنجانده شده است. مقادیر عددی به عنوان اعداد JSON گنجانده شده است. ترتیب پارامترها مهم نیست و می تواند متفاوت باشد.

سرور مجوز باید فیلد هدر پاسخ HTTP "Cache-Control" با مقدار "no-store" را در هر پاسخی که حاوی نشانه‌ها، اعتبارنامه‌ها یا سایر اطلاعات حساس است، و همچنین فیلد سرصفحه پاسخ "Pragma" با مقدار داشته باشد. از "بدون کش".

مثلا:

     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",
       "example_parameter":"example_value"
     }

در زیر چند نکته مهم وجود دارد که باید مورد توجه قرار گیرد:

• GTAF نام مقادیر ناشناخته را در پاسخ نادیده می گیرد.
• اندازه نشانه ها و سایر مقادیر دریافت شده از سرور OAuth تعریف نشده باقی می مانند.
• GTAF باید از فرضیات در مورد اندازه ارزش اجتناب کند. سرور OAuth باید اندازه هر مقداری را که صادر می کند مستند کند.

پاسخ به خطا

اگر درخواست مجوز به هر دلیلی مانند گم شدن، نامعتبر بودن، یا عدم تطابق URI تغییر مسیر، یا اگر شناسه سرویس گیرنده مفقود یا نامعتبر باشد، با شکست مواجه شود، سرور OAuth باید با کد وضعیت HTTP 400 (درخواست بد) پاسخ دهد (مگر اینکه در غیر این صورت مشخص شده باشد) و باید حداقل یکی از پارامترهای فهرست شده در بخش Error Response and Codes را شامل شود.

اعطای مجوز در GTAF

اعطای مجوز، اعتباری است که نشان دهنده مجوز کاربر نهایی (برای دسترسی به منابع محافظت شده آن مانند اطلاعات موجودی داده) است که توسط GTAF برای به دست آوردن رمز دسترسی استفاده می شود.

GTAF از نوع اعطای client_credentials استفاده می کند. در نوع اعطای client_credentials ، GTAF با استفاده از یک درخواست HTTP POST و HTTP Basic Authentication یک توکن درخواست می کند. همه درخواست‌ها از طریق TLS (یعنی HTTPS) ارسال می‌شوند و GTAF نمی‌تواند با یک سرور OAuth بدون گواهینامه معتبر TLS یکپارچه شود. GTAF قادر به عبور از یک محدوده توکن قابل تنظیم است و در صورتی که پیکربندی نشده باشد، از یک محدوده خالی عبور می کند.

GTAF انتظار دارد که یک نشانه دسترسی همراه با مقدار "expires_in" (زمان برای زندگی) برگردانده شود. مقدار expires_in باید حداقل 900 ثانیه باشد و نباید بیشتر از چند ساعت باشد. درخواست توکن جدید نباید باعث شود که توکن های موجود زودتر منقضی شوند.

برای جزئیات بیشتر در مورد انواع مختلف کمک هزینه، به بخش 1.3 RFC 6749 مراجعه کنید.

نمونه درخواست و پاسخ

فرض کنید که GTAF پیکربندی زیر را برای یک سرور OAuth دارد:

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

توجه: راز مشتری برای یک DPA واقعی باید بسیار امن تر از آنچه در مثال نشان داده شده باشد.

برای تولید رشته مجوز، شناسه مشتری، ':'، و رمز عبور به هم پیوسته و با پایه 64 کدگذاری می شوند. این را می توان در یک رابط خط فرمان به صورت زیر تکرار کرد:

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

سپس GTAF با استفاده از این اعتبار، نوع اعطای client_credentials و محدوده پیکربندی شده، یک درخواست HTTPS POST به سرور OAuth می‌کند. برای مثال، درخواست GTAF شبیه به درخواست ایجاد شده توسط:

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

هدرهای استفاده شده توسط GTAF با هدرهای ارسال شده توسط curl مطابقت ندارند، اگرچه هدر مجوز یکسان خواهد بود.

GTAF انتظار پاسخ به این شکل را دارد:

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

در زیر نمونه ای از پاسخ معتبر آورده شده است:

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

توجه: پاسخ باید JSON معتبر باشد.

پاسخ به خطا و کدها

اگر درخواست مجوز از GTAF به هر یک از دلایل ذکر شده در بخش Error Response با شکست مواجه شود، سرور OAuth باید با یک کد وضعیت HTTP 400 (درخواست بد) پاسخ دهد (مگر اینکه در غیر این صورت مشخص شده باشد) و یکی از پارامترهای زیر را با پاسخ شامل شود. :

مثلا: \

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

     {
       "error":"invalid_request"
     }

GTAF انتظار دارد که سرور OAuth از پاسخ های خطای زیر پشتیبانی کند:

کد خطا	واکنش	دلیل
HTTP 400	درخواست_نامعتبر	درخواست فاقد یک پارامتر لازم است، شامل یک مقدار پارامتر پشتیبانی نشده (غیر از نوع اعطا) است، یک پارامتر را تکرار می‌کند، دارای اعتبارنامه‌های متعدد است، از بیش از یک مکانیسم برای احراز هویت با GTAF استفاده می‌کند، یا به شکل دیگری نادرست است.
HTTP 401	invalid_client	احراز هویت مشتری ناموفق بود (مثلاً کلاینت ناشناخته، احراز هویت مشتری شامل نشده است، یا روش تأیید اعتبار پشتیبانی نشده است). سرور OAuth ممکن است یک کد وضعیت HTTP 401 (غیر مجاز) را برگرداند تا نشان دهد کدام طرح‌های احراز هویت HTTP پشتیبانی می‌شوند. اگر سرویس گیرنده سعی در احراز هویت از طریق فیلد هدر درخواست "Authorization" داشته باشد، سرور OAuth باید با یک کد وضعیت HTTP 401 (غیر مجاز) پاسخ دهد و فیلد سرصفحه پاسخ "WWW-Authenticate" را که با طرح احراز هویت استفاده شده توسط کلاینت مطابقت دارد را شامل شود.
HTTP 500	خرابی سرور OAuth

برای جزئیات سایر پاسخ‌هایی که می‌توان برای اشکال‌زدایی استفاده کرد، به بخش 5.2 RFC 6749 مراجعه کنید.